Glossary
Agent-readable documentation
Definition
Agent-readable documentation is documentation published in forms a software agent can consume reliably — structured plain text, a discovery index, a query interface, and a record of where each claim came from — rather than only as HTML built for human browsers.
Not the same as machine-readable
The two phrases get used interchangeably and mean different things.
Machine-readable usually means a formal schema: an OpenAPI document, a JSON Schema, something a parser validates against. It is precise and it covers only what a schema can express.
Agent-readable means prose an LLM can consume without losing the thread. Explanations, caveats, worked examples — the parts of documentation that carry meaning a schema cannot. The requirement is not formality; it is that the text arrives clean, that the agent can find it, and that the agent can tell how current it is.
A site can be fully machine-readable and still be a poor source for an agent, because everything that explains why lives in HTML wrapped around navigation and cookie banners.
The four layers
Each solves a distinct failure:
- Clean content. The page available as Markdown or plain text, not only as rendered HTML. Removes the extraction step, where boilerplate and navigation leak into what the agent reads.
- Discovery. An index — conventionally
llms.txt— telling an agent what exists before it fetches anything. Removes the crawl. - Retrieval. An interface, typically an MCP server, letting the agent search and fetch specific content rather than downloading whole pages. Removes the guesswork.
- Provenance. Metadata saying where a claim came from and when it was last verified. Removes the silent staleness problem — the one failure the first three layers cannot touch.
Most sites that describe themselves as agent-ready have the first layer. Few have the fourth.
Why accuracy matters more here
A human reading documentation brings scepticism. An example that looks wrong gets checked against the source.
An agent has no such instinct. It treats documentation as specification and writes code against it. Wrong documentation does not produce confusion that someone resolves — it produces confident defects, repeated across every place the agent applied them.
This is why agent-readable and accurate are not separable goals. Making stale documentation easier for agents to consume makes it worse, not better: you have improved the delivery of bad information. Formats without verification are an efficiency gain for the wrong answer.
What it does not require
It does not require writing separately for agents. A second set of documentation maintained for machines is a second thing to keep current, and it will drift from the first.
The same content, served in more than one representation, with an index and an interface in front of it, is the whole of it.
Go deeper
Questions people ask
Do we need separate documentation for agents?
No, and it is a mistake to build one. A second set drifts from the first. Serve the same content in multiple representations instead.
Is adding llms.txt enough to be agent-readable?
It is one layer of four. An index pointing at pages only available as rendered HTML solves discovery and leaves extraction, retrieval and provenance unsolved.
How does an agent know whether documentation is current?
Only if you tell it. Publishing a last-verified date and the source a claim derives from is the only layer that addresses staleness — formats and interfaces do not.