Human developers read your docs, infer your intent, and email you when stuck. Agents read your schema, take it literally, and silently guess when it is ambiguous. Design for the second reader.
TL;DR
- Agents are increasingly the primary callers of APIs and tools.
- They rely on schemas and descriptions, not tribal knowledge or blog posts.
- Clear names, tight types, explicit errors, and self-describing fields are now usability features.
- A good agent API is also a better human API.
The new primary consumer
Through MCP servers and tool-calling, agents now sit on the calling side of a huge and growing share of API traffic. That changes what "good API design" optimizes for. A human developer compensates for a confusing API by reading docs, experimenting, and asking around. An agent has only what is in the interface — the names, the types, the descriptions, the errors. Whatever is implicit gets guessed, and guesses become bugs.
Design principles for agent-friendly APIs
- Names that explain themselves.
archiveOrder(id)beatsprocess(id, 2). The agent infers behavior from the name; make the name carry it. - Tight, explicit schemas. Precise types and enumerated options constrain the agent toward correct calls. A loose
stringwhere you meant one of three values invites the wrong one. - Descriptions that say when, not just what. "Use this to permanently delete; prefer
archivefor reversible removal" tells the agent how to choose. This is the single highest-leverage thing you can add. - Errors that instruct. "Invalid date: expected ISO 8601 (YYYY-MM-DD), got '04/16/2026'" lets an agent self-correct. "Error 400" does not.
// Agent-hostile
function proc(x: string, mode: number): any
// Agent-friendly
/** Archive an order (reversible). Use `deleteOrder` for permanent removal. */
function archiveOrder(orderId: string): Promise<ArchiveResult>
The description field is not documentation you write later. For an agent, it is part of the function signature.
Anticipate how agents fail
- They take ranges literally. If a field accepts 1–100, an agent will eventually send 100. Validate and return a useful error.
- They retry. Make operations idempotent where you can, so a retried call does not double-charge or double-send.
- They batch. Agents naturally want to operate on many items; offer bulk endpoints rather than forcing N calls.
- They need to discover capabilities. Self-describing interfaces — like MCP's tool listing — let an agent learn what is available instead of hardcoding assumptions.
The happy side effect
Everything that makes an API good for an agent makes it good for a human: clear names, precise types, helpful errors, descriptions that explain intent. Designing for the literal, schema-reading, never-asking agent forces a clarity that benefits every caller. The agent is just a very demanding user who never lets ambiguity slide.
Design the interface so a literal reader succeeds, and everyone downstream benefits.