# Agent-Ready API Checklist

The Agent-Ready API Checklist (published as "Build AI-Ready APIs — API Checklist") is Emmanuel Paraskakis's free, 12-insight, 2-pitfall framework for auditing whether an API can be used correctly by an AI agent. It covers description accuracy, error design, resource discovery, idempotency, pagination, response design, and deprecation signaling — the full set of places agent usability tends to break. It's the primary free lead magnet behind Emmanuel's AI-Ready API positioning.

## Why it matters

The checklist exists because "make your API agent-ready" is too abstract to act on directly. Twelve specific insights turn that abstraction into an audit you can actually run: does your API's description match its schema? Does every collection have a list endpoint? Are your errors specific enough for one-try recovery? Each insight targets a real, observed failure mode, not a theoretical concern — Emmanuel's own summary of the whole checklist is "keep it simple, keep it standard, no surprises, name it well, describe it well," because agents run on pattern matching and punish anything that breaks the pattern.

The two pitfalls matter as much as the twelve insights: universal search endpoints (`POST /search`) invite hallucinated queries instead of clean filtering, and blindly trusting automated API-readiness scoring tools can mislead you, since those tools often miscount description and example gaps by mishandling `$ref`s and reused schemas.

## How to apply it

Run the checklist end to end against your API, insight by insight:

1. Assume agents skip specs for well-known API shapes and rely on training data.
2. Match descriptions to schema exactly.
3. Return [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457) errors specific enough for one-try recovery.
4. Design resource hierarchy so agents can navigate through context, not guesswork.
5. Use descriptive field names agents can trust without a lookup call.
6. Give every collection resource a list endpoint.
7. Design for idempotency, since agents retry.
8. Treat pagination as a safety net, with good filters as the real front door.
9. Keep responses focused — extra fields are a token tax that compounds across calls.
10. Design for agents that won't seek docs they don't think they need.
11. Signal deprecation with [RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)/[RFC 8594](https://www.rfc-editor.org/rfc/rfc8594) headers plus a link to the successor.
12. Prefer SDKs, then OpenAPI, then code samples/tutorials — in that order — for agent usability.

Avoid the two pitfalls: no universal search-everything endpoints, and don't blindly trust automated readiness scoring without validating against real agent behavior.

Get the full checklist free: [Build AI-Ready APIs — API Checklist](https://maven.com/emmanuel/o/d722eb).

### FAQ

**Is this checklist just for MCP servers?** No — it's for the underlying API itself, regardless of whether you also build an MCP server, CLI, or Skill on top of it. Everything above the API inherits whatever the checklist catches (or misses).

**How long does it take to run this checklist against an API?** It varies by API size, but it's designed to be run as a structured audit, not a vague gut check — each of the 12 points is a specific, checkable question about your API.

**Do automated tools already check this for me?** Partially, and imperfectly. Pitfall #2 in the checklist specifically warns that automated readiness-scoring tools can misjudge description/example completeness and flag things (like rate-limit headers) without considering context — always validate findings against the real spec and real agent behavior.

**Is the checklist free?** Yes — it's published as a free Maven Expert Page resource.

**What's the next step after running the checklist?** [Build AI-Ready API Products With MCP](https://maven.com/emmanuel/build-ai-ready-apis) goes deeper into fixing what the checklist surfaces, including building the MCP layer on top of a now-ready API.

Source: Level 250 — https://www.level250.com/glossary/agent-ready-api-checklist