AI readiness
AI Readiness measures how clearly an API specification describes the tools an agent can call. Use it to find missing context and improve the spec before testing real agent workflows.
Why agents need more than a valid spec
Agents rely on operation descriptions, schemas, and constraints to choose tools and construct arguments. Gaps can produce incorrect calls or unnecessary retries:
- No request body schema → the agent invents a payload shape, and your API rejects it — or worse, accepts it.
- No description → the agent picks tools by name alone, and
POST /process gets called for everything. - No response schema → the agent cannot interpret what came back, so it guesses, retries, and burns tokens.
Validity is table stakes. Readiness is whether a model can ground itself in your API without a human in the loop — and that is what Elva scores.
The readiness check on every MCP server
The MCP readiness panel draws from the collection's quality report, primarily the AI Readiness category. It is a collection-level assessment, so review findings alongside the operations selected for your MCP server.
Finding status | Readiness display |
Fail | Error: inspect and address the finding. |
Partial | Warning: review the incomplete cases. |
NotApplicable | Omitted from the readiness issue list. |
Pass | The evaluated requirement is satisfied. |
Grades use the shared scoring thresholds: A ≥84, B ≥74, C ≥64, D ≥52, otherwise F. If the AI Readiness category is N/A, the panel can fall back to the overall collection score and grade. Inspect the full report and its coverage before interpreting that fallback as AI-specific evidence.
Readiness is a specification-quality signal. It does not guarantee correct model behavior or enforce your API's authorization rules. Test selected tools using realistic prompts and consumer permissions.
AI Readiness in the spec score
AI Readiness contributes 20% of the overall score. It evaluates nine check families:
Check | What to improve |
ai-op-ids | OperationId Quality |
ai-op-semantics | Semantic Operation Descriptions |
ai-context-anchors | LLM Context Anchors |
ai-schema-richness | Schema Field Metadata |
ai-schema-discoverability | Schema Discoverability |
ai-parameter-constraints | Parameter Constraint Coverage |
ai-enum-documentation | Enum Documentation |
ai-implicit-enums | Implicit Enum Coverage |
ai-format-specification | Format Specification |
Improving the collection specification updates the evidence used by both quality scoring and MCP readiness. Publish or rebuild the MCP server separately when you want changed tool definitions to reach connected clients.
Raise the grade in one pass
Step | Action |
1. Name operations | Use unique, descriptive operationId values and summaries. |
2. Describe behavior | Explain purpose, important parameters, response fields, and side effects. |
3. Complete schemas | Describe request bodies where applicable and response bodies where returned; bodyless responses such as 204 do not need an invented body. |
4. Constrain inputs | Document actual enum values, formats, ranges, and their meaning. |
5. Rescore and test | Review coverage and findings, publish the intended definition, and test the resulting tools. |
Keep examples consistent with your API's real behavior. A higher score should come from clearer, more accurate documentation, not from adding unsupported fields or constraints.
Where to go next
Spec quality & scoring
The full engine: 30+ checks, four weighted categories, and how a percentage becomes a grade.
Hosted MCP servers
Where the readiness check runs: select operations, set auth, and deploy an agent-callable server.
On this page
- AI readiness