A Practical Checklist for an Agent-Ready API

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.

Classify the effect

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
}

Require idempotency for mutations

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.

Bound every lookup

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.

Return typed errors with permitted next actions

{
  "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.

Provide a recovery path

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.

Emit the event you will need during an incident

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.

Final test

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.