Context editing: cut agent token bills ~84% by clearing stale tool results

The biggest hidden line item in an agent’s bill isn’t the model — it’s the tool result you fetched 30 steps ago and never stopped paying for. Because an agentic loop re-sends its entire history on every turn, that stale search result, that 8,000-token file dump, that giant JSON payload all get reprocessed on call after call after call. Anthropic now ships an API flag that clears them automatically, and in its own eval it cut token use by 84%. Here’s exactly how it works, the config that matters, the prompt-cache trap that makes it backfire if you’re careless, and the honest test for whether your agent even needs it.

Why long agents get expensive: you re-pay for everything

Start with the mechanic that makes this matter, because it’s the thing most cost write-ups skip.

An LLM API is stateless. Every turn, you send the whole conversation back — system prompt, every user message, every assistant message, and crucially every tool call and every tool result so far. The model reprocesses all of it as input tokens to produce the next step. There’s no “memory” on the server between calls; the context window is the memory, and you pay to refill it each time.

For a chatbot, that’s fine — conversations are short. For an agent, it’s the whole cost story. An agent that browses the web, reads files, and calls tools accumulates results fast, and each one is dead weight after the model has used it:

• A web search returns 6,000 tokens of results. The agent extracts one fact and moves on. Those 6,000 tokens sit in the window for the rest of the run.
• A file-read tool dumps an 8,000-token file. The agent edits three lines. The other 7,900 tokens are now permanent ballast.
• Twenty tool calls later, your “input” on every single turn is a 120,000-token pile of mostly-spent results — and you pay for all of it, every turn, until the run ends or the context window fills up and the agent simply dies.

That’s the shape of the problem: linear accumulation, re-billed per turn. A 40-turn agent doesn’t pay for its context once — it pays for a growing context forty times. This is exactly the kind of cost that never shows up in a per-token price comparison and blindsides teams when the invoice lands (we catalogued more of these in hidden LLM API costs).

What context editing does

Context editing is Anthropic’s server-side answer: automatically drop the stale tool results before they’re reprocessed. You opt in with a beta header and a strategy.

“The clear_tool_uses_20250919 strategy clears tool results when conversation context grows beyond your configured threshold. When activated, the API automatically clears the oldest tool results in chronological order. The API replaces each cleared result with placeholder text so Claude knows it was removed.”

Three things to note in that description:

1. It’s threshold-triggered, not every-turn. Nothing clears until your input crosses the trigger (default 100,000 tokens). Below that, the feature is dormant.
2. It clears oldest-first and keeps the recent ones. The most recent tool interactions — the ones the model is probably still reasoning about — stay. Only the aged-out results go.
3. It leaves a placeholder. The model sees that a result was there and was removed, so it doesn’t hallucinate that the tool was never called. If it needs the data again, it can re-fetch.

The headline number comes from Anthropic’s own testing:

In a 100-turn web-search evaluation, “context editing enabled agents to complete workflows that would otherwise fail due to context exhaustion — while reducing token consumption by 84%.”

Two wins in one sentence, and the second is easy to overlook: it’s not just cheaper, it’s more capable, because runs that used to hit the context ceiling and crash now finish. On Anthropic’s internal agentic-search eval, context editing alone also lifted task performance by 29% — clearing spent tool noise apparently helps the model focus, not just the bill.

The config that actually matters

The minimal call is one line of config. This turns on clearing with all defaults:

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Research recent AI developments"}],
    tools=[{"type": "web_search_20250305", "name": "web_search"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

But the defaults are conservative, and the four tuning parameters are where the savings — and the pitfalls — live:

A realistic production config clears more aggressively than the defaults and protects the tools whose output you can’t afford to lose:

context_management={
    "edits": [
        {
            "type": "clear_tool_uses_20250919",
            "trigger": {"type": "input_tokens", "value": 30000},
            "keep": {"type": "tool_uses", "value": 3},
            "clear_at_least": {"type": "input_tokens", "value": 5000},
            "exclude_tools": ["web_search"],
        }
    ]
}

The response tells you exactly what happened, so you can measure the effect instead of guessing:

{
  "context_management": {
    "applied_edits": [
      { "type": "clear_tool_uses_20250919", "cleared_tool_uses": 8, "cleared_input_tokens": 50000 }
    ]
  }
}

You can also preview the effect before you commit, by passing the same context_management block to the token-counting endpoint — it returns both the post-edit input_tokens and the original_input_tokens, so you can model the savings on real traffic first.

The catch: it breaks your prompt cache

Here is the part that turns context editing from “free money” into “measure first,” and the part most tutorials leave out entirely.

If you run agents at any scale, you almost certainly use prompt caching — it’s the single biggest lever for agentic cost, because it lets you re-read a large static prefix at roughly one-tenth the input price instead of paying full freight every turn. Context editing and prompt caching interact, and not in your favor at the moment of a clear:

“Tool result clearing invalidates cached prompt prefixes when content is cleared. To account for this, clear enough tokens to make the cache invalidation worthwhile. Use the clear_at_least parameter to ensure a minimum number of tokens is cleared each time. You’ll incur cache write costs each time content is cleared, but subsequent requests can reuse the newly cached prefix.”

Unpack that. The prompt cache works on prefixes: everything up to the changed point stays cached, everything after has to be re-written. When context editing deletes a tool result from the middle of your history, it changes the prefix, so the cache below that point is invalidated. The next request has to re-write that cache — and cache writes cost more than a normal input token (on Anthropic, 1.25× base for the 5-minute TTL, 2× for the 1-hour TTL).

So the mental model is: context editing trades a one-time cache-write cost for a permanently smaller window going forward. Over a long run, the smaller window wins many times over. Over a short run, the re-write never amortizes and you’d have been better off leaving the history alone. The clear_at_least parameter is you telling the API where that break-even sits.

(Thinking blocks behave differently, for the curious: when they’re kept, the cache is preserved; they only invalidate it when cleared. Tool-result clearing is the case that always touches the cache.)

When clearing isn’t enough: the memory tool

Clearing has an obvious risk — what if the agent needs that data later? For read-once results (a search it already extracted, a file it already edited), deletion is fine; it can re-fetch. But for facts the agent must carry across the whole run, deletion loses them. That’s what the memory tool is for, and it graduated to general availability — no beta header required:

tools=[{"type": "memory_20250818", "name": "memory"}]

The memory tool lets Claude read and write files in a store you host. It’s client-side: Claude requests an operation (view, create, str_replace, insert, delete, rename), your application executes it against real storage under a /memories prefix, and returns the result. Files persist across sessions, so an agent can build a knowledge base over days, not just survive one long run.

The elegant part is how it pairs with context editing. As the window approaches the clear threshold, the API injects a system nudge — effectively “old tool results are about to be cleared” — and Claude can proactively write what matters to a memory file before it disappears. Clearing then removes the bulky raw result from the window while the distilled fact lives on in a file the agent can re-read on demand. This is “just-in-time” context: keep references in the window, load the actual data only when needed.

The numbers back the pairing. On Anthropic’s internal agentic-search eval, the memory tool combined with context editing improved performance 39% over baseline — better than context editing’s 29% alone.

Context editing vs compaction vs memory

Anthropic now ships three overlapping context-management tools, and picking the wrong one wastes effort. The short version:

The distinction between the first two is worth holding onto: context editing is surgical (drop these specific spent results, keep everything else intact), while compaction is a rewrite (summarize the entire history into a shorter form and throw away the original). Editing preserves exact recent detail; compaction preserves the gist of everything at the cost of exact detail. Long agents often want both — compaction to keep the overall arc small, editing (or memory) to manage the tool-result bulk — plus memory for anything that must survive either operation. Compaction is a deep topic with its own trade-offs, and it’s the subject of the next post in this series; for now, Anthropic’s compaction docs are the reference.

Is it worth it for your agent? An honest test

Context editing is a long-horizon lever, not a default. Run through this before you flip it on:

1. How long are your runs? If a typical task finishes in a handful of turns and never pushes input past ~50–100k tokens, the trigger may never fire — or if it does, the cache re-write won’t amortize. Short agents: skip it. It’s built for the 40-, 80-, 100-turn runs that accumulate real ballast.
2. How tool-heavy are you? The 84% figure came from a tool-saturated web-search agent. If your agent mostly reasons and rarely calls tools, there’s little tool-result bulk to clear and the upside shrinks.
3. Are you caching? If yes, tune clear_at_least so each clear frees clearly more than the cache-write premium costs. If you’re not caching, context editing is closer to pure upside — smaller input every turn after a clear, with no re-write penalty to weigh against.
4. Can the agent re-fetch what you clear? Clearing read-once results is safe. If your agent depends on data it can’t retrieve again, protect it with exclude_tools or move it to memory before it’s cleared.

The honest framing — the one that matters for anyone doing cost math — is that “84% fewer tokens” is a ceiling from an ideal case, not a number you’ll bank by default. What you actually save depends on run length, tool density, and how well your clear_at_least is tuned against your cache economics. And remember that input tokens are only half the bill: on reasoning-heavy agents, output and thinking tokens can dominate, which is a separate lever (reasoning effort) and a reminder that shrinking input is necessary, not sufficient.

Turn it on

The whole thing is two headers and a config block. To start clearing tool results and give Claude a place to stash what matters:

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=conversation,
    tools=[
        {"type": "web_search_20250305", "name": "web_search"},
        {"type": "memory_20250818", "name": "memory"},
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [{
            "type": "clear_tool_uses_20250919",
            "trigger": {"type": "input_tokens", "value": 30000},
            "clear_at_least": {"type": "input_tokens", "value": 5000},
        }]
    },
)

Then watch applied_edits in the responses and your cached-vs-uncached token split in billing. If clears are firing and freeing real volume on long runs, you’ll see it in the invoice. If they’re firing on short runs and churning the cache, dial the trigger up or turn it off for that workload. Measure, don’t assume — the same rule that governs every real cost decision on this site.

This post was verified on 2026-07-11 against Anthropic’s official documentation: context management announcement, context editing docs, memory tool docs, and effective context engineering. Beta headers, parameter defaults, model support, and eval numbers are quoted from those pages; API features and betas change often, so the live docs win. This is the first post in a series on context engineering — next: when to summarize an agent’s history with compaction, and when it backfires. See our methodology for how we verify.