A Practical Checklist for an Agent-Ready API

A developer published a practical checklist for making APIs safe for AI agents, arguing that an MCP server alone does not fix ambiguous side effects, retries, data limits, or recovery paths. The checklist recommends tagging each tool with an effect type (read, draft, state_change, or irreversible_action), enforcing approval at the calling layer rather than the model, requiring durable idempotency keys for retryable actions, and bounding searches with page, scope, freshness, and cost limits. It also calls for structured error codes with safe next actions and audit logging of both the policy decision and the call.

An MCP server exposes tools. It does not repair an API that leaves side effects, retries, data limits, and recovery ambiguous. Use this checklist before exposing an endpoint to an agent. Every tool should identify one effect: read , draft , state change , or irreversible action . The calling layer, not the model, should enforce approval for consequential effects. { "name": "cancel delivery", "effect": "state change", "approval required": true, "idempotency key required": true, "dry run supported": true } If an agent can retry an action, the action needs a durable idempotency key. Store the result with the key and return the original outcome on repeat calls. A timeout must not leave the caller guessing whether it created a duplicate. For searches and listings, declare a maximum page size and maximum pages, a required time range or other scope, cursor expiry, result freshness, and a rate and cost limit. An unbounded search turns a vague task into an unbounded data and spend problem. { "code": "APPROVAL REQUIRED", "retryable": false, "safe next actions": "request approval", "create draft" , "correlation id": "9b6d..." } Don't use generic error text as workflow control. It forces the agent to infer a recovery path it should not invent. For each mutation, document whether it is simulatable through a dry run, compensatable after completion, reversible only within a time window, or irreversible and therefore approval-gated. At minimum, record task ID, authenticated principal, agent identity, tool version, input hash, approval ID, effect, result, correlation ID, and compensating action. Log the policy decision as well as the call. Without it, you can see what happened but not why it was allowed. Ask whether a caller can make an unsafe change by misunderstanding the tool. If yes, refine the contract. The goal isn't to make the agent more careful. It's to make the interface harder to misuse. For the architectural rationale and trade-offs, read the canonical article: The Agent-Ready API Is Not an API With an MCP Server https://michaeldabydeen.com/articles/the-agent-ready-api-is-not-an-api-with-an-mcp-server .