Write a Table of Contents for Agents, Not a Marketing Page

Whether to implement llms.txt depends on your Agent's judgment cost. If it only takes 500 tokens for the Agent to decide whether to use your software, this directory structure is suitable for teams with complex documentation, many tools, and users complaining about quotas. Just dumping llms.txt into the root directory usually isn't enough.

On day one, I split up the documentation for an internal imaging tool into llms.txt. Tokens are the unit of measurement for how models process text; llms.txt is like a site directory meant for Agents. I wrote down the tool name, entry point, applicable scenarios, and scenarios where it shouldn't be used, all in my local Markdown editor. I fed it to Claude. It asked me what task this tool solves. I said "retrieving reports," and it immediately started asking for API docs. That's when I realized I was still writing in a marketing tone—listing what exists but not when to use it.

By day three, I made three changes: specified the approximate token count per page, marked which pages shouldn't be crawled, and defined which tasks require human confirmation. Then I ran WorkBuddy. I've been using this tool for a month. It didn't swallow the entire documentation set like before; instead, it read the directory first, then picked a specific page. Previously, the Agent was like an intern who reads through a stack of materials indiscriminately; now it has navigation and knows which page to go to first. There are cases where a single REST API quick-start doc can hit 193,217 tokens. Stuffing that directly into an Agent leads to truncation, skipping, and potentially hallucinated answers. My docs aren't that big, but as long documents pile up, quota consumption drops visibly.

A week later, I hooked it up to multi-step tasks and tried MCP, which I had just started learning. MCP is a socket for connecting Agents to external tools. In the past, if I asked it to check interfaces, generate examples, and validate parameters, it would often re-read the same chunk of documentation repeatedly. Now, I give it a short directory first. The step where it decides whether to use your software is fast; the actual calls expand from there. What we save is trial-and-error.

Directories save context and reduce blind crawling, giving product docs an entry point readable by machines. It's not an SEO plugin; writing it doesn't automatically make things accurate. If the directory description sounds like marketing, the Agent gets misled; if tool boundaries aren't clear, it makes incorrect calls; if the directory isn't maintained after doc updates, it's worse than having nothing.

My take is to start with a short directory page for high-frequency tools—don't try to cover everything. Like AI imaging entering clinical departments, doctors' feedback often highlights the fear of "having to review everything again." Agents reading software feel the same way: let them use a very short context to decide whether to enter your workflow.