Skip to main content
All posts
Software Engineering18 min read

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.

Published Updated: 15 November 2026

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-Key on 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 Request sends 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.
The agent-ready API surface. Three trust zones (agent runtime, adapter, your API); numbered callouts 1–9 match the nine design rules below.
The agent-ready API surface. Three trust zones (agent runtime, adapter, your API); numbered callouts 1–9 match the nine design rules below.

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: createRefund beats post_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, not user.
  • 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.

Loading diagram...

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 type URI per error class, so the adapter can map it and you can count it.
  • A detail that names the field, the rule and a valid example. "currency must be an ISO 4217 code such as EUR" 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.

Agent-readiness of public OpenAPI descriptions, share of operations passing each check
Agent-readiness of public OpenAPI descriptions, share of operations passing each check

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.

Which design rule stops which agent failure mode (our analysis)
Which design rule stops which agent failure mode (our analysis)

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.

Who APIs are designed for, Postman 2025 State of the API Report
Who APIs are designed for, Postman 2025 State of the API Report

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.

RuleMinimum barHow to test it
① ContractOpenAPI 3.1+, verb-first operationId, 40+ character description per operation, enums, examples, error schemasLint with Spectral or Redocly; run our sampling script on your description
② Tool surfaceTask-shaped tools; legacy and admin operations excluded; namespaced names; annotations and outputSchemaTool-selection evals in CI: prompts with the expected tool
③ IdentityAudience-bound OAuth tokens; scope per tool; user and agent both identifiableCall each tool with an under-scoped token; expect 403 and no tool listed
④ IdempotencyIdempotency-Key on every unsafe POST, generated by the adapter, retained 24 h or moreReplay a request, then replay it with a changed body; expect one effect and a 422
⑤ Errorsapplication/problem+json; stable type URIs; field-level detail; retry signalFuzz arguments; the agent should self-correct within two attempts
⑥ ResponsesCursor pagination; default page size of 50 or fewer; filters; concise mode; has-more flagMeasure the token size of the largest default response
⑦ Rate limitsBudgets per agent and per user; 429 + Retry-After; per-tool limits on expensive toolsLoad test with a looping agent; other consumers must be unaffected
⑧ Long workNothing synchronous beyond the client timeout; 202 + status resource or handleDrop the connection mid-call and retry; expect one job
⑨ Approval and auditDry-run for destructive tools; approval for high-value actions; audit record per callReconstruct 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

  1. Weeks 1–2: measure. Run the nine checks and list the operations agents need, usually a fraction of the catalogue.
  2. Weeks 3–4: fix the contract. Rewrite those operations' descriptions, add enums and examples, and describe errors as problem details. Humans benefit too.
  3. 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.
  4. 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.
  5. 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

Tier B: research and data

Tier C: vendor documentation, directional

Topics

API design for AI agentsagent-ready APIOpenAPI to MCPMCP tool designidempotency keyRFC 9457 problem detailsAPI pagination for LLM agentsrate limiting AI agents

Frequently Asked Questions

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.

Expert engagement

Need expert guidance?

Our team specializes in cloud architecture, security, AI platforms, and DevSecOps. Let's discuss how we can help your organization.

Get in touchNo commitment · No sales pressure

Related articles

All posts