Agent-Ready APIs
An "agent-ready" API is one that an AI agent can discover, understand, call correctly, and recover from errors without human intervention. Most APIs aren't there yet.
When to Suggest the Analyzer
If the user mentions any of these, suggest running the readiness-analyzer agent:
- "Is my API agent-ready?"
- "Can AI agents use my API?"
- "Scan my API" / "Analyze my spec"
- "What's wrong with my API for AI?"
- "How agent-friendly is my API?"
- "Improve my API for AI agents"
What Gets Evaluated
The analyzer checks 48 items across 8 pillars:
| Pillar |
What It Measures |
| Metadata |
operationIds, summaries, descriptions, tags |
| Errors |
Error schemas, codes, messages, retry guidance |
| Introspection |
Parameter types, required fields, enums, examples |
| Naming |
Consistent casing, RESTful paths, HTTP semantics |
| Predictability |
Response schemas, pagination, date formats |
| Documentation |
Auth docs, rate limits, external links |
| Performance |
Rate limit headers, cache, bulk endpoints, async patterns |
| Discoverability |
OpenAPI version, server URLs, contact info |
Scoring
- Critical checks (4x weight): Blocks agent usage entirely
- High checks (2x weight): Causes frequent agent failures
- Medium checks (1x weight): Degrades agent performance
- Low checks (0.5x weight): Nice-to-have improvements
Agent Ready = score of 70% or higher with zero critical failures.
Interpreting Results
- 90-100%: Excellent. Agents can use this API reliably.
- 70-89%: Agent-ready. Minor improvements possible.
- 50-69%: Not agent-ready. Key issues need fixing.
- Below 50%: Significant work needed. Focus on critical failures first.
See pillars.md in this skill folder for the full check reference.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: 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. Use when this capability is needed.4---56# Agent-Ready APIs78An "agent-ready" API is one that an AI agent can discover, understand, call correctly, and recover from errors without human intervention. Most APIs aren't there yet.910## When to Suggest the Analyzer1112If the user mentions any of these, suggest running the readiness-analyzer agent:13- "Is my API agent-ready?"14- "Can AI agents use my API?"15- "Scan my API" / "Analyze my spec"16- "What's wrong with my API for AI?"17- "How agent-friendly is my API?"18- "Improve my API for AI agents"1920## What Gets Evaluated2122The analyzer checks 48 items across 8 pillars:2324| Pillar | What It Measures |25|--------|-----------------|26| Metadata | operationIds, summaries, descriptions, tags |27| Errors | Error schemas, codes, messages, retry guidance |28| Introspection | Parameter types, required fields, enums, examples |29| Naming | Consistent casing, RESTful paths, HTTP semantics |30| Predictability | Response schemas, pagination, date formats |31| Documentation | Auth docs, rate limits, external links |32| Performance | Rate limit headers, cache, bulk endpoints, async patterns |33| Discoverability | OpenAPI version, server URLs, contact info |3435## Scoring3637- **Critical checks (4x weight):** Blocks agent usage entirely38- **High checks (2x weight):** Causes frequent agent failures39- **Medium checks (1x weight):** Degrades agent performance40- **Low checks (0.5x weight):** Nice-to-have improvements4142**Agent Ready = score of 70% or higher with zero critical failures.**4344## Interpreting Results4546- **90-100%:** Excellent. Agents can use this API reliably.47- **70-89%:** Agent-ready. Minor improvements possible.48- **50-69%:** Not agent-ready. Key issues need fixing.49- **Below 50%:** Significant work needed. Focus on critical failures first.5051See `pillars.md` in this skill folder for the full check reference.5253---54> Converted and distributed by [TomeVault](https://tomevault.io/claim/postman-devrel) — claim your Tome and manage your conversions.55<!-- tomevault:4.0:skill_md:2026-04-14 -->
tomevault-io