Making your product readable by the agents that will recommend it

A growing share of the traffic that decides whether your product gets used is not a person. It is an agent, sent by a developer, asked to work out whether your API can do something and then to wire it up. That agent will read your documentation, and what it finds decides the answer.

29 July 2026 · 5 min read

The good news is that everything which makes documentation legible to an agent also makes it legible to a person in a hurry.

What an agent has to get through today#

A typical documentation page is 90% chrome: navigation, a sidebar, a cookie banner, a search widget, three scripts, and somewhere in the middle the two paragraphs that answer the question. An agent fetching that page pays for all of it in tokens, and often gets a shell of HTML because the content arrives by JavaScript afterwards.

The result is an agent working from a bad copy of your docs, and hallucinating the parts it could not read. If you have ever seen a model invent an endpoint that looks like yours but is not, this is usually why.

Serve markdown beside the HTML#

The simplest useful change: give every documentation page a markdown twin at a predictable URL. This site does it as /docs.md, and every blog post has one at /blog/<slug>.md, which is why the file you are reading was written as markdown and rendered into this page rather than the other way around.

Three properties make it work.

Predictable. Append .md, get markdown. No content negotiation to discover, no separate domain.

Identical content. Both renderings come from one source, so they cannot drift. If your markdown is a stale export, it is worse than not having it.

Discoverable. A <link rel="alternate" type="text/markdown"> on the HTML page points at it, so an agent that landed on the page can find the cheap version.

<link rel="alternate" type="text/markdown" href="https://example.com/docs.md" />

llms.txt, and what belongs in it#

llms.txt is a plain markdown file at the root of your domain that tells an agent what your product is and where the authoritative documents are. It has the same spirit as robots.txt but the opposite purpose: robots.txt says what not to read, llms.txt says what is worth reading and in what order.

A useful one is short and factual. Ours covers the endpoint and how to authenticate, the tool surface, the rules that will refuse an agent's call, the quickstart, the REST equivalents, and links to the markdown documents. What makes it useful is not completeness, it is that an agent can act from it: the rules section exists so an agent that hits daily_send_quota_exhausted knows what that means without a support conversation.

Things worth including:

• One paragraph on what the product does, in plain terms.
• The base URL, the auth scheme, and one working example.
• The limits and refusal reasons an agent will actually meet.
• Links to markdown documents rather than to HTML pages.
• Anything an agent would otherwise guess wrong.

Things to leave out: marketing claims, comparison tables, and anything you would not want quoted back to a customer verbatim.

Write documents an agent can act on#

Beyond the format, four habits change the answer quality noticeably.

State constraints where the action is. A limit documented three pages away from the call it applies to will be missed. Put the recipient cap in the send documentation, not only in a policy page.

Make error and refusal states first-class. Agents encounter your failure paths far more often than a human reading the happy path does. Document every refusal reason and what to do about it. This is the single highest-value section for agentic use and the one most often missing.

Use stable identifiers. A refusal reason that is a stable string can be handled in code. A refusal reason that is a sentence cannot, and it will be pattern-matched badly by somebody.

Keep examples runnable and current. An agent will copy your example exactly. If it does not run, that is now your integration bug rather than a documentation nit.

Structured data still earns its place#

Search engines and the systems that feed model training and retrieval both read structured data. Article and FAQPage schema on your content pages, canonical URLs, and honest metadata are not glamorous but they are how a page ends up cited rather than paraphrased from a competitor's summary of it.

The FAQ section on every post here is not a design flourish. It is the shape a question-and-answer gets retrieved in, and writing the question the way a person would actually ask it is most of the work.

Where this connects back to email#

An agent that has read your documentation and decided to integrate has one more problem: it needs to talk to someone. Support questions, verification codes, and the occasional human handover all arrive as email, which is where an agent with its own address stops being blocked on a person. Agents that can provision their own inbox close the last gap in an unattended integration.

That is the wider point of making a product agent-readable: not that agents read instead of people, but that the parts of your funnel which used to require a human at 3am no longer do.

A short checklist#

1. Every documentation page has a markdown twin at a predictable URL, from the same source.
2. <link rel="alternate" type="text/markdown"> on each HTML page.
3. An llms.txt at the root: what it is, how to auth, the limits, links to the markdown.
4. Refusal and error states documented with stable identifiers.
5. Constraints stated next to the calls they constrain.
6. Runnable, current examples.
7. Article and FAQ structured data on content pages.
8. Nothing important rendered only by JavaScript.

Questions#

What is llms.txt?

A plain markdown file at the root of a domain that tells agents what the product is, how to authenticate, what the limits are, and where the authoritative documents live. Think of it as the opposite of robots.txt.

Why serve markdown as well as HTML?

Because an agent fetching a documentation page pays for navigation, scripts, and chrome in tokens, and often receives a shell if content is rendered client-side. A markdown twin gives it the content and nothing else.

Does this replace SEO?

No, it extends it. Structured data, canonical URLs, and clear question-shaped headings still decide whether your page is cited. Agent-readable formats decide whether the agent reading it gets the details right.

What is the highest-value section to write for agents?

Error and refusal states, with stable identifiers and the correct response to each. Agents hit failure paths far more often than a human reading your quickstart does.

Should llms.txt list everything?

No. Keep it short and factual: what the product does, how to authenticate, the limits that will refuse a call, and links to the full markdown documents.

How do I know if it is working?

Ask an agent to integrate your product using only what it can fetch, and read what it produces. The gaps in its attempt are your documentation gaps, stated precisely.