Agent-Ready APIs
Knowledge about what makes an API "agent-ready" for AI agent consumption.
What Agent-Readiness Means
An agent-ready API is one that an AI agent can:
- Discover -- Find the right endpoint for a given task
- Understand -- Construct a valid request without guessing
- Self-heal -- Recover from errors without human intervention
Most APIs are built for human developers who can read docs, interpret ambiguous errors, and make judgment calls. AI agents can't do that. They need explicit metadata, structured errors, and predictable patterns.
The 8 Pillars
Agent-readiness is measured across 8 pillars with 48 total checks. See pillars.md for the complete reference.
| Pillar |
What It Measures |
| Metadata |
operationIds, summaries, descriptions, tags |
| Errors |
Error schemas, HTTP codes, messages, retry guidance |
| Introspection |
Parameter types, required fields, enums, examples |
| Naming |
Consistent casing, RESTful paths, HTTP method semantics |
| Predictability |
Response schemas, pagination patterns, date formats |
| Documentation |
Auth docs, rate limits, external references |
| Performance |
Response times, caching headers, rate limit headers |
| Discoverability |
OpenAPI version, server URLs, contact info, license |
Scoring
- Each check has a severity: Critical (4x weight), High (2x), Medium (1x), Low (0.5x)
- Score is 0-100 based on weighted pass/fail
- Agent Ready = score >= 70% with zero critical failures
- A single critical failure (like missing operationIds) means "not agent-ready" regardless of total score
When to Suggest Analysis
Suggest running the readiness analyzer when:
- User says "is my API agent-ready?" or "ready for AI agents?"
- User asks "what's wrong with my API?"
- User mentions building an AI agent that consumes their API
- User asks about MCP server compatibility
- User wants to improve their API for LLM tool use
- User mentions they're building tools for Claude, GPT, Gemini, or other AI models
How to Interpret Scores
| Score |
Verdict |
What It Means |
| 90-100 |
Excellent |
API is highly agent-compatible. Minor improvements only. |
| 70-89 |
Agent Ready |
Meets the bar. Some improvements recommended. |
| 50-69 |
Needs Work |
Agents will struggle. Address critical and high issues. |
| 0-49 |
Not Ready |
Significant gaps. Agents will fail frequently. |
Common Quick Wins
These fixes have the highest impact-to-effort ratio:
- Add operationIds to every endpoint (+8-15 points). Agents use these to select endpoints.
- Define error response schemas (+5-10 points). Agents need to parse and recover from errors.
- Add parameter examples (+3-5 points). Agents use examples as templates for valid requests.
- Document rate limits (+3-5 points). Agents need to know their constraints.
- Use consistent naming (+2-4 points). Agents predict URL patterns from names.
1---2name: cursor-plugin-postman-agent-ready-apis3description: Knowledge about AI agent API compatibility. Use when user asks about API readiness, agent compatibility, or wants to improve their API for AI consumption.4---56# Agent-Ready APIs78Knowledge about what makes an API "agent-ready" for AI agent consumption.910## What Agent-Readiness Means1112An agent-ready API is one that an AI agent can:131. **Discover** -- Find the right endpoint for a given task142. **Understand** -- Construct a valid request without guessing153. **Self-heal** -- Recover from errors without human intervention1617Most APIs are built for human developers who can read docs, interpret ambiguous errors, and make judgment calls. AI agents can't do that. They need explicit metadata, structured errors, and predictable patterns.1819## The 8 Pillars2021Agent-readiness is measured across 8 pillars with 48 total checks. See `pillars.md` for the complete reference.2223| Pillar | What It Measures |24|--------|-----------------|25| **Metadata** | operationIds, summaries, descriptions, tags |26| **Errors** | Error schemas, HTTP codes, messages, retry guidance |27| **Introspection** | Parameter types, required fields, enums, examples |28| **Naming** | Consistent casing, RESTful paths, HTTP method semantics |29| **Predictability** | Response schemas, pagination patterns, date formats |30| **Documentation** | Auth docs, rate limits, external references |31| **Performance** | Response times, caching headers, rate limit headers |32| **Discoverability** | OpenAPI version, server URLs, contact info, license |3334## Scoring3536- Each check has a severity: Critical (4x weight), High (2x), Medium (1x), Low (0.5x)37- Score is 0-100 based on weighted pass/fail38- **Agent Ready** = score >= 70% with zero critical failures39- A single critical failure (like missing operationIds) means "not agent-ready" regardless of total score4041## When to Suggest Analysis4243Suggest running the readiness analyzer when:44- User says "is my API agent-ready?" or "ready for AI agents?"45- User asks "what's wrong with my API?"46- User mentions building an AI agent that consumes their API47- User asks about MCP server compatibility48- User wants to improve their API for LLM tool use49- User mentions they're building tools for Claude, GPT, Gemini, or other AI models5051## How to Interpret Scores5253| Score | Verdict | What It Means |54|-------|---------|---------------|55| 90-100 | Excellent | API is highly agent-compatible. Minor improvements only. |56| 70-89 | Agent Ready | Meets the bar. Some improvements recommended. |57| 50-69 | Needs Work | Agents will struggle. Address critical and high issues. |58| 0-49 | Not Ready | Significant gaps. Agents will fail frequently. |5960## Common Quick Wins6162These fixes have the highest impact-to-effort ratio:63641. **Add operationIds to every endpoint** (+8-15 points). Agents use these to select endpoints.652. **Define error response schemas** (+5-10 points). Agents need to parse and recover from errors.663. **Add parameter examples** (+3-5 points). Agents use examples as templates for valid requests.674. **Document rate limits** (+3-5 points). Agents need to know their constraints.685. **Use consistent naming** (+2-4 points). Agents predict URL patterns from names.
KunanonJ