API strategy
Agent infrastructure
llms.txt for APIs explained: what the spec proposes, how it differs from OpenAPI and robots.txt, and where it stops short for real agent projects.
The llms.txt file showed up in September 2024 as a small proposal with a big ambition: give large language models a single, predictable place to find the machine-readable version of your site. Since then it's been adopted by documentation platforms, discussed in every API design forum, and cited in a lot of agent-readiness pitches. It's also been misread. llms.txt is not an API contract. It's not a tool manifest. It's a discovery file.
Our view: llms.txt is a useful convention for making documentation legible to models at inference time, and it's actively unhelpful when teams mistake it for the runtime layer their agents need. This piece walks through what the spec actually says, how it differs from robots.txt and OpenAPI, what it does for API documentation, and where the gap starts. Five sections, then a look at what comes after llms.txt in a real agent project.
The llms.txt proposal was published by Jeremy Howard in September 2024. It defines a Markdown file placed at the root of a domain — /llms.txt — that gives language models a curated map of the site's most important content, in a form they can read in one pass.
The file itself is small. A required H1 with the project name. An optional blockquote summary. Optional sections of Markdown links, grouped under H2 headings, pointing to the pages a model should read to understand the project. There's a second variant, llms-full.txt, which inlines the actual Markdown content of those pages so a model doesn't have to fetch each URL separately.
That's it. No JSON schema. No auth section. No endpoints, methods, or parameters. It's a table of contents, written in Markdown, addressed to a reader that lives inside a context window.
The design choice matters. HTML is noisy — nav, footers, ads, JavaScript-rendered content — and models spend tokens parsing chrome instead of substance. Markdown files served at a known path let a model (or an agent, or a documentation search tool) pull the useful bits directly. For a docs site, that's a real improvement.
The closest analogues are robots.txt and sitemap.xml, and the differences are the whole point.
robots.txtsitemap.xml gives them a full inventory for indexing. Both are addressed to systems that crawl over time and store what they find. llms.txt is addressed to a model reading in the moment — it assumes a small context budget and picks what matters.
OpenAPI is a different animal entirely. It's a formal contract describing endpoints, request and response schemas, authentication schemes, and error models. It's what SDK generators consume. It's what agent frameworks parse to build tool definitions. llms.txt is a pointer to human-readable docs; OpenAPI is a machine-readable specification of behaviour. Treating them as substitutes is the mistake we see most often.
The question isn't "OpenAPI or llms.txt?" It's "how do these two artefacts serve different readers at different moments?" A well-run API surface ships both. The OpenAPI spec defines the contract; llms.txt helps a model find the tutorial, the auth guide, and the migration notes when a developer or agent asks a question about your platform.
Within its actual scope — inference-time discovery of documentation — llms.txt earns its place. Three concrete wins:
Curated over crawled. A model reading sitemap.xml gets everything: changelog entries from 2019, deprecated endpoints, marketing pages. A model reading llms.txt gets what you decided matters. That's a real signal, and it's cheap to produce.
Markdown over HTML. Serving your docs in Markdown at predictable URLs — either linked from llms.txt or inlined in llms-full.txt — cuts token cost and improves accuracy. Documentation platforms including Mintlify, ReadMe, and Fern now generate these files automatically. Anthropic and OpenAI both publish llms.txt for their developer docs.
Discoverability without indexing lag. A model doesn't need to have crawled your site last week to know what's there. If it can fetch yourdomain.com/llms.txt when a question comes in, it gets your current documentation, not a stale copy. This is closer to how agents actually work: pull-based, at request time, scoped to the task.
What this adds up to is agent-ready API documentation in a narrow sense — the docs are legible to a model that's trying to answer a developer's question or scaffold a first integration. That's genuine value. It's also the ceiling of what llms.txt was ever designed to do.
The pitch we hear from a lot of teams is that publishing llms.txt makes their API "agent-ready." It doesn't, and the gap is worth being precise about.
An agent calling your API in production needs several things llms.txt doesn't provide:
POST /v1/invoices expects, what it returns, and what errors it can raise. That's OpenAPI territory. llms.txt can point at the OpenAPI file, but pointing at a spec is not the same as consuming one. See our earlier piece on OpenAPI specification best practices for what an agent-legible spec actually looks like.llms.txt says nothing about OAuth flows, scope granularity, or delegated access. An agent acting on behalf of a user needs a real auth path, not a link to "Authentication.md."llms.txt describes what's in the docs. It can't describe what isn't in the API.The last point is the one that catches teams late. You publish llms.txt. Your docs are clean. Your OpenAPI spec is current. Your agent still can't complete the workflow, because the workflow requires actions your API doesn't expose. Documentation quality doesn't fix an access gap.
This is why we treat llms.txt as a piece of a larger picture, not a strategy on its own. It's a good hygiene move for documentation. It's a bad answer to "how do we make our product agent-ready?"
If llms.txt is the discovery layer, what sits underneath it for agent-facing APIs?
Three things, in order of specificity:
A current OpenAPI spec, generated from the code, not maintained by hand. Hand-maintained specs drift. Generated specs stay honest. We've written the step-by-step version of this and the drift problem it solves. The spec is what SDK generators, MCP server generators, and agent frameworks actually read.
Documentation shaped for the reader you have. Human developers want tutorials and reference. Models want compact Markdown they can pull at inference time. Agents want tool descriptions written in the imperative, with disambiguation between similar tools baked in. These are three different jobs. llms.txt helps with the second. The third is a design discipline in its own right — see how to write tool descriptions for LLM agents.
A runtime that actually executes. Documentation, however well-shaped, does not run. An agent that reads your llms.txt, understands your OpenAPI, and knows what tool to call still needs somewhere to call it — with the right auth, the right rate-limit handling, and observability that survives production. That's a different layer from the docs, and it's the layer most agent projects underestimate.
The emerging pattern for machine-readable API docs is a stack: llms.txt for discovery, OpenAPI for contract, tool definitions for agent framing, and a runtime for execution. Teams that ship all four have agent-ready products. Teams that ship only the first have agent-ready marketing.
Most of the SaaS companies we talk to have working API documentation and are still stuck on their agent projects. The reason is the one llms.txt can't touch: their APIs cover a fraction of what their products can do, and no amount of documentation polish changes that.
Pontil sits in the tools layer of the agent stack. We scan the codebase, generate connectors from the APIs that exist, and run them in a managed runtime where tool calls execute as the authenticated user. The OpenAPI spec stays the contract, the docs stay legible, and llms.txt continues to do its useful, narrow job. The difference is that the tools an agent needs are generated, maintained, and run — not left as an exercise for the reader.
If you're publishing llms.txt this quarter, ship it. It's a good move. Just don't confuse it with the thing that actually closes the gap between your product and the agents trying to use it. If that gap is where you're stuck, our product page is the shorter version of this argument.
The convention will settle. Formats often do — robots.txt became a de facto standard quickly but wasn't formally standardized until RFC 9309 in 2022, and sitemap.xml still isn't a formal standard. llms.txt will likely pick up structure around auth hints, versioning, and links to formal specs, and adoption will spread past documentation platforms into API providers directly. That's healthy. A predictable discovery file is a small piece of infrastructure that costs almost nothing to publish and saves models real tokens at read time.
The harder question is whether the industry keeps its expectations calibrated. llms.txt is not the reason your agent will work in production. It's a signpost pointing at the docs. The docs point at the API. The API points at some fraction of your product. Closing the rest of that chain is the actual project, and it lives well below the file at your domain root.
So: publish llms.txt. Keep your OpenAPI honest. Then ask the question the discovery file can't answer for you — what can your agent actually do once it finds you?
Stay up to date on the ever changing agentic landscape.
GET STARTED
Start with a 30-minute discovery call
contactus@pontil.com
