Context rot: what it is and how to reduce it with your docs

Context rot is the deterioration in an LLM's response quality that happens as the amount of information in its context window increases. If your customers use coding agents to retrieve parts of your docs, context rot can affect their ability to correctly install and work with your software.

Most fixes for context rot target the agent: summarizing or compacting chat history, storing memory outside the context window, or handing tasks to subagents with fresh context. Context engineering tools cover that side. But the agent can only work with what it retrieves, so another way to reduce context rot is to optimize the docs agents read when working with your API, SDK, or product.

This guide covers what context rot is, why it happens, and which changes to your docs reduce it. Get those changes right, and customers complete integrations with fewer errors while your team fields fewer support tickets.

Key points on context rot

• Context rot makes LLMs less reliable at using available information as context grows, even when input remains within the context window.
• Docs teams can reduce context rot for their customers with a few docs-side fixes, such as letting agents query pages instead of pasting them in and keeping each page to one task.
• To keep agent context lean and current, Mintlify hosts an MCP server for every site, generates llms.txt and skill.md, and suggests docs updates from merged PRs through Autopilot.

What is context rot?

Context rot is a drop in an LLM's accuracy that happens well before its context window is full. As the model has more to sort through, it starts overlooking information that it may have used correctly earlier in the conversation.

When an agent gets your API wrong, context rot is only one possible cause. Use the table below to tell it apart from problems with similar symptoms.

Problem	Symptom
Context rot	Agent regresses mid-session, ignoring instructions or API constraints it followed earlier
Context overflow (exceeding the token limit)	Hard API error or automatic truncation because the prompt exceeded the token limit
Stale or inaccurate docs	Agent produces broken code even in a fresh session
Hallucination	Agent invents endpoints or parameters in a fresh session because it lacks knowledge
Error cascading	Agent latches onto a previous mistake in the chat history and treats it as fact

These problems often compound. Stale docs and earlier mistakes add more noise, which means a higher chance of context rot. But context rot is the one that shows up mid-session, after the agent got things right.

What causes context rot?

Context rot has two sources: limits in how models process long inputs, and the content that fills those inputs. You can't change how models work, but you control much of the content they ingest.

Attention becomes less reliable as context grows

Models use attention mechanisms (calculations that help determine how different pieces of text relate to one another) to process information. As context grows, models must process more relationships between pieces of text, and they can become less reliable at identifying and applying the information relevant to the current task.

In its evaluation of 18 models, Chroma found that model performance generally became less reliable as context length increased, although results varied by model and task. Anthropic describes this limitation using the concept of an "attention budget," explaining that LLMs, like humans, have limited working memory capacity to process large volumes of information.

Information in the middle can be harder to use

Language models often perform worse when the information they need is located in the middle of a long input, a problem known as the "lost in the middle" phenomenon.

In the study Lost in the Middle: How Language Models Use Long Contexts, researchers found that models often performed better when relevant information appeared near the beginning or end of an input, but performance often declined when relevant information appeared in the middle.

Look-alike content can distract the model

When docs contain multiple similar examples, an agent may have difficulty identifying which instructions apply to its task.

For example, an SDK might have separate methods for creating a customer record and updating one. If an agent retrieves docs for both, it may confuse the methods and generate code that creates a new record instead of updating an existing one.

Stale information adds conflicting instructions

Outdated docs can cause agents to generate incorrect code because the instructions they retrieve no longer match the current software. Even when current instructions are available, stale information can still influence an agent's response, causing it to generate code that fails.

Consider an outdated tutorial that references an API endpoint that has since been replaced. If an agent retrieves that tutorial alongside the current API reference, it may generate code using the obsolete endpoint.

Signs an agent is hitting context rot

Context rot can cause coding agents to mishandle your docs as customer development sessions progress. The resulting errors affect integrations even when your docs contain the correct instructions. The table below lists the most common context rot patterns and gives examples of what it looks like.

Sign	What it looks like
Repeats failed attempts	Reintroduces code changes that have already failed testing, despite receiving feedback explaining the errors
Ignores earlier instructions	Violates a project constraint set earlier, such as switching from TypeScript to JavaScript midway through implementation
Invents methods or fields	Generates code using nonexistent API methods or unsupported fields after correctly using the documented API earlier in the session
Agrees with incorrect assumptions	Late in a long session, drops an earlier correct decision when the developer pushes back, such as accepting that a required API parameter is optional
Blends feature logic	Applies permission rules from one feature to another, such as allowing view-only users to modify inventory

When these signs show up in your customers' sessions, the fix doesn't have to wait for a better model. Much of it starts with what your docs put into the agent's context.

How to reduce context rot with your docs

Documentation publishers can reduce the risk of their customers experiencing context rot by controlling how their content is organized and maintained. Structured documentation helps coding agents find relevant instructions without retrieving unnecessary or conflicting information.

Let agents query docs instead of pasting them in

Host an MCP server or search endpoint so agents can retrieve only the docs they need, including relevant code examples. Less unnecessary context means less risk of context rot.

When docs lack direct, structured retrieval tools, developers may paste thousands of words of reference material into chat prompts or configure their agents to scrape full URLs. Both approaches load unnecessary content into the context window before any code is written. That raises the risk that the agent overlooks relevant instructions or generates incorrect code.

When an agent implements token refresh, for example, it only needs the exchange endpoint schema and header requirements. Through an MCP search tool, it retrieves just those sections rather than ingesting your entire OAuth 2.0 setup guide.

Keep always-loaded files short

Provide concise starter files (AGENTS.md or CLAUDE.md) that customers can copy into their repos, so they don't crowd the context window before development begins. Anthropic recommends keeping CLAUDE.md files under roughly 200 lines.

Limit starter files to project-wide instructions, like supported SDK versions and build commands, to preserve token capacity for the customer's code and conversation history. Link to the relevant doc pages for implementation steps instead of embedding setup guides or schemas.

For example, a starter AGENTS.md that specifies Python 3.12 and links to your billing docs keeps detailed webhook payload schemas out of context.

Write one topic per page

Limit each docs page to a single task or concept so search tools can identify relevant content more accurately.

Say you maintain separate pages for SDK installation and rate limits. When an agent debugs a 429 Too Many Requests error, search tools can retrieve the rate-limit rules directly without pulling installation instructions.

Serve clean Markdown, not rendered HTML

Provide Markdown versions of your documentation pages so agents can access structured technical text without having to extract it from HTML markup.

Rendered web pages wrap technical instructions in site navigation and layout markup. Some agent tools try to strip out that page chrome. Serving Markdown through .md routes or Accept: text/markdown headers skips that step, delivers clean headings and code blocks, and cuts token overhead.

For instance, the rendered HTML of a webhook authentication page carries the sidebar, footer, and scripts along with the instructions. The Markdown version carries only the instructions and code.

Remove outdated and duplicate content

Remove obsolete guides and consolidate overlapping content to reduce conflicting instructions in search results. When duplicate tutorials or older versions remain searchable, agents may retrieve competing implementation examples and risk combining incompatible approaches. If you still support older versions, keep those pages live for readers but exclude them from search indexing, so agents retrieve only current instructions.

For example, a deprecated tutorial might use callbacks while the current guide uses async/await. An agent retrieving both may generate code that passes a callback to a promise-based method.

Keep docs current as the code changes

Update your docs alongside software changes so agents can retrieve instructions that match the current API.

Every change to an endpoint route or parameter schema makes existing guides obsolete until someone updates them. To catch those changes before agents do, make docs part of the release workflow: update them in the same pull request as the code change, or add a CI check that flags API changes with no matching docs edit.

For example, when an endpoint changes from accepting a URL query parameter to requiring a JSON request body, publishing revised docs alongside the code release keeps agents from generating requests in the old format.

How Mintlify reduces context rot for agents

Mintlify builds several of the practices above into your site, so agents retrieve only the docs they need and your team keeps those docs current:

• Hosted MCP server: Every Mintlify site includes a hosted MCP server, with tools for searching docs and retrieving individual sections or full pages
• Agent feedback through MCP: Coding agents flag outdated docs through Mintlify's MCP feedback tool, helping your team identify and fix problems before more customers encounter them (in beta on Pro and Enterprise plans)
• Generated discovery and guidance files: Mintlify keeps an llms.txt index of your docs up to date automatically, and public sites on Pro and Enterprise plans also get a skill.md that describes your product's capabilities, inputs, and constraints for agents
• Markdown versions of every page: Agents access Markdown through .md URLs or the Accept: text/markdown header
• Docs that keep up with your code: Autopilot detects merged code changes and opens pull requests that update the affected docs, so agents don't retrieve outdated instructions (in beta on Pro and Enterprise plans)
• Agent traffic analytics: Publishers see which pages coding agents access and what they search for through MCP, helping identify docs that need improvement (on Pro and Enterprise plans)
• Retire old pages without deleting them: Pages marked noindex: true stay live at their URL but drop out of site search, MCP search, and llms.txt by default, so agents retrieve only current instructions

In controlled experiments on a large engineering org's internal repos, agents searching structured Mintlify docs over MCP used about 50% fewer tokens per task than agents with no docs.

Reduce context rot for your customers' coding agents with docs built for accurate, targeted retrieval. Start for free with Mintlify.

Frequently Asked Questions

How do you reduce context rot in Claude Code?

Run /compact to summarize the conversation or /clear to start a fresh session, and retrieve only the docs required for the current step. Keep foundational constraints in a concise CLAUDE.md file. If a product's docs offer an MCP server, connect it with claude mcp add --transport http <name> <url> so Claude Code searches and reads only the sections it needs instead of loading full setup guides into the chat.

What is context rot in AI?

Context rot is the gradual decline in an AI model's ability to use available information accurately as the amount of context increases, even before reaching the model's token limit.

When does context rot start?

There's no fixed token threshold. In Chroma's evaluation of 18 models, performance declined as inputs grew, but the point where it declined varied by model and task. In coding sessions, it shows up as forgotten constraints and invented methods once the chat fills with similar code examples and large payloads.

Does a bigger context window fix context rot?

No. Larger context windows raise the token limit, but they don't stop accuracy from declining as inputs grow. Even with large windows, models still miss instructions buried mid-prompt, so selective retrieval and lean docs still matter.