Why it matters
Agents don’t behave like human developers. A human developer who hits a confusing endpoint reads the docs, checks Slack, or asks a teammate. An agent doesn’t do any of that by default — it defaults to confidence over curiosity, tries something based on pattern matching, and only backs off to documentation after it fails. That means the API itself has to carry the burden that used to be split between the API and a patient human reader.
Emmanuel’s framing for this, in his own words: “Keep it simple. Keep it standard. No surprises. Name it well. Describe it well. Be boring. Agents run on pattern matching.” Boring, in this context, is the compliment. An API that surprises a human developer for half a second is an API that sends an agent down the wrong path entirely, because the agent has no instinct to say “that’s odd, let me double-check.”
A concrete example: a response field named activeUserCount is instantly understood by an agent. A response field named AUC forces the agent to guess or make an extra call to verify what it means — and every extra call is wasted time, wasted tokens, and a new chance to get it wrong.
AI-Ready APIs sit at the base of the Agent Access Stack. Everything an agent might use to reach your product (an MCP server, a CLI, a Skill) is a wrapper around your API. If the underlying API is not ready for agents, nothing built on top of it will be either.
How to apply it
Run your API against Emmanuel’s free 12+2 checklist (12 insights, 2 pitfalls):
- Assume agents skip your spec for well-known API shapes and rely on training data — accuracy matters most for anything novel.
- Write descriptions that match your schema exactly; agents trust what you say over what you define.
- Return structured, specific errors (RFC 9457 Problem Details) that name the exact field and reason, so an agent can self-correct in one retry.
- Give every collection resource a list endpoint — agents can’t guess IDs, they need a starting point.
- Design for idempotency, since agents will retry.
- Avoid universal search endpoints (
POST /search) — they invite hallucinated queries; use per-resource filters instead. - Signal deprecation with machine-readable headers (RFC 9745 / RFC 8594), because agents fail silently on breaking changes they can’t detect.
Full checklist: Build AI-Ready APIs — API Checklist (free). Go deeper in Build AI-Ready API Products With MCP.
FAQ
What makes an API "AI-ready" instead of just well-documented?
Good documentation helps a human who's willing to read it. AI-readiness means the API is self-explanatory enough that an agent, which usually won't read the docs first, still succeeds — through naming, error design, and structure, not just prose.
Do I need an MCP server to have an AI-ready API?
No. MCP, CLI tools, and Skills are all wrappers on top of your API. If your API is agent-ready, those layers become much easier to build; if it isn't, wrapping it in MCP just moves the same problems one layer up.
Is this the same as passing an OpenAPI linter?
Not entirely. Linters catch structural issues (missing examples, unused schemas) but can't tell you if your naming is confusing or your error messages actually help an agent recover. Emmanuel's checklist specifically warns against blindly trusting automated readiness-scoring tools for this reason.
What's the single most common mistake?
Vague or misleading descriptions. Emmanuel's checklist point #2: "descriptions can override schema" — if your endpoint description says "search by email" but the schema also accepts a name field, the agent will only try email, because it trusts what you wrote more than what you defined.
Where do I start if I've never audited my API for agents?
Start with the free checklist above, then read What Agents Want from Your Product to run a live audit against your own API.