How to write documentation for AI agents

We tested 93 products with the AI Agent Readiness Test between August 5 and September 22, 2026, and we published the reports between August 6 and September 22. Each report carries two scores. One score counts the files a site exposes for AI agents. The other scores whether AI models can finish five first-hour developer jobs by reading the product’s public documentation pages alone. The two scores together make up the AI Agent Readiness Score out of 80.

The count of agent-facing files is nearly settled. Of the 93 products, 91 publish an llms.txt, a file that lists a site’s pages for language models. 87 serve a Markdown version of each page. 69 expose an MCP (Model Context Protocol) server that answers a real request. 68 run a docs assistant on the site. 57 publish llms-full.txt, which carries the full documentation in one file. 37 products pass all five checks.

The reading score is not settled in the same way. No product earned all 30 points. The highest score was 28 of 30, shared by Tavily, ClickHouse, and LiveKit, and the average was 23.2. Eight products pass all five surface checks and still score 20 or less on reading. The lowest of them, Mem0, scored 9 of 30.

Those two scores move separately. Several docs platforms generate llms.txt and the Markdown pages by default, so the delivery layer is a build step rather than a writing task. What decides whether an agent finishes a first-hour job is what the pages say. Across the 93 products, the reading test lost 631 points. Most of that loss sits in a few places, and writing fixes them.

Where agents lose the most points

The reading test gives each product the same five jobs a developer faces in a first hour: get a first working result, find the exact limits, recover from an error, complete one webhook or authentication path, and use the primary SDK. Three models, GPT 5.6 Sol, Claude Opus 5, and DeepSeek v4 Flash, each take the jobs alone, from the same brief, with no shared context. The models create no accounts, make no API calls, and run no code. The only input is the product’s public documentation pages. Each model votes PASS, PARTIAL, or FAIL on each job, and every vote carries a verbatim quote from a page and that page’s URL. The full test design is on the methodology page.

Each job has 558 points available across the 93 products, which is 93 products times three models times two points for a PASS. The losses are not spread evenly. The job to find the exact limits lost 225 points, more than any other job, and 86 of the 93 products lost at least one point on it. Recovering from an error lost 151 points, and 64 products lost at least one point on it. Use the primary SDK lost 99 points, the webhook or authentication job lost 98, and first working result lost 58.

The limits job loses its points in distinct ways. Mailgun keeps the only rate-limit number on the site in the Metrics reference, with no statement of what the number applies to. No page lists the sending quota for each plan. Arcade.dev has no docs page that gives a general API rate limit, and its plan quotas appear only on marketing pages. Airbyte has pages that disagree on Plus workspace limits and on sync intervals for higher plans. Two pages that disagree cap a job at PARTIAL, because the model has to choose between them.

Error recovery loses its points to pages that name the problem and stop there. 48 products had the error job framed as recovering from an HTTP 429 response. For E2B, the RateLimitError reference names the cause of the error, and no page gives the limit that triggers it, the retry timing, or a backoff schedule. For CARTO, the rate limits page names what triggers a 429, and no page gives the block duration, the retry timing, or safe retry steps. For DeepInfra, the docs say to retry after a short delay, and no page gives the length of the delay, a backoff schedule, or a documented Retry-After header.

The webhook and SDK jobs lose points to pages that do not match each other. Mailgun puts the webhook signature on the security page and the event on the payloads page, and no page shows the full POST body. A model that writes a verification handler has to assemble the request from two pages and guess at the rest of the body. Resend splits its webhook flow in a similar way. The example in the receiving guide reads the parsed request body with no signature check, while the verification page requires the raw body. An example that reads the parsed body cannot produce the raw body the check needs. For Merge, the pagination loop on the SDKs page omits await, and the Pagination page uses an older callback-style Node client.

The first working result job loses the fewest points. CARTO loses points there because the quickstart SQL example hard-codes one regional API host, while the API Base URL page says to use the organization’s own URL. A model that finds the quickstart first builds requests against a host that another page contradicts.

What an agent does with a gap matters for all five jobs. The agent takes the value it finds, or it fills the gap from general knowledge, and the code it writes follows what the page says. A person with the same gap asks support, checks the pricing page, or sends a test request. An agent reading the pages has none of those moves.

What to change in your pages

State each limit once, on a docs page, with what it applies to and the value for each plan. That change addresses the job that lost the most points. If a rate-limit number applies to one metric only, the page that gives the number should say so. Plan quotas belong on a docs page even when marketing pages also carry them, because the agent reads the docs and has no way to judge which page governs.

Give the retry timing and the steps next to each error. When a reference page names RateLimitError, the same page should give the limit that triggers the error, the wait before the first retry, the backoff schedule, and whether the API sends a Retry-After header. An agent that meets the error mid-task can then follow the steps instead of guessing a delay.

Show one complete example for each flow. The Mailgun webhook path needs a page that shows the signature check and the event together, with the full POST body above the handler. The Resend receiving guide needs an example that reads the raw body, so the code the guide teaches can pass the verification the docs require.

Find pages that disagree and make them agree. The Airbyte pages that give different Plus workspace limits and different sync intervals force every reader into the same choice, and the test caps the job at PARTIAL when the pages disagree. Make one page the source for each number, and change the other pages to link to it.

Keep SDK examples in step with the reference. The Merge pagination loop and the CARTO quickstart host both drift from the rest of the docs. When the reference changes, every example that uses the changed call needs the same edit, because the agent follows the example it found first.

Where the test stops

The test reads pages and runs no code. A PASS on a job means the pages gave a model one confident answer, not that the code the model wrote from that answer works against the live API. The panel is also small. Three models give three votes per job, and each report prints every vote with its quote and URL, so you can read where the models disagreed and judge the votes yourself.

What to do first

Add any missing agent-facing file first. Each surface check is worth 10 points, and llms.txt, llms-full.txt, and the Markdown pages are built from pages that already exist, so those checks fall to configuration. The writing time belongs to limits and error recovery, the two jobs that lost 376 points between them across the 93 products. Every report lists fixes ranked by the points each fix would add back, and a failed surface check is worth 10 points where a reading job is worth the points its votes lost. The grades table shows how the tested products compare.