AI-native
How do you write documentation AI agents can use?
Write it so it reads well as plain text. Publish each page as Markdown, describe your API in an OpenAPI file, put the whole set in one llms-full.txt, and give exact, copyable examples. Agents don't see your layout or your menus; they see words, so every fact has to be in the words.
Updated November 2, 2026
How do AI agents read documentation?
An agent fetches a page, turns it into text and looks for the answer to the step it's on. Navigation, scripts and tabs are noise, and content that only appears after a click may never be seen. An agent also has limited room to read, so a page that answers first and links to the detail serves it better than a long page with the answer near the end.
Should every page have a Markdown version?
Yes, if you can. A Markdown copy of each page gives an agent the content without the page around it. Sandboxer serves its docs and guides as Markdown, for example its long-running tasks page, and Transformer does the same for its blog posts, such as its CLI guide.
Why publish an OpenAPI file?
An OpenAPI file describes every API operation, its inputs and its responses in a format programs can read. Agents and code generators can use it directly instead of guessing from prose. Sandboxer describes its REST API in one OpenAPI file and publishes the same content as one page per operation.
What are llms.txt and llms-full.txt for?
llms.txt is a short summary with the key facts and links; llms-full.txt puts the full text in one file, so an agent can load everything at once. Sandboxer's llms-full.txt holds its full docs. Transformer's llms-full.txt adds the offer lifecycle, its MCP tool list, API examples, the FAQ and the developer docs. Flagger.gg's llms-full.txt has every page on its site as plain text. Read what llms.txt is.
What makes an example useful to an agent?
It runs as written. Show the full command with real flags and machine-readable output, and say what it returns. Flagger.gg's docs show an agent turning off a flag with a reason attached: flagger kill search_v2 --note "error rate up after 10%" --json. Transformer's show a sale being reported from the command line: transformer conversions report --click <tf_click> --amount 49 --order A-1001.
Are MCP tool descriptions documentation too?
Yes, and often the only documentation an agent reads. Each tool's name and description decide whether the model picks it. Transformer's tool list says which side each tool is for, brand or creator, and what it returns. Flagger.gg lists only the tools an agent's token allows, so the agent never sees actions it can't take. See what MCP is.
How do you stop agents from promising things that don't exist?
Label what isn't available yet, in the same place you describe what is. Flagger.gg's docs list features as "in development", such as guarded rollouts with automatic rollback and SDKs beyond Go and Node, so an assistant reading them won't offer those as live. Then keep the docs current: an agent trusts the page it reads. For the full agent-readiness list, see how to make a product AI agents can use.
Frequently asked questions
What format should documentation for AI agents use?
Plain Markdown for pages, an OpenAPI file for the API, and an llms.txt plus llms-full.txt at the root of the site.
Do AI agents read OpenAPI files?
Many agents and tools can. An OpenAPI file gives exact operations, inputs and responses, which is more reliable than prose.
Is llms-full.txt the same as documentation?
It is the documentation in one file. Sites generate it from the same source as their pages so the two never drift apart.
Should I write separate docs for agents and for people?
Usually not. Clear, answer-first pages with exact examples serve both. Add Markdown versions and one-file exports for agents.