The 98% Context Reduction Pattern

Official Sources#

Most agent systems waste context by default.

They call a tool. The tool returns a large JSON blob. The model reads the blob, chooses the next tool, gets another large blob, and repeats. After a few steps, the context window is full of intermediate data the agent no longer needs.

The result is familiar: slower runs, higher costs, worse reasoning, and failures that look mysterious until you inspect the transcript.

The fix is simple but underused: keep intermediate state outside the model context.

Anthropic's recent engineering work around code execution with MCP points at this pattern. Instead of making the model directly inspect every row, page, or event, give the agent an execution environment where it can write small programs, process data locally, and return only the answer, the evidence, and the receipt.

For the foundation, read progressive disclosure in Claude Code and the context engineering guide. For the same discipline applied to a skill's reference material, see how linked skill files fetch remote context only on demand. This post is the implementation pattern.

The Bad Loop#

A naive agent loop looks like this:

agent -> list all customers
tool -> returns 10,000 rows
agent -> filter for accounts with failed invoices
tool -> returns 1,200 rows
agent -> inspect invoice events
tool -> returns 30,000 events
agent -> summarize failures

The model context becomes a data warehouse. That is not what a language model is good at.

Even if the context window is large enough, the reasoning quality suffers. The model has to search through raw data, remember which parts matter, and avoid being distracted by irrelevant fields.

Large context is useful. It is not a substitute for data processing.

The Better Loop#

A better loop gives the agent a place to compute:

agent -> write a script that queries customers, joins invoices, filters failures, and outputs a compact report
execution environment -> runs the script
tool -> returns summary, counts, source IDs, and errors
agent -> reasons from the report

The model does not need every row. It needs the result and enough evidence to trust it.

The difference is not cosmetic. It changes the shape of the whole agent system:

• raw data stays in the execution environment
• intermediate files stay on disk
• logs stay in traces
• the model sees compact outputs
• humans get receipts they can audit

That is the 98% context reduction pattern.

What Belongs Outside Context#

Move these out of the model context whenever possible:

• full database query results
• full API responses
• raw HTML pages
• large logs
• dependency trees
• generated intermediate files
• repeated tool schemas
• long test output after the first failure

Keep these in context:

• the user goal
• relevant constraints
• a compact summary of findings
• source IDs or links
• the current plan
• the final diff or artifact
• the next decision that needs reasoning

The model should reason. Code should crunch.

Filesystem State Is Agent Memory#

The most underrated memory primitive is still the filesystem.

If an agent processes 50 files, it does not need to paste the full contents of all 50 into context. It can write:

.agent-work/
  findings.json
  failing-tests.txt
  candidate-files.txt
  summary.md

Then it can read the compact summary when needed. The raw evidence remains available without living in the prompt forever.

This is why local coding agents feel powerful. They can use files as durable scratch space. The context window becomes the active working set, not the entire workspace.

The Receipt Format#

A good reduced-context tool response should include:

{
  "summary": "Found 18 failed invoices across 7 customers.",
  "counts": {
    "customersScanned": 10421,
    "failedInvoices": 18,
    "affectedCustomers": 7
  },
  "evidence": [
    "customer_123 invoice inv_456",
    "customer_789 invoice inv_999"
  ],
  "filesWritten": [
    ".agent-work/failed-invoices.csv",
    ".agent-work/invoice-summary.md"
  ],
  "nextSuggestedAction": "Inspect payment provider webhook logs for these invoice IDs."
}

The model can act on that. The human can audit it. The raw data is still available if deeper inspection is needed.

How to Apply This Today#

You do not need a new framework.

For Claude Code, ask it to write analysis scripts and keep raw outputs in files. For MCP servers, expose workflow tools that process data server-side and return receipts. For custom agent apps, add a workspace directory and persist intermediate state between steps.

The architecture is boring:

1. Let the agent create a script or query.
2. Run it in a scoped environment.
3. Save raw outputs to files.
4. Return a compact summary.
5. Keep links back to evidence.

That boring pattern is what makes long-running agents cheaper and more reliable.

The Bottom Line#

Context is not a trash can.

Efficient agents keep the model focused on decisions and keep intermediate state in the systems built for it: code, files, databases, logs, and traces. The best agent architectures do not ask the model to remember everything. They give it a reliable way to retrieve what matters.

That is how you cut context without cutting capability.

Continue Reading#

• MCP tools need a shared board, not another transcript
• Point Your Agent at Developers Digest

Sources#

• Anthropic Engineering: Effective context engineering for AI agents
• Anthropic Engineering: Code execution with MCP
• DevDigest: Progressive Disclosure: How Claude Code Cut Token Usage by 98%
• DevDigest: Context Engineering Guide

Frequently Asked Questions#

What is the 98% context reduction pattern?#

The 98% context reduction pattern is an agent architecture approach where intermediate data - database query results, API responses, raw logs - stays outside the model's context window. Instead of pasting full datasets into the prompt, agents write scripts that process data in an execution environment and return compact summaries with evidence links. The model reasons from summaries rather than raw data, cutting context usage by 90-98% on data-heavy tasks while improving reasoning quality.

Why does context reduction improve agent reliability?#

Large context windows do not equal better reasoning. When models process thousands of rows or pages of raw data, they get distracted by irrelevant fields, lose track of the goal, and make extraction errors. Context reduction forces the agent to process data programmatically - where code is reliable - and reserve the model for decisions where reasoning matters. The result is fewer hallucinations, faster runs, and lower token costs.

How do I implement context reduction in Claude Code?#

Ask Claude Code to write analysis scripts rather than reading data directly. For example, instead of "show me all failing tests," say "write a script that runs the test suite, captures failures, and writes a summary to .agent-work/failures.md." Claude Code will create the script, run it, and read the compact output. The raw test output stays in files, not in context. This pattern scales to database queries, log analysis, and any data-heavy task.

What should stay in context vs. outside context?#

Keep in context: the user goal, relevant constraints, the current plan, compact findings, source references, and the next decision. Move outside context: full query results, raw API responses, large logs, dependency trees, generated files, repeated tool schemas, and verbose test output after the first failure. The rule is that the model should reason about decisions while code handles data processing.

Does this pattern require MCP or special tooling?#

No. The pattern works with any agent that can write and execute code. Claude Code implements it natively - the agent writes scripts, runs them, and reads outputs. MCP servers can implement it by returning receipts instead of full payloads. Custom agent apps implement it by adding a workspace directory for intermediate state. The tooling is optional; the architecture is the point.

How does filesystem state act as agent memory?#

Files are durable and cheap. An agent processing 50 documents can write findings to .agent-work/findings.json instead of keeping all 50 documents in context. On subsequent turns, it reads the compact summary file rather than re-processing. The filesystem becomes a working memory that persists across reasoning steps without consuming context tokens. This is why local coding agents feel powerful - they have natural scratch space.

What is a receipt in context reduction?#

A receipt is a compact tool response that includes a summary, counts, evidence links, files written, and a suggested next action. It answers the question "what happened and where can I verify it?" without including the raw data. For example, a database query receipt might say "Found 18 failed invoices across 7 customers" with IDs and a CSV path, not 18 full invoice objects. The agent acts on the receipt; the human can audit the files.

Does context reduction work with long context models?#

Yes, and it becomes more important with longer context windows. A 200K token window can hold more data, but that does not make the model better at processing data. Long context creates the illusion that stuffing everything into the prompt is fine. In practice, agents with long context and no reduction pattern still hit reasoning degradation, slower responses, and higher costs. Treat long context as headroom for complex reasoning, not storage for raw data.