Introducing the AI Agent Spec Validator

We just shipped a free tool for anyone building with AI agents: the Envelope Spec Validator.

Paste your .envelope.json — or any JSON describing an AI agent team — and you get back a scored report across five dimensions, with specific issues, fix suggestions, and AI-powered feedback on every agent prompt.

Why we built it

Designing a multi-agent system involves a lot of decisions that are hard to get right the first time. Does every agent have an access policy? Is the manager agent using a stronger model than the specialists? Are there human review gates before agents write to external systems? Does each prompt actually tell the agent what to produce?

These aren't things you catch by eyeballing JSON. They're things you catch by running the spec against a set of rules — which is what the validator does.

What it checks

The validator scores your spec across five dimensions:

Security — whether each agent has an access policy with defaultAction: "deny", whether rules have reasons, and whether any agent has write or delete access without appropriate controls.

Role clarity — whether prompts are specific enough to guide reliable behaviour, whether the hierarchy is valid (every reportsToKey points to a real agent), and whether a manager exists in multi-agent teams.

Structure — whether the team defines its inputs and outputs, and whether human review gates exist when agents can write to external systems.

Completeness — whether the spec has a readme, description, version, schema reference, and category.

Model hygiene — whether every agent has a model assigned, whether there's appropriate differentiation across agents, and whether manager agents are using a model suited to coordination.

Each dimension scores 0–100, weighted into an overall score with a letter grade.

AI prompt review

The rules-based score runs instantly. In parallel, the validator sends every agent prompt to an AI reviewer that checks for things rules can't catch:

• Does the prompt specify what the agent receives as input?
• Does it define what format to produce as output?
• Is there a completion condition?
• What should the agent do when it can't complete the task?

The review comes back per-agent, collapsed, with specific issues and suggestions. It's not generic advice — it reads the actual prompt and tells you what's missing from it.

Fix with AI

Once the analysis is complete, you can hit Fix with AI. The validator sends your spec and every identified issue to the same model, which returns a corrected version. You can:

• Re-validate the fixed spec immediately to confirm the score improved
• Download the corrected .envelope.json file (free, no account needed)
• Save to workspace to open it directly in Envelope (requires a free account)

Try it

Go to openenvelope.org/validator and paste a spec. If you don't have one handy, the Library has downloadable agent team designs you can validate straight away.

It's free. No account needed to validate or fix.

Frequently Asked Questions

What is the AI agent spec validator?

The validator is a free tool that scores any .envelope.json agent spec across five dimensions: security, role clarity, structure, completeness, and model hygiene. It flags specific issues, explains what to fix, and uses AI to give feedback on every agent prompt.

What does it check?

Security — whether agents have deny-by-default access policies and appropriate controls for write or delete operations. Role clarity — whether prompts are specific enough and the agent hierarchy is valid. Structure — whether inputs, outputs, and human review gates are defined. Completeness — whether the spec includes a description, version, schema reference, and category. Model hygiene — whether model assignments match the reasoning requirements of each role.

Is it free?

Yes. Free to use, no account required. Paste your JSON and get results immediately.

What format does it accept?

Any JSON that describes an AI agent team. It works with .envelope.json files following the Envelope schema, but will also score partial or draft specs and tell you what's missing.