A real API's OpenAPI spec is often too large to paste into an LLM chat and get a reliable answer back. GitHub's public spec runs about 9.9 MB, Stripe's about 6.4 MB, Cloudflare's about 18.1 MB across 2,222 paths — all measured directly from the vendors' own repos. Pasted whole, a file that size chews through an enormous token budget before the model reads your actual question, and even models with large context windows get measurably worse at following instructions as they approach the ceiling. The fix isn't a bigger context window. It's not sending the whole spec: llms.txt, per-operation Markdown, an MCP server, or a filtered slice, depending on the job.
How big is "too large," concretely
These three sizes are measured directly from each vendor's public OpenAPI repo, covered in more depth in our own typed-client posts:
| API | Spec size (YAML) | Paths / operations | Source |
|---|---|---|---|
| GitHub | Full REST surface — repos, issues, Actions, Packages, billing | github/rest-api-description, covered in our GitHub client post | |
| Stripe | Full payments surface, 2,300+ anyOf/oneOf sites |
stripe/openapi, covered in our Stripe client post | |
| Cloudflare | 2,222 top-level paths across every Cloudflare product | cloudflare/api-schemas, covered in our Cloudflare client post |
These aren't edge cases. Any API that's grown for a few years across dozens of resource groups ends up in this range — a spec doesn't need to be famous to hit multiple megabytes, it just needs enough endpoints.
Why pasting the whole spec into a chat fails
A few compounding problems, not just one:
- Token cost. Plain text runs roughly one token per four characters. A 10 MB spec is on the order of several hundred thousand tokens before your prompt starts — expensive on a per-call basis, and slow, even against models with genuinely large context windows.
- Degraded instruction-following near the ceiling. Models get measurably less reliable at precise tasks — like "find the exact request schema for this one operation" — as the amount of loaded context grows, independent of whether the window technically fits. A near-full context window is not the same as a comfortable one.
- You're paying for 99% you don't need. A single integration task usually touches a handful of operations. Loading Cloudflare's full 2,222-path spec to ask about one DNS endpoint wastes nearly all of that budget on paths the model will never reference.
- Tooling chokes first. Before an LLM ever sees it, your editor, diff tool, or IDE may already be struggling — GitHub's and Cloudflare's specs are both large enough that syntax highlighting and diffing slow down noticeably in normal editors, as noted in our per-API posts.
The practical result: ask an agent a question against a pasted multi-megabyte spec, and you get slow responses, higher cost, and a real chance it answers from the wrong section of the document or misses the operation entirely.
Strategy 1: llms.txt — a curated index instead of the whole spec
Instead of the full spec, give the agent a small Markdown file that says what the API does and links to the specific pages worth reading. That's exactly what llms.txt is for: a top-level orientation, then ranked links to per-endpoint reference pages, so the agent reads a few hundred words before deciding which operation's full detail it actually needs. Sourced's llms.txt generator builds this directly from your OpenAPI spec — endpoints grouped by tag, schemas summarized, regenerated on every spec push — which is the fastest way to get from "18 MB spec" to "an agent can navigate this in one read." See the implementation guide for exactly what sections to include for an API specifically.
Strategy 2: per-operation Markdown pages
llms.txt is the index; per-operation Markdown pages are what it points to. Instead of one giant spec file, each operation gets its own small .md page — request shape, response shape, one example — that an agent fetches only when it needs that specific call. This is the same principle as paginating a book instead of shipping it as one unbroken scroll: the agent's context stays proportional to the task, not to your entire API surface. Hosted docs platforms that emit clean Markdown per page (not just HTML) make this strategy free to adopt; see the llms.txt format reference for how the linking convention works.
Strategy 3: MCP servers — expose operations as callable tools, not text to read
For agentic workflows specifically, the strongest fix skips "reading the spec" entirely. An MCP server turns each OpenAPI operation into a typed tool the agent calls directly, with the argument schema doing the work a paragraph of prose would otherwise need to convey. The agent's context holds a short list of tool names and descriptions — dozens of tokens each — not the full request/response schema for every operation in the API. Sourced's OpenAPI-to-MCP generator and managed host builds this from the same spec, exposes safe read tools by default, and flags destructive operations separately. This is also the strategy behind the prompt pack for generating an SDK and MCP server from a spec — the agent never sees the raw spec at all once the tools exist.
Strategy 4: slice the spec by tag before generating anything
If you need to run codegen or validation against a large spec directly — not just make it agent-readable — filter it first. Both our GitHub and Cloudflare posts cover this: a tool like openapi-filter cuts a multi-megabyte spec down to just the tags you use (repos and issues, say, instead of GitHub's entire surface), which shrinks both the generation time and whatever you next feed to an LLM. Validate the full spec once with the OpenAPI validator, then work from the filtered slice for anything agent-facing.
Which strategy for which job
| Job | Best strategy |
|---|---|
| Agent needs to decide whether your API is relevant | llms.txt |
| Agent needs the exact shape of one operation | Per-operation Markdown page |
| Agent needs to actually call the API mid-task | MCP server |
| You're running codegen or a validator locally against a huge spec | Tag-based slicing |
| You want all of the above from one spec, generated together | Sourced free preview |
Honest scope: when you don't need any of this
If your spec is a few hundred KB and covers a couple dozen operations, none of this is necessary — paste it directly, most agent chat interfaces handle that fine. This problem shows up specifically once a spec crosses roughly a megabyte or a few hundred operations, which in practice means large platform APIs (payments, cloud infra, source control) more than a typical internal service API. Check your own spec's size before assuming you need llms.txt, MCP, and slicing all at once — often one of the four is enough.
FAQ
How large does a spec have to be before this becomes a real problem?
There's no hard cutoff, but specs in the multi-megabyte range with hundreds of operations — like GitHub's ~9.9 MB or Cloudflare's ~18.1 MB — reliably cause both tooling slowdowns and poor LLM performance when pasted whole. A spec under a few hundred KB with a few dozen operations usually pastes fine.
Does a bigger context window solve this?
Not by itself. Even when a spec technically fits, models get less reliable at precise, instruction-following tasks as the loaded context grows toward the model's limit. A large context window makes pasting possible; it doesn't make it a good idea for a task that only needs a handful of operations.
What's the difference between llms.txt and an MCP server for this problem?
llms.txt is a reading aid — it helps an agent (or a human) find the right page faster. An MCP server is an execution aid — it lets the agent call the operation directly as a typed tool, without reading a spec at all. Most agentic workflows benefit from both: llms.txt for orientation, MCP for action.
Can I generate llms.txt, per-operation docs, and an MCP server from the same OpenAPI spec?
Yes — that's the point of generating all three from one source rather than maintaining them separately. Sourced produces all three from one spec upload, and the best SDK generator for AI agents comparison covers how other tools handle the same three outputs.
Should I slice my spec permanently, or just for this?
Keep the full spec as your source of truth and generate slices on demand for specific agent tasks or generator runs. A permanently split spec is harder to keep consistent — cross-references between operations in different files are easy to break.
Where do I start if I just have one large spec file?
Run it through the OpenAPI validator first to confirm it's clean, then either generate an llms.txt or an MCP server depending on whether you need an agent to read about your API or call it. Create hosted docs from your repo does both plus SDK previews in one pass.