The 10 API design principles for the agent era
Most API design advice was written for humans who read docs. These ten principles are written for the caller that can't: an AI agent. Each one is independent, opinionated, and measurable — the Agent-Readiness Checker grades your OpenAPI spec against every one.
An agent can discover and select the right operation.
It can act with scoped, bounded authority.
It can depend on consistent, recoverable behaviour.
- 01Discoverable
Be discoverable
An agent can find what it's allowed to call at runtime.
Publish a machine-readable surface — OpenAPI, an llms.txt, or an MCP manifest — so an agent can enumerate capabilities without scraping prose docs. If it can't be discovered, it can't be used.
Scored as Discovery rubric weight ×1.2 - 02Discoverable
Expose capabilities, not raw endpoints
Group operations into a small set of intent-level tools.
A model selects far more reliably from 12–20 well-named capabilities than from 300 near-identical CRUD routes. Curate the surface into the verbs a caller actually wants — the raw endpoints can live underneath.
Scored as Tool curation rubric weight ×1.3 - 03Discoverable
Right-size the surface
Keep the callable surface small enough to reason about.
Every extra endpoint is another branch an agent can take wrongly. Prune, group, and version deliberately so the surface stays selectable rather than sprawling.
Scored as API surface size rubric weight ×1.0 - 04Discoverable
Make every operation self-describing
Each operation states its intent in one clear line.
Empty or vague descriptions force a model to guess. Give every operation and parameter a one-line statement of what it does and when to use it — the description is now part of the interface, not documentation.
Scored as Semantic clarity rubric weight ×1.3 - 05Discoverable
Name things predictably
Same concept, same name; same action, same verb.
Consistent resource and action naming lets a caller generalise from one endpoint to the next. Predictability is what makes an API learnable in a single pass.
Scored as Naming consistency rubric weight ×1.0 - 06Safe to call
Make auth safe for autonomous callers
Authentication a non-interactive agent can actually satisfy.
Token flows, machine credentials, and scoping should assume the caller is software acting on a user's behalf — not a human clicking a consent screen. Auth that only works interactively is auth an agent can't use.
Scored as Auth model rubric weight ×1.1 - 07Safe to call
Grant the least privilege that works
Scopes and permissions bound the blast radius of a mistake.
Design narrow, composable scopes so an agent gets exactly the access a task needs and no more. Least privilege is the difference between a wrong call that errors and one that does damage.
Scored as Least privilege rubric weight ×1.1 - 08Consistent
Return structured, recoverable errors
Typed error codes a caller can branch on and retry.
Replace free-text error strings with a typed envelope — a stable code, a human message, and a retryable flag. Structured errors are what let an agent recover instead of stalling.
Scored as Error handling rubric weight ×1.2 - 09Consistent
Paginate consistently
One pagination style, documented, across every collection.
Mixing cursor and offset styles across endpoints breaks any caller that loops over results. Pick one model, apply it everywhere, and document how to page through to the end.
Scored as Pagination rubric weight ×0.9 - 10Consistent
Signal limits and retries
Clear 429s with retry guidance the caller can honour.
Tell the caller the limit, when it resets, and how long to wait — via standard headers and a documented 429. An agent that knows when to back off is an agent that stays inside your limits.
Scored as Rate limits rubric weight ×0.9
See how your API scores
The checker runs your OpenAPI spec against all ten principles and returns a score, a letter grade, and the top fixes — in seconds. Vendor-neutral, with a published methodology.
Run the free checker