Do I need API experience to use this checklist?

Some familiarity helps. You should understand what an API is, what an endpoint is, and what a response looks like. You don't need to have shipped an API yourself to apply these 12 items.

My API already has good docs and a solid OpenAPI spec. Do I still need this?

That's exactly the assumption this checklist challenges. Agents routinely skip good docs and a solid spec — they guess from training data, follow descriptions over schema, and only fall back to the spec when the API is unfamiliar. Good docs help humans. Agents play by different rules.

Can't I just run an automated API readiness scoring tool instead of going through this manually?

You can, but validate what it tells you. Scoring tools can inflate gaps by dereferencing $refs and counting reused schemas multiple times, and they can miss that property-level examples compose into full responses. One spec with 95% descriptions and 100% functional examples scored 38% on a tool we tested. Use scoring as a starting point, not the verdict — check findings against real agent behavior.

How is this different from a full agent-readiness course?

This checklist is the diagnostic layer — 12 things to check and 2 traps to avoid, in one pass. A full course goes further: it covers MCP servers, redesigning APIs for agent use, and building the tooling to fix what the checklist finds. Start here if you want to know where you stand first.

Checklist

12 Things Every API Needs to Be Agent-Ready

Agents skip your docs, trust descriptions over schema, and retry blind. Here are the 12 things an API needs to survive that, plus 2 traps to avoid.

Why this list exists

Most APIs were built for human developers, and they quietly break when agents try to use them instead. The failures aren’t loud. An agent doesn’t throw an error and stop — it guesses, retries, follows a description instead of a schema, or gives up and hallucinates an endpoint that doesn’t exist. Your AI-ready API looks fine in the dashboard. It’s failing in ways you can’t see until you go looking.

The 12 items below come from testing real agents against real APIs — not theory about what agents “might” do. Each one is a specific, checkable thing you can look at in your own API today. For the larger surface decision, pair this with the MCP vs REST API comparison.

The 2 pitfalls to avoid

Beyond the 12 items, two traps show up often enough to call out on their own.

Universal search endpoints are a hallucination factory. A single POST /search that accepts anything is hard for an agent to use correctly, because there’s nothing in the shape of the endpoint to guide it. Per-resource filters are self-documenting — GET /orders?status=active tells the agent exactly what’s possible. A universal search endpoint only makes sense if search itself is your product.

Don’t blindly trust automated readiness scoring tools. They can inflate description and example gaps by dereferencing $refs and counting reused schemas more than once. They can miss that property-level examples compose into full responses. They can flag conventional things — like X-RateLimit headers or API key auth — as gaps without weighing convention or context. A spec that’s 95% described and 100% functionally exampled scored 38% on one tool. Always check a scoring tool’s findings against the actual spec and real agent behavior before you act on them.

How to use this

Pick one of your APIs. Go through the 12 items above one at a time and note where it falls short. You don’t need all 12 fixed before you ship anything — a handful of the most agent-relevant items, specific to your API, is enough to start. The two pitfalls are worth a five-minute gut check on their own: do you have a universal search endpoint, and have you ever taken a scoring-tool number at face value without checking it against the spec? If you need to choose where to start, use how to determine which APIs to make agent-ready.

The common thread across all 12 is the same: be boring. Agents run on pattern matching. They’re trained on what most APIs do, and they default to standards, conventions, and RFCs. They won’t figure out your clever exception or adapt to your one non-standard field. Every quirk is a place an agent can fail — quietly, and without telling you. That is why every MCP server, CLI, or skill should inherit from a boring, reliable API foundation.

Next step

Where to take this next

Working through this with your team? Team training — a private program that gets product, platform, and engineering aligned on what to ship for agents. Learning on your own? Compare the courses.

FAQ

Do I need API experience to use this checklist?: Some familiarity helps. You should understand what an API is, what an endpoint is, and what a response looks like. You don't need to have shipped an API yourself to apply these 12 items.
My API already has good docs and a solid OpenAPI spec. Do I still need this?: That's exactly the assumption this checklist challenges. Agents routinely skip good docs and a solid spec — they guess from training data, follow descriptions over schema, and only fall back to the spec when the API is unfamiliar. Good docs help humans. Agents play by different rules.
Can't I just run an automated API readiness scoring tool instead of going through this manually?: You can, but validate what it tells you. Scoring tools can inflate gaps by dereferencing $refs and counting reused schemas multiple times, and they can miss that property-level examples compose into full responses. One spec with 95% descriptions and 100% functional examples scored 38% on a tool we tested. Use scoring as a starting point, not the verdict — check findings against real agent behavior.
How is this different from a full agent-readiness course?: This checklist is the diagnostic layer — 12 things to check and 2 traps to avoid, in one pass. A full course goes further: it covers MCP servers, redesigning APIs for agent use, and building the tooling to fix what the checklist finds. Start here if you want to know where you stand first.