The 40-point AI-Agent API Readiness Checklist

The machine-readable contract exists, parses, and can be fetched.

• 1

  Document is valid OpenAPI 3.x and parses without errors

  Validate against the OpenAPI 3.0/3.1 schema with a real parser, not just YAML linting. A spec that fails strict validation will break code generators, MCP tool builders, and any agent that loads it programmatically.

• 2

  API has a title, version, and description

  The info block is the agent's first context. A clear title and a description that says what the API is for help a model decide whether and how to call it; the version lets it reason about compatibility.

• 3

  At least one server URL is defined

  Without a servers entry an agent cannot resolve relative paths into callable URLs. List every environment (production, sandbox) explicitly and mark which is which.

• 4

  Schemas are reused via $ref instead of duplicated

  Duplicated inline objects drift apart and bloat the context window. Shared components/schemas keep types consistent and let tool generators emit one model per entity instead of many near-copies.

• 5

  The spec is published at a stable, machine-fetchable URL

  Agents and CI need to GET the current spec without auth gymnastics or a login wall. Host it at a versioned, CORS-friendly URL and keep it in sync with what production actually serves.

Every input and output is typed precisely enough to generate against.

• 6

  Every request body has a defined schema

  A free-form or missing request schema forces the agent to guess the shape of the payload. Define the body as a typed object so the model knows exactly which fields to send.

• 7

  Every 2xx response has a defined schema

  Agents chain calls by reading prior responses. If the success response is untyped, the model cannot reliably extract the id or token it needs for the next step.

• 8

  Required fields are marked on every object

  The required array is how a model knows what it must supply versus what is optional. Missing required markers lead to dropped fields and avoidable 4xx errors on the first attempt.

• 9

  Enums, formats, and constraints are specified

  Use enum, format (date-time, email, uuid), and bounds (minimum, maxLength, pattern) so agents emit valid values instead of plausible-looking guesses. Constraints turn a retry loop into a first-try success.

• 10

  Each field has a human-readable description

  Field names alone are ambiguous (is amount in cents or dollars?). One line of description per field removes the guesswork that causes silent, wrong-unit mistakes.

An agent can tell what each operation does and when to reach for it.

• 11

  Every operation has a unique operationId

  The operationId becomes the tool/function name in generated clients and MCP servers. Missing or duplicate ids produce unnamed or colliding tools that an agent cannot address.

• 12

  operationIds use verb_noun naming (e.g. create_customer)

  Action-first names map directly onto how models pick tools. createCustomer or create_customer reads as intent; getThingV2Final does not.

• 13

  Every operation has a summary and description

  The summary is the short label a model scans; the description is where it learns side effects and preconditions. Both feed straight into tool selection quality.

• 14

  Operations are grouped with meaningful tags

  Tags cluster related operations so an agent can narrow a large API to the handful relevant to a task, instead of weighing hundreds of tools at once.

• 15

  “When to use this endpoint” guidance is documented

  Near-duplicate endpoints (search vs list, create vs upsert) confuse models. A sentence on when to choose each prevents the agent from picking the wrong one.

Concrete examples show the agent exactly what a real call looks like.

• 16

  Each operation includes a request example

  A worked example resolves ambiguity that schemas cannot. Models pattern-match strongly on examples, so one realistic request often does more than a page of prose.

• 17

  Each operation includes a response example

  Response examples let an agent plan how it will parse the result before it ever makes the call, and help it recognize success versus an unexpected shape.

• 18

  Common multi-step workflows are documented

  Real tasks span several calls (create, then confirm, then fetch status). Documenting the canonical sequence keeps agents from inventing brittle orderings.

• 19

  Parameters include descriptions and examples

  Path, query, and header parameters need the same treatment as body fields: a description and an example value so the agent formats ids, dates, and filters correctly.

• 20

  Docs are available in a machine-readable form

  Prose-only docs on a marketing site are hard for agents to use. Keep the authoritative behavior in the spec (descriptions, examples) so it travels with the contract.

The agent knows how to authenticate, with what scope, and within what limits.

• 21

  Security schemes are defined in the spec

  Declare the auth mechanism (OAuth2, API key, bearer) in securitySchemes so tooling can prompt for or inject credentials automatically rather than failing with an opaque 401.

• 22

  OAuth / API-key scopes are documented per operation

  Each operation should state the scope it requires. Agents and the humans supervising them need to know, before calling, whether the current token is even allowed to do this.

• 23

  Least-privilege scopes are available

  Offer narrow, read-only and action-specific scopes so an agent can be granted exactly what a task needs. All-or-nothing keys make safe delegation impossible.

• 24

  Rate limits and the 429 response are documented

  State the limits and document the 429 response with its Retry-After header. Without this, agents hammer the API and stall instead of backing off cleanly.

• 25

  Credential handling and rotation are explained

  Document token lifetime, refresh, and rotation. Long-running agents must know how to renew credentials mid-task rather than silently breaking when a token expires.

When something fails, the agent gets a typed, actionable signal.

• 26

  4xx and 5xx responses are documented

  Document the error responses an operation can return, not just the happy path. Undocumented failures force the agent to interpret raw text and often retry the wrong way.

• 27

  Errors share a typed Error schema

  One consistent error object across the API lets an agent handle failures uniformly instead of writing bespoke parsing for every endpoint.

• 28

  Errors include a machine-readable code

  A stable string code (rate_limited, invalid_parameter) is something a model can branch on reliably; an English message that changes wording is not.

• 29

  Responses include a request id for tracing

  A request id in the response (or a header) lets the agent and its operators correlate a failure with logs, which is essential for debugging autonomous runs.

• 30

  Retryability and backoff guidance is provided

  Mark which errors are safe to retry and recommend a backoff. This is what separates a graceful recovery from an infinite retry loop or duplicate side effects.

Dangerous and irreversible actions are labeled and gated.

• 31

  Destructive endpoints are explicitly labeled

  Mark operations that delete, charge, or send so a model (and a guardrail layer) can require extra confirmation before invoking them autonomously.

• 32

  Irreversible actions document confirmation requirements

  If an action cannot be undone, say so and state how to confirm intent (a confirm flag, a two-step flow). Agents should never discover irreversibility by causing it.

• 33

  Mutations support idempotency keys

  An idempotency key lets an agent safely retry a create or payment after a timeout without double-charging. Without it, the safe move is to not retry, which strands the task.

• 34

  High-risk operations offer a dry-run / preview

  A preview or validate-only mode lets an agent check what an action would do before committing, turning a risky one-shot into a reviewable two-step.

• 35

  Soft vs hard delete behavior is documented

  State whether delete archives or destroys, and whether it cascades. Agents reason very differently about a reversible soft delete than an unrecoverable hard one.

Each operation can become a clean, safe tool an agent can call.

• 36

  Operations map cleanly to clear tool names

  A good operation is one tool with one purpose. Endpoints that do many things via flags or modes are hard to expose as a single, predictable MCP tool.

• 37

  Input schemas are complete enough to generate tools

  MCP tool definitions are built from your input schema. Missing types, required flags, or descriptions produce tools the model cannot fill in correctly.

• 38

  Responses are predictable and typed

  Tools whose output shape shifts run to run break agent planning. A stable, typed response is what lets the model chain this tool into the next step.

• 39

  Dangerous tools can require human approval

  Expose an approval boundary so high-risk tools pause for a human in the loop. This is the practical control that makes letting an agent act at all acceptable.

• 40

  Tool descriptions explain when to use each tool

  The description is the model's entire basis for choosing a tool. Spell out the job it does, its preconditions, and what it returns, in plain language.