Token-Efficient API Docs: Why Verbosity Costs You Agent Traffic

An AI agent pays for your documentation by the token. Every page it fetches gets tokenized and loaded into a finite context window — working memory the docs share with everything else the agent is doing: the user's request, the conversation so far, the code it is writing, the output of every other tool in play. Documentation that spends ten pages saying one page's worth of facts is spending the agent's memory, and a budget-constrained reader responds predictably. It truncates, it skims, or it skips you entirely.

Human readers hide this problem from you. A developer skims a bloated page, forgives it, and finds the fact eventually. A model has a hard ceiling, and everything past the ceiling might as well never have been written. This is why token-efficient documentation is an agent traffic concern and a core part of agent-readiness: the concept is how much reading an agent must do before it can operate your API; the measurement behind it is what the Discry methodology calls tokens-to-comprehension. The scan artifacts behind the Discry Index surface this pattern constantly, and the failure modes are specific enough to edit against.

How an agent actually consumes your docs

The pipeline has three steps, and token weight taxes every one of them.

Fetch. An agent arrives over plain HTTP, without executing JavaScript, and looks for machine-readable entry points: an llms.txt, an AGENTS.md, an OpenAPI spec. Whatever renders on that plain fetch is what exists, as far as the agent is concerned.

Fit. The fetched material has to fit into the context window alongside the actual task. The docs are a guest in that window, and the window has other tenants. An agent (or the harness driving it) decides which pages to load, how much of each, and what to drop when the budget runs out. Nothing about that selection process rewards thoroughness; it rewards density.

Answer. The model works from whatever survived the fit. If your rate-limit rules sat at the bottom of a page that got truncated, the agent doesn't know it's missing them — it answers from what it has, confidently, and the resulting bad request lands as a support ticket that blames your API.

Everything in that pipeline happens before a single API call, which is exactly the territory the Discry Score measures: whether an agent can find a usable version of your docs, and whether it can operate your API from what it found.

What verbosity costs

Three distinct failure modes show up in scan artifacts, and they compound.

Truncation. When the material an agent needs won't fit, something gets cut, and the agent doesn't get to choose wisely — it can't weigh a fact it never read. The monolith is the classic case: Alpha Vantage publishes its entire reference as a single page that weighed roughly 780KB at scan time, with no llms.txt and no smaller entry point. An agent that needs one endpoint's parameters must ingest — or truncate — the whole thing.

Wrong-page selection. Bloat in the index is worse than bloat in the pages, because it corrupts the agent's map. ClickHouse passes the llms.txt discovery check — the file exists — but at scan time it was a ~92KB site-wide dump that mixed legal pages, blog newsletters, and campaign links into the same list as the API reference, costing an agent on the order of twenty thousand tokens of link-scanning before the documentation even started. An index like that actively routes agents to the wrong pages; a missing index at least fails honestly.

A higher model tier required. Routing routine work to lower-cost models is standard industry practice — cost-based routing and model cascades are how production agent fleets control unit economics. Dense, well-organized docs let a small model find and apply the facts it needs. Bloated docs demand a model that can hold more and filter harder, which raises what the Discry methodology measures as the capability floor: the lowest tested model tier that reliably operates your API from its docs, labeled small-model ready, advanced-model required, or frontier required. The argument follows directly: if only frontier models can find the signal in your noise, you are invisible where the volume is. A team whose docs are small-model ready gets chosen by the cheap, high-volume tier of agents; a team whose docs demand frontier attention competes for a much smaller pool.

What token-efficient looks like in the corpus

The APIs that handle this well share a shape: a small, curated entry point that orients the agent fast, with heavier material one deliberate hop away.

Spotify's llms.txt was 668 bytes at scan time — a concise file that links directly to the OpenAPI spec and a building-with-AI tutorial. Supabase ships an llms.txt that delivers structured progressive disclosure in well under two thousand tokens, linking out to per-SDK references. Cloudflare layers it: a compact root index linking to per-product llms.txt files, each of which links to a product-scoped llms-full.txt, so an agent only ever pays for the product it came for.

The heavier end of the corpus makes the same point from the other direction. Snowflake's llms-full.txt weighed about 52MB at scan time, spanning tens of thousands of sections — thorough by any human standard, and past what an agent's budget can practically consume in one pull. Completeness and token weight are different axes; a bundle can score full marks on the first and still fail an agent on the second.

Two APIs in the corpus treat the budget itself as a documented interface. Paddle splits its llms.txt into per-section files specifically to stay under truncation limits, alongside an LLM-specific sitemap and markdown twins for its pages. Payabli goes further: its llms-full.txt endpoints accept query parameters to strip the embedded OpenAPI spec or filter SDK examples to a single language, with the response-size tradeoffs documented per endpoint. That is documentation written by a team that understands its reader pays per token.

Editing moves that cut weight without cutting facts

None of these require new tooling. They are editorial decisions, applied to the surfaces agents actually fetch.

Put the answer first. Open every page and every section with the fact — the endpoint's purpose, the auth scheme, the limit — and let context and narrative follow. Agents (and the retrieval systems feeding them) weight the top of what they load; a page that spends four paragraphs on philosophy before naming the base URL charges the agent four paragraphs of rent for nothing. This mirrors how good docs open for humans, so nothing is lost.

Tables over prose for parameters. "The limit parameter, which is optional, controls the number of results returned per page, up to a maximum of 100, with a default of 25" costs multiples of what a four-column table row costs, and the table is easier to extract facts from mechanically. Parameters, error codes, rate limits, and enum values all belong in tables. Your OpenAPI spec already holds this material in structured form; the prose docs should match its density, and the spec itself should stay fetchable.

One canonical example, not five variants. A single copy-pasteable request with realistic values teaches an agent your API's shape. Five near-identical variants teach the same shape five times and charge for each. Keep one canonical example per operation on the main path, and move language-specific variants behind links or filters the way Payabli does — the agent that wants Python should be able to pay for Python alone.

Treat llms-full.txt as a curated bundle, not an export. llms-full.txt exists so an agent can load your core documentation in a single request — which only works if the bundle is curated to what an integration needs: auth, core resources, request shapes, errors, limits. Piping your entire site through an exporter produces the Snowflake problem; leaving the file as a copy of your link index produces a bundle with no content at all, a pattern the corpus also contains. Across the APIs we scan, only 31% publish a working llms-full.txt, against 64% for llms.txt itself — so a tight bundle is still a differentiator, and a bloated one squanders it.

Keep agent surfaces free of marketing and navigation. The llms.txt failure pattern we see most often is the site-wide dump: every URL on the domain, blog posts and legal pages included. Your agent-facing index should contain your API documentation, grouped by task, one line of description per link — the format the llms.txt guide walks through. The same discipline applies inside pages: one API in the corpus expands a glossary tooltip into a full inline definition at every occurrence of common words, so an agent pays a repeated token tax on every page it reads.

Weigh your docs before an agent does

Token weight is measurable in an afternoon, with the same tokenizers agents use.

For OpenAI-family models, tiktoken tokenizes any text locally: fetch a docs page as it renders on a plain HTTP request (curl, then strip to text), run it through the encoder, and read the count. For Anthropic models, the API exposes a token-counting endpoint that reports exactly what a prompt costs before you send it. As a rough planning heuristic, a token is on the order of four characters of English text — a 100KB page is in the neighborhood of 25,000 tokens before an agent has done any work with it.

Weigh three things: your llms.txt (an agent's first fetch — per the llmstxt.org spec it should be a curated index, and its weight should reflect that), your llms-full.txt bundle, and the two or three pages an integration cannot avoid — auth, your core resource, errors. Then ask the editorial question: how many of those tokens carry a fact an agent needs, and how many are navigation, repetition, or narrative? The ratio is your editing backlog, and shorter multi-step guides compound the win — an agent sequencing a multi-step workflow pays the weight of every page in the chain.

The cheapest fix on the page

Token efficiency is unusual among agent-readiness work: it requires no new infrastructure, no protocol adoption, and no engineering sprint. It is editing — the kind your docs likely need for human readers anyway, applied with the knowledge that your fastest-growing readership has a meter running. The teams treating agents as a first-class documentation audience are already structuring for it, and the corpus shows agents reward them for it.

What grade does an AI agent give your API? Discry your API — free — 60 seconds, no signup.