Writing MCP Docs an Agent Can Actually Use

Two Audiences, One Markdown File: Writing MCP Docs an Agent Can Actually Use - Tanisha Sharma, Bolna & Jyoti Bisht, Independent When an MCP server exposes documentation.search and documentation.fetch, its docs site quietly acquires a second reader: the agent. And the agent is not a small human. Humans want narrative tutorials; agents want flat, deduplicated, single-source-of-truth pages. Humans skim; agents tokenize. Humans tolerate ambiguity; agents hallucinate from it. This talk is a field report from rewriting an MCP server's documentation to serve both audiences from one markdown source. Concrete before/after pages, real agent traces from the SuprSend MCP server (used as a case study not a pitch), the five rewrite rules that actually moved the needle on hallucination rates, and the surprising downstream effect: the human-facing docs got better too. Every rule generalizes to any MCP server with public docs. Closes with two open questions the audience is invited to argue back at: should agent-facing docs be a separate channel? Should MCP add a "documentation" primitive at the protocol level? For DevRels, technical writers, and MCP server maintainers who already exposed their docs as a tool or are about to.