How to make your API usable by AI agents
A checklist ordered by how rarely each item is done, measured across 404 scored developer tools. The rare items are where you separate yourself, and most of them are runtime behavior rather than documentation.
Most advice about making an API agent-ready is a list of things to publish. The measurement says otherwise. We scored 404 developer tools on 41 signals, and the things almost everybody has done are the cheap, visible ones. The things that decide whether an agent can actually run against you in production are largely undone.
This checklist is ordered by how rare each item is, as of September 2026. Rare means two things at once: most competitors have skipped it, and it is probably the reason an agent gave up on somebody.
#The rare things, which is where the leverage is
Document idempotency. 5% of tools do. An agent retries. It retries on timeouts it cannot distinguish from failures, and it retries more often than a human would because retrying is cheap for it. Without an idempotency key, a retried payment charges twice and a retried create makes two records. This is the single largest gap in the dataset and the one with the worst failure mode.
Return rate-limit headers. 9% do. Tell the caller what its limit is, how much is left, and when the window resets. An agent that cannot read this either backs off blindly, which makes your API look slow, or keeps hammering, which gets it banned. Both end with the agent choosing someone else.
Document retry behavior. 9% do. Say which status codes are safe to retry, whether to use exponential backoff, and whether you send Retry-After. An agent guessing at this is writing your reliability policy for you.
Give request and response examples. 12% and 13%. Not a schema alone. Concrete examples for every endpoint, including the error shapes. A parser can generalize from an example far more reliably than from prose describing an example.
Let an agent get credentials programmatically. 13% do. If issuing a key requires a human clicking in a dashboard, an autonomous agent stops at your front door. This is the most common silent elimination in the whole dataset.
Document your errors. 13% do. Every error code, what causes it, and what the caller should do about it. "400 Bad Request" is not documentation. An agent that cannot tell a retryable error from a fatal one will treat all of them as fatal, and you lose the integration on the first hiccup.
Publish a usable OpenAPI spec. 13% score well. Many tools have a spec. Far fewer have one that is complete, current, and actually describes the responses. An out-of-date spec is worse than none, because it is trusted and wrong.
Document your limits. 28% do. Request size, rate, concurrency, timeout, payload caps. An agent plans its work against these numbers when they exist and discovers them by failing when they do not.
Drop the sales call. 30% of tools let you start without one. Every gate that needs a human removes you from consideration by anything autonomous.
#The common things, which are now table stakes
These no longer separate anyone, and skipping them still hurts.
Publishing an llms.txt file is done by 96%. Shipping a CLI, 96%. A TypeScript SDK, 92%. An MCP server, 80%. A Python SDK, 81%. A quickstart, 59%.
The MCP number deserves a comment. An MCP server over an API with undocumented errors and no idempotency does not fix anything. It exposes the same ambiguity through a newer surface, and it can make things worse by putting a friendly tool name on an operation an agent cannot safely retry. Fix the contract, then wrap it.
#Why the order looks like this
The gap between 96% publishing llms.txt and 5% documenting idempotency is the whole finding. One is an afternoon and it is visible on your marketing site. The other is a design decision that shows up only when something fails at three in the morning inside somebody else's agent loop.
Agent-readiness has been treated as a marketing surface. It is a runtime contract. The vendors who work out the difference in the next year will be the ones agents keep choosing, because they will be the ones agents do not get burned by.
#Check where you actually stand
Run a free audit on your domain. It scores all 41 signals in about half a minute and names what failed rather than giving you a grade.
Every number on this page comes from The State of Agent-Readiness, which is computed live from the scored registry and available as a public JSON endpoint with no key. We sell none of the tools in it, including the ones that score above us.