Agent-Ready APIs: 9 Design Rules for AI Agent Callers
How to design APIs that AI agents call safely: OpenAPI written for models, curated MCP tools, idempotency keys, RFC 9457 errors, pagination, rate limits.
On 28 July 2026 the Model Context Protocol published its 2026-07-28 specification. Its tools chapter states plainly what API teams had been learning the hard way: a tool's error message is not written for a human. It is written for a model, and clients should hand it to the model "to enable self-correction". Meanwhile Azure API Management, Amazon Bedrock AgentCore Gateway and frameworks such as FastMCP made it a few clicks to turn an existing REST API into agent tools.
So every API team now gets the same ticket: "make our API work with agents". Exporting the OpenAPI description to MCP works in the demo. In production the agent picks the wrong operation, creates the same ticket twice after a timeout or drowns in a 400-item list. This guide is for CTOs, API and platform leads, and architects who own that decision. We set out nine design rules, show what we measured in 127 public OpenAPI descriptions, and give you a checklist for your own API.
TL;DR / Key takeaways
- Generate, then curate. OpenAPI-to-MCP converters are a starting point. FastMCP's own docs say models do significantly better with curated servers than with auto-converted ones. Ship task-shaped tools, not one tool per endpoint.
- Agents retry, so writes must be idempotent. Timeouts, ambiguous errors and "let me try again" loops all resend writes. An
Idempotency-Keyon every unsafe POST is cheap insurance. - Errors are prompts. RFC 9457 problem details with a stable type, the failing field and a retry signal let the agent fix its own call. A bare
400 Bad Requestsends it into a loop. - Public API descriptions are not ready. In our sample, none of 127 descriptions declared
application/problem+json, only one of seven flagship APIs declared an idempotency key, and the median long-tail spec had no examples. - Bound everything. Cursor pagination, filters, response budgets and agent-aware rate limits protect context windows and backends. Contract first, then gateway.
Download: Editable draw.io file · Open in diagrams.net · Chart data (CSV)
Why this matters now
Agents already call your APIs, designed for them or not. Postman's 2025 State of the API Report, a survey of more than 5,700 developers, architects and executives, found that 89% of developers use AI but only 24% design APIs for AI agents. Sixty per cent still design primarily for humans, and 51% of developers worry about unauthorised or excessive API calls from AI agents.
The tooling closed the gap from the other side. Azure API Management exposes selected operations of a managed REST API as remote MCP tools. Amazon Bedrock AgentCore Gateway converts OpenAPI, Smithy and Lambda targets into MCP tools and adds semantic tool search. FastMCP's from_openapi() turns every route into a tool by default.
The plumbing is solved; the design is not. An agent reads your descriptions literally, guesses arguments, retries when unsure and pays for every token you return. Most of the fix belongs in the API contract.
The nine design rules, zone by zone
The numbers match the callouts in the hero diagram. Rules ①, ④, ⑤ and ⑧ live in your API, rules ②, ③, ⑥ and ⑦ in the adapter, and ⑨ spans all three zones.
① Write the contract for a model
Your OpenAPI description is now a prompt.
- Stable, verb-first
operationIds. They become tool names:createRefundbeatspost_v2_refunds_by_id. MCP recommends names of 1–128 characters from letters, digits, underscore, hyphen and dot. - Descriptions that say when, not just what. "Creates a refund for a captured payment. Use only after the customer confirmed." Anthropic's guidance is to write tool descriptions as you would for a new hire and to name parameters unambiguously:
user_id, notuser. - Enums, formats and examples. Each free-text field turned into an enum removes a class of malformed arguments.
- Error responses with schemas. If the contract does not describe errors, neither the adapter nor the model can use them. Our enterprise API design principles cover the human-facing basics this builds on.
OpenAPI 3.1 is the floor because it aligns with JSON Schema 2020-12, the dialect MCP tool schemas default to. OpenAPI 3.2.0, published on 19 September 2025, adds the QUERY method for safe searches with a request body and better streaming support. Adopt it when your tooling does.
② Curate a task-shaped tool surface
This is where most agent projects go wrong. Export 150 operations one-to-one and the model faces 150 near-identical choices, with its context full of schemas before the user has spoken.
Anthropic's September 2025 guidance argues for fewer, workflow-shaped tools, such as one scheduling tool instead of separate list-users, list-events and create-event tools, and for namespacing (asana_search, jira_search) when several servers meet in one client.
Then mark behaviour. MCP tool annotations carry readOnlyHint (default false), destructiveHint (default true), idempotentHint (default false) and openWorldHint (default true). An unannotated tool is therefore treated as a destructive, non-idempotent write. Set them honestly: the spec warns that clients must treat annotations from untrusted servers as untrusted. They drive the approval UI, not a security boundary. Add an outputSchema so clients can validate structuredContent.
③ Give every call an identity and a scope
An agent call has two principals: the user it acts for and the agent itself. Authorisation and audit need both. For MCP that means OAuth with audience-bound tokens via the RFC 8707 resource parameter, and fresh tokens for downstream calls rather than forwarded ones. Our MCP authorization deep dive walks through the flow and our guide to AI agent identity covers token exchange.
For API design the rule is simpler: scope per tool, not per API. A search tool should not run on a token that can issue refunds. The 2026-07-28 spec explicitly lets tools/list vary by the authorisation presented, so an agent with a read scope need not even see the write tools.
④ Make every unsafe write idempotent
Agents retry. Timeouts, gateway 502s, ambiguous errors and model loops all produce a second POST: harmless for a search, an incident for a payment.
The fix is an Idempotency-Key header: one unique key per logical operation, reused on every retry, with the server storing and replaying the first result. The IETF HTTPAPI draft (revision 08, 22 October 2026, still an Internet-Draft) suggests 400 for a missing key, 422 for a key reused with a different payload and 409 while the first request is in flight. Stripe accepts keys of up to 255 characters on all POST requests, may prune them once they are at least 24 hours old on its v1 API, and rejects a retry whose parameters differ from the original.
The adapter, not the model, should derive the key from the task step; models do not reliably remember UUIDs. Set idempotentHint: true only if the server enforces it.
⑤ Return errors that teach
The MCP specification splits failures in two. Protocol errors cover unknown tools and malformed requests. Tool execution errors, flagged with isError: true, carry "actionable feedback that language models can use to self-correct". Its own example: "Invalid departure date: must be in the future."
Design REST errors so the adapter can produce that sentence. RFC 9457 (July 2023, replacing RFC 7807) defines application/problem+json; for agents we add three conventions:
- A stable
typeURI per error class, so the adapter can map it and you can count it. - A
detailthat names the field, the rule and a valid example. "currencymust be an ISO 4217 code such asEUR" beats "validation failed". - An explicit retry signal, such as an extension member
retryable: false, so agents stop resending the same bad call.
Keep stack traces and internal identifiers out of detail.
⑥ Paginate and shape responses for a context window
A 2,000-row JSON array is a denial-of-service attack on a context window. Anthropic recommends "some combination of pagination, range selection, filtering, and/or truncation" with sensible defaults, and notes that Claude Code caps tool responses at 25,000 tokens by default. In its worked example a concise response took 72 tokens against 206 for the detailed one, about a third.
For collections: opaque cursors, not page numbers (MCP itself uses cursor and nextCursor), a small default page size with a hard maximum, filters, names next to IDs, and a has-more flag. When you truncate, tell the agent how to narrow the query.
⑦ Rate-limit by agent, and make the limit legible
One looping agent can out-call a whole team, and a limit per IP or subscription key cannot tell it from everyone else on that key.
Set budgets per agent identity, per end user and per expensive tool. Return 429 Too Many Requests with Retry-After. The IETF RateLimit and RateLimit-Policy fields (draft 11, May 2026, not yet an RFC) let you advertise remaining quota before the client hits the wall. The MCP spec says servers must rate-limit tool invocations; in API Management, rate-limit-by-key policies apply to an MCP server's tools as they do to APIs.
⑧ Never block on long-running work
MCP clients are told to enforce timeouts. A three-minute synchronous call times out, the agent retries, and without rule ④ you have two exports running.
Use 202 Accepted with a status resource the agent can poll. In MCP, return an explicit handle from a start tool and accept it in a status tool. The 2026-07-28 spec recommends this for cross-call state, with the handle's lifetime stated in the tool description and an expired handle returning a tool error the model can recover from.
⑨ Put approval and audit where the damage is
The MCP spec says a human should always be able to deny tool invocations. Your API makes that practical: dry-run modes for destructive operations, prepare and confirm steps for high-value actions, and a per-call audit record of user, agent, tool call ID, idempotency key and outcome. Our article on human-in-the-loop approval gates covers the runtime side.
What the numbers say
How far are today's API descriptions from these rules? We drew 120 providers at random (seed 44) from the APIs.guru OpenAPI Directory, one description each, 9,006 operations in total. These are directory snapshots dated 2017 to 2023, so read them as the long tail. We also checked seven current vendor descriptions, fetched on 15 November 2026: Stripe, GitHub, Twilio (2010 API), Box, PagerDuty, Jira Cloud and Adyen Checkout v72. The sampling script is published. It measures what the description declares; an API can behave better than its description.
The basics are mostly there; the agent-specific parts are missing. Every flagship and the median long-tail spec give every operation an ID, and six of seven flagships carry examples on more than 80% of operations. The long tail does not: its median spec has no examples and no 4xx error schema.
Nobody declares problem details, and almost nobody declares 429. None of the 127 descriptions declared application/problem+json. Among the flagships only PagerDuty documents 429 on most operations; in the long tail, 9 of 120 specs do so on 80% or more.
Idempotency is invisible. Adyen Checkout declares an Idempotency-Key header on 88% of its POST operations. No other description in the sample declares one. Stripe supports keys on every POST, but its description does not declare the header, so a generated adapter will never send one unless someone adds it.
The second grid is our analysis, not measured data. Each rule fully stops only one of the eight failure modes, so no single rule is enough. The rules that stop the expensive ones, duplicate side effects and over-privileged actions, are ③, ④ and ⑨, and a generated adapter gives you none of them.
In a recent engagement…
Earlier this year a European insurer asked us to review an internal claims assistant built on its existing claims API. The team had done what the tooling makes easy: import the API into the gateway, export every operation as an MCP tool and point an agent at it. The demo was convincing.
Production was not. The agent often picked a legacy search over the current one because their descriptions were near-identical. A slow document-generation endpoint timed out, the agent retried, and claim handlers found duplicate letters in the file. Generic 400 errors made the agent resend the same payload until it hit a per-subscription rate limit that throttled every other consumer too.
None of the fixes was clever. A handful of task-shaped tools replaced the export; legacy operations were excluded. The adapter generated idempotency keys from the tool call ID, document generation moved to 202 Accepted, errors became problem details with a retry flag, and limits were keyed by agent and user. The hardest decision was who owns tool descriptions: the API team, reviewed like code.
The agent-readiness checklist
Use it as a review gate before exposing any API to agents.
| Rule | Minimum bar | How to test it |
|---|---|---|
| ① Contract | OpenAPI 3.1+, verb-first operationId, 40+ character description per operation, enums, examples, error schemas | Lint with Spectral or Redocly; run our sampling script on your description |
| ② Tool surface | Task-shaped tools; legacy and admin operations excluded; namespaced names; annotations and outputSchema | Tool-selection evals in CI: prompts with the expected tool |
| ③ Identity | Audience-bound OAuth tokens; scope per tool; user and agent both identifiable | Call each tool with an under-scoped token; expect 403 and no tool listed |
| ④ Idempotency | Idempotency-Key on every unsafe POST, generated by the adapter, retained 24 h or more | Replay a request, then replay it with a changed body; expect one effect and a 422 |
| ⑤ Errors | application/problem+json; stable type URIs; field-level detail; retry signal | Fuzz arguments; the agent should self-correct within two attempts |
| ⑥ Responses | Cursor pagination; default page size of 50 or fewer; filters; concise mode; has-more flag | Measure the token size of the largest default response |
| ⑦ Rate limits | Budgets per agent and per user; 429 + Retry-After; per-tool limits on expensive tools | Load test with a looping agent; other consumers must be unaffected |
| ⑧ Long work | Nothing synchronous beyond the client timeout; 202 + status resource or handle | Drop the connection mid-call and retry; expect one job |
| ⑨ Approval and audit | Dry-run for destructive tools; approval for high-value actions; audit record per call | Reconstruct one call end to end from the audit log alone |
Page size and retention are our defaults, not standards.
Governance for European enterprises
No EU regulation addresses API design for agents directly, but several apply to what an agent does through your API.
GDPR. Every field a tool returns lands in a model's context and often reaches a model provider acting as your processor. Data minimisation (Article 5(1)(c)) and data protection by design (Article 25) are the legal names for rule ⑥. Keep personal data out of error detail and idempotency keys.
NIS2. Article 21 of Directive (EU) 2022/2555 requires access control policies and incident handling. Scoped, logged and revocable agent identities (rules ③ and ⑨) are how you evidence that for non-human callers.
DORA. A financial entity's ICT risk-management framework under Regulation (EU) 2022/2554 should cover any agent with write access to a core API.
EU AI Act. Most agents calling your API are not high-risk AI systems. Where one is, the Annex III obligations, including logging and human oversight, apply from 2 December 2027 after Regulation (EU) 2026/1744 deferred them. Rule ⑨'s audit record is the raw material either way.
A pragmatic adoption path
- Weeks 1–2: measure. Run the nine checks and list the operations agents need, usually a fraction of the catalogue.
- Weeks 3–4: fix the contract. Rewrite those operations' descriptions, add enums and examples, and describe errors as problem details. Humans benefit too.
- Month 2: make writes safe. Add idempotency keys to every unsafe POST in scope, move long-running work to
202+ status, and add dry-run to destructive operations. - Months 2–3: curate the adapter. Generate from the contract, then reduce to task-shaped tools with annotations, output schemas, per-tool scopes and agent-aware limits. Our enterprise MCP server design guide covers hosting and scope.
- Month 3 onwards: test like a product. Run tool-selection and error-recovery evals in CI, watch for retry and 4xx loops, and version tool descriptions like code.
The verdict
Making an API agent-ready is not a protocol project. Converters solved the protocol; they cannot turn a contract written for careful humans into one a probabilistic caller can use safely. That work sits with the API team.
Our view is blunt: do not export your whole API to agents. Pick the tasks, curate the tools, and fix rules ④ and ⑤ before anything goes live, because duplicate side effects and error loops are the failures that cost money. Everything else improves the hit rate; those two prevent the incident.
If you want a second pair of eyes, our software architecture team runs this nine-rule review against your API descriptions and adapter configuration, and hands you the completed checklist.
FAQ
What makes an API agent-ready?
One that a language model can call correctly from the description alone, and that survives how agents behave: retrying after timeouts, guessing arguments and looping over results. That takes a contract written for a model, curated tools, scoped identity, idempotent writes, errors that say what to change, bounded responses, legible rate limits, asynchronous long work and an audit trail naming user and agent.
Should we auto-generate an MCP server from our OpenAPI description?
Use generation as a starting point, not as the product. FastMCP, Azure API Management and Amazon Bedrock AgentCore Gateway all convert OpenAPI operations into MCP tools, but FastMCP's own documentation says models perform significantly better with curated servers. Generate, then reduce to task-shaped tools, rewrite descriptions for a model, add annotations and output schemas, and exclude operations agents should not call.
Do AI agents need idempotency keys?
Yes, for any write that must not happen twice. Agents retry on timeouts, on ambiguous errors and when the model decides to try again. An Idempotency-Key header lets the server replay the first result instead of creating a second payment or ticket. The IETF draft (revision 08, October 2026) suggests 400 for a missing key, 422 for a reused key with a different payload and 409 while the first request is still running.
How should API errors be designed for AI agents?
Return RFC 9457 problem details (application/problem+json) with a stable type URI and a detail that names the field, the expected format and whether a retry can succeed. The MCP 2026-07-28 specification separates protocol errors from tool execution errors and says clients should pass tool execution errors, flagged with isError, to the model so it can self-correct.
How should we paginate API responses for LLM agents?
Use opaque cursors, a small default page size, filters and a has-more signal, and offer concise and detailed response shapes. Anthropic's engineering guidance recommends combining pagination, range selection, filtering and truncation, and notes that Claude Code limits tool responses to 25,000 tokens by default.
How do we rate-limit AI agents without breaking them?
Set budgets per agent identity and per end user, not only per IP or subscription key. Return 429 with Retry-After so clients back off, and consider the RateLimit and RateLimit-Policy fields from the IETF HTTPAPI draft, still an Internet-Draft in November 2026. On the agent side, cap retries and add jitter so a fleet of agents cannot turn one slow dependency into a retry storm.
Sources
All sources checked on 15 November 2026. Chart 1 is our own analysis; the method and script are linked below.
Tier A: primary specifications and regulation
- Model Context Protocol, specification 2026-07-28, Tools: https://modelcontextprotocol.io/specification/2026-07-28/server/tools
- Model Context Protocol, schema reference 2026-07-28 (ToolAnnotations, pagination): https://modelcontextprotocol.io/specification/2026-07-28/schema
- OpenAPI Specification 3.2.0 (19 September 2025): https://spec.openapis.org/oas/v3.2.0.html
- RFC 9457, Problem Details for HTTP APIs: https://www.rfc-editor.org/rfc/rfc9457.html
- RFC 9110, HTTP Semantics (202 Accepted, Retry-After): https://www.rfc-editor.org/rfc/rfc9110.html
- RFC 8707, Resource Indicators for OAuth 2.0: https://www.rfc-editor.org/rfc/rfc8707.html
- IETF draft-ietf-httpapi-idempotency-key-header-08: https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/
- IETF draft-ietf-httpapi-ratelimit-headers-11: https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/
- Regulation (EU) 2016/679 (GDPR), Articles 5 and 25: https://eur-lex.europa.eu/eli/reg/2016/679/oj/eng
- Directive (EU) 2022/2555 (NIS2), Article 21: https://eur-lex.europa.eu/eli/dir/2022/2555/oj/eng
- Regulation (EU) 2022/2554 (DORA): https://eur-lex.europa.eu/eli/reg/2022/2554/oj/eng
Tier B: research and data
- Postman, 2025 State of the API Report: https://www.postman.com/state-of-api/2025/
- Anthropic Engineering, "Writing effective tools for agents — with agents" (11 September 2025): https://www.anthropic.com/engineering/writing-tools-for-agents
- APIs.guru OpenAPI Directory (sample frame): https://api.apis.guru/v2/list.json
- CC Conceptualise, OpenAPI agent-readiness sampling script and results: https://www.conceptualise.de/blog/agent-ready-api-design-guidelines/openapi_sample.py and https://www.conceptualise.de/blog/agent-ready-api-design-guidelines/data.csv
Tier C: vendor documentation, directional
- Microsoft Learn, Expose REST API in API Management as an MCP server: https://learn.microsoft.com/en-us/azure/api-management/export-rest-mcp-server
- AWS, Amazon Bedrock AgentCore Gateway: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway.html
- FastMCP, OpenAPI integration: https://gofastmcp.com/integrations/openapi
- Stripe API reference, Idempotent requests: https://docs.stripe.com/api/idempotent_requests
- Flagship OpenAPI descriptions sampled: Stripe (github.com/stripe/openapi), GitHub (github.com/github/rest-api-description), Twilio (github.com/twilio/twilio-oai), Box (github.com/box/box-openapi), PagerDuty (github.com/PagerDuty/api-schema), Jira Cloud (developer.atlassian.com), Adyen (github.com/Adyen/adyen-openapi)
Topics