Documenting an API for AI agents is not documenting it for humans

A human developer reading API documentation who hits an ambiguous sentence has a straightforward move available: open the source, fire a test request, ask a colleague. The ambiguity costs them something, but it's recoverable.

An AI agent building a tool call doesn't have those options, at least not in the moment. It has to produce a valid JSON object with the right parameters directly from the text it just read. If the docs say "this field is an identifier" without saying its format, whether it's optional, and what comes back when it's invalid, the agent generates a guess — and that guess either fails outright or, worse, gets silently accepted and produces a wrong result downstream. Ambiguity that's merely annoying to a human turns directly into a failed call or a wrong action for an agent.

The practical consequence is that, for an agent audience, a structured example is worth more than explanatory prose. A complete, real request — every required field present, one example of a valid error, the exact shape of a successful response — is something a model can pattern-match against directly. A paragraph describing the same thing in words is something the model has to interpret first and then convert into structure, and that conversion step is where errors get introduced.

This doesn't mean dropping prose; it means prose should accompany the example, not replace it. The best documentation for an agent is documentation where, even if every explanation were stripped out, the examples alone would still demonstrate correct behavior.

When a human notices a breaking API change — a renamed field, a changed default — they can draw on experience and adapt, even without reading the changelog. An agent has no experience; it only has the contract it saw at training time or at the moment it read the documentation. If that contract changes without a clear version boundary, the agent keeps building calls against the old contract, and neither side understands why the result is wrong.

That means API versioning aimed at an agent consumer needs to be more explicit and more stable than what suffices for a human SDK. A breaking change should be signaled in the route or the response schema itself, not only in a release note that no agent reads unless it has been explicitly instructed to.

Human-facing documentation is usually organized around visual navigation: a side menu, nested tabs, a "show more" button that hides content until it's clicked. None of that means anything to an agent that reads content once and acts on it; whatever sits behind a click doesn't exist for it at all, unless it already knows the path to get there. Documentation whose structure is flat and fully traversable in a single fetch is more reliable for an agent than documentation that's beautifully organized but has its actual content hidden behind user interaction.

That means good design for an agent sometimes runs exactly opposite to good design for a human: a human enjoys compression and hidden detail; an agent needs that same detail, unhidden, along a single path.

One approach we've applied to our own site: every page also has a plain, machine-readable text counterpart, and a single index file at the root of the site lists all of them with direct links. The idea is simple — a page built for a browser and visual layout is overhead for an agent that only wants the text, and a parallel version that strips that overhead out makes reading more reliable for the agent.

The value of doing this doesn't come from a guaranteed search ranking benefit; it comes from the fact that the actual, present-day consumers of these files are coding agents and assistants reading them right now, and the cost of maintaining them is one small file. If the convention gets picked up more broadly later, the work is already done. If it doesn't, nothing was lost.

Documentation written for a human usually assumes the reader has implicit context: they know what a certain default means because they've seen it in similar projects, or they guess a field is optional because it was omitted from other examples. An agent has none of that implicit context unless it's spelled out in the exact text it read. That means a sentence like "this parameter usually isn't needed" is guidance for a human and an unresolved condition for an agent — one that either gets ignored or misread.

The practical consequence is that good agent-facing documentation converts every implicit condition into an explicit one: this parameter is required when X, ignored when Y. These are exactly the details a human documentation writer tends to skip as obvious — precisely because they're obvious to the writer — and that's exactly where an agent's tool call breaks.

The temptation in documenting for agents is that more detail is always better. But a contract that keeps shifting in small ways — even without a formally declared breaking change — is more expensive for an agent than a simpler, more stable one, because the agent has to re-verify actual behavior every time. Stability, even at some cost to flexibility, is worth more to an agent consumer than completeness is.

This doesn't mean an API should never change; it means small, unannounced changes carry a cost that's invisible to a human consumer but shows up immediately for an agent, because the agent has no memory of "this used to work differently" that would let it forgive a minor drift as a small deviation.

Human-facing documentation usually focuses on the happy path and summarizes errors in a short, separate section, because a developer who hits an error can read the status code and guess. An agent doesn't have that guesswork available; if the exact shape of an error response — its fields, what each code means, and whether it's retryable — isn't documented with the same precision as the success response, the agent either ignores the error or misreads it as success.

That means, for an agent audience, the error section shouldn't be a short paragraph at the bottom of the page; it needs the same level of structured detail as the happy path: a complete example for each error category, not just a list of codes.

• Does your documentation include a complete, valid example that stands on its own, or only description?
• Are required fields, formats and valid errors written in structured form, not just prose?
• How is a breaking change signaled — in the contract itself, or only in a note nobody reads?
• Is a machine-readable version of your content available independent of the visual layout?