--- title: Writing documentation an agent can actually answer from metaTitle: Writing help documentation for AI agents to retrieve description: Your agent answers from your help centre, which was written for people who are already reading it. What to change so retrieval finds the right passage and the answer is groundable. date: 2026-08-06 author: MCPmailer tags: Guides --- An email agent is only as good as what it can retrieve, and most help documentation was written on the assumption that somebody is already reading the page, has the navigation in view, and can see the heading above the paragraph. Retrieval strips all of that away and hands the model a fragment. ![One passage retrieved without the page around it](/blog/writing-docs-agents-can-use/hero.webp "The paragraph arrives without the page. It has to stand alone.") Fixing the documentation is usually cheaper than fixing the agent, and it improves the human experience at the same time. ## Write passages that survive on their own The single most useful change. A paragraph that says "click Save, then repeat for each domain" is meaningless out of context, and out of context is exactly how it will arrive. Make each section answerable alone: name the subject in the first sentence, avoid pronouns pointing at a previous heading, and repeat the noun rather than saying "it". Slightly more repetitive to read top to bottom, dramatically more useful when retrieved. The test: copy any single section into a blank document. Does it still answer a question? ## One question per section Structure documentation around the questions people actually ask rather than the shape of your product. A section titled "Billing" is a retrieval target for everything and an answer to nothing. Three sections titled "When am I charged", "How do I change my card", and "What happens if a payment fails" are three precise targets. Your agent's escalation log is the source for these, per [the weekly half hour that keeps an agent honest](/blog/weekly-review-email-agents). Every question it could not ground is a section somebody needs to write, ordered by how often it came up, which is better prioritisation than any documentation project has ever had. ## State the facts as facts Retrieval-friendly prose is direct. Two habits to drop. **Hedging.** "Refunds typically take a few days" gives the model nothing to state confidently, so it either invents precision or hedges further. "Refunds are issued within three working days" is a fact an agent can quote and a customer can rely on. **Cross-references as the answer.** "See the section above for details" is a dead end when the section above was not retrieved. Repeat the important detail rather than pointing at it. | Written for a reader | Written for retrieval too | | --- | --- | | "Click Save, then do the same for each" | "Save each domain individually" | | "This usually takes a few days" | "This takes three working days" | | "See the previous section" | The relevant sentence, repeated | | "Billing" as one long page | One section per question | | "Contact us if unsure" | The condition under which to contact, spelled out | ## Mark what must never be paraphrased Some strings have to survive verbatim: order and invoice references, product names, error codes, legal wording, and anything a customer will search for in your systems. Documentation that presents these plainly, ideally in code formatting, makes it far more likely they arrive intact, per the translation rules in [answering email in the language it arrived in](/blog/multilingual-email-agent). The related rule for policy text: an agent should quote it, not apply it. Write policy sections so quoting them is useful on its own, which usually means stating the rule and its exceptions in the same place rather than scattering exceptions across pages. ![A section that answers one question and names its own subject](/blog/writing-docs-agents-can-use/section.webp "Name the subject, state the fact, keep the exception nearby.") ## Keep a machine-readable copy Serve documentation as markdown alongside HTML, at a predictable URL, from one source so the two cannot drift. That removes the chrome, the scripts, and the navigation from what a retrieval step ingests, and it is the same practice that makes your product legible to agents evaluating it from outside, per [making your product readable by the agents that will recommend it](/blog/agent-readable-website-llms-txt). For an internal agent the equivalent is exporting your wiki to plain text on a schedule rather than scraping the rendered pages, which is both cheaper and less brittle. ## Date things, and delete things Two maintenance habits that matter more for agents than for people. A page with a last-reviewed date lets you find the ones nobody has checked since the product changed. A person browsing usually notices when something looks stale; a retrieval step never does. And delete superseded pages rather than leaving them. A human skims two conflicting articles and picks the newer one. Retrieval may return either, and an agent will answer confidently from the wrong one, which is the failure mode described in [making an agent answer only what it can prove](/blog/grounding-and-citation-email-agents). ## The measurable payoff When documentation improves, the agent's ungrounded escalation rate falls, and it falls permanently rather than drifting back the way prompt tweaks do. That is the cleanest signal available that the work was worth doing, and it is measurable within a week. The secondary effect is the one people underestimate: the same changes reduce the volume of questions arriving at all, because a help centre written as answers to real questions is one people can actually use. ## Questions ### How should documentation change for an AI agent? Write sections that stand alone, one question per section, with facts stated directly rather than hedged, and important details repeated instead of cross-referenced. ### What is the test for a good section? Copy it into a blank document. If it still answers a question without the page around it, retrieval can use it. ### Where do I get the list of sections to write? Your agent's escalation log. Every question it could not ground is a missing section, ordered by frequency. ### Why does hedging hurt? Because a model given vague wording either invents precision or hedges further. A stated fact can be quoted confidently and relied on. ### Should I keep old pages around? No. A person picks the newer of two conflicting articles; retrieval may return either, and the agent will answer confidently from the wrong one. ### Does this help humans too? Yes. Documentation organised around real questions with facts stated plainly is easier for people, and it reduces the volume of questions arriving at all. ## Related - [Making an agent answer only what it can prove](/blog/grounding-and-citation-email-agents) - [Making your product readable by the agents that will recommend it](/blog/agent-readable-website-llms-txt) - [The weekly half hour that keeps an agent honest](/blog/weekly-review-email-agents) - [The internal helpdesk nobody wanted to staff](/blog/ai-agent-internal-it-helpdesk)