The pitch, and the sentence in the docs that complicates it Context editing is the feature Anthropic shipped to stop long-running Claude agents from drowning in their own tool history: once a conversation crosses a token threshold, clear_tool_uses_20250919 automatically strips the oldest tool calls and results, replaces them with a placeholder, and lets the agent keep going instead of hitting the context window wall. Anthropic reports a 29% performance improvement from context editing alone, 39% combined with the memory tool, and an 84% token reduction in a 100-turn web search evaluation. Source: Anthropic, "Managing the context window" It's easy to read that as the fix for a problem this blog has already covered: auto-compaction rewrites the conversation prefix a provider would otherwise serve from cache at a 50-90% discount, so the next turn re-pays full price for tokens that were already paid for once. Structural clearing instead of lossy summarization sounds like it should sidestep that tax entirely. It doesn't. Anthropic's own API documentation says so directly: "You'll incur cache write costs each time content is cleared." Source: Anthropic, "Context editing" Context editing doesn't dodge the cache-invalidation bill compaction runs up. It just gives you a dial to decide when paying it is worth it, and a raw compaction implementation gives you no dial at all. Two lanes of the same six-turn agent session: without context editing, every cache read gets a little pricier as the prefix grows unbounded. With clear_tool_uses_20250919 triggered at 100K tokens, one cache write resets the prefix and subsequent reads shrink back down. What the edit actually does clear_tool_uses_20250919 runs server-side, before Claude sees the prompt: it walks the conversation in chronological order, clears the oldest tool_use/tool_result pairs once a trigger threshold is crossed, and swaps each cleared result for a short placeholder so Claude knows something was removed. By default it clears results only and leaves the original tool call parameters intact, so the model can still see what it asked for, just not what came back. Your own client-side conversation history is untouched; the edit is a view the API constructs per request, not a mutation you have to track. | Parameter | Type | Default | What it controls | |---|---|---|---| | trigger | {type, value} | 100,000 input tokens | When clearing activates: input_tokens or tool_uses count | | keep | {type, value} | 3 tool uses | How many of the most recent tool use/result pairs survive a clear | | clear_at_least | {type, value} | none | Minimum tokens a clear must free to fire at all | | exclude_tools | array | none | Tool names that are never cleared, e.g. a running plan file | | clear_tool_inputs | boolean | false | If true, also clears the original tool call parameters, not just results | Source: Anthropic, "Context editing" The order of operations that makes the bill non-obvious Here's the mechanic that the "cache-friendly" framing glosses over. The trigger check happens against the full, pre-edit prefix, so the turn that crosses 100K tokens still gets whatever cache credit that prefix had already earned. Then the edit runs, the oldest tool pairs come out, and what's left, a shorter prefix Claude has never seen in that exact shape before, has to be written into the cache fresh. That write costs the standard cache-write premium, 1.25x the base input rate on a 5-minute TTL, the same premium this blog has already mapped across Anthropic, OpenAI, and DeepSeek, before any future turn gets to read the shrunk prefix at the cheap rate. Anthropic's guidance is explicit about why clear_at_least exists: "clear enough tokens to make the cache invalidation worthwhile." A response from a call that triggered an edit reports exactly what got cleared: { "context_management": { "applied_edits": [ { "type": "clear_tool_uses_20250919", "cleared_tool_uses": 8, "cleared_input_tokens": 50000 } ] } } Clear 50,000 tokens and the write premium is trivial against the reads it saves over the next dozen turns. Set no clear_at_least floor, and a trigger that fires early can clear a few thousand tokens, pay a full write premium for the privilege, and still leave the underlying growth problem basically untouched. The parameter exists because Anthropic knows the naive version of this feature can lose money. The code, basic and tuned Minimal version, no tuning, defaults everywhere: import anthropic client = anthropic.Anthropic() response = client.beta.messages.create( model="claude-sonnet-5", max_tokens=4096, messages=conversation_history, tools=tool_definitions, betas=["context-management-2025-06-27"], context_management={ "edits": [{"type": "clear_tool_uses_20250919"}] }, ) Tuned for an agent where a running plan or spec file must never be cleared, and where a clear should only fire when it actually pays for the write it triggers: response = client.beta.messages.create( model="claude-sonnet-5", max_tokens=4096, messages=conversation_history, tools=tool_definitions, betas=["context-management-2025-06-27"], context_management={ "edits": [ { "type": "clear_tool_uses_20250919", "trigger": {"type": "input_tokens", "value": 60000}, "keep": {"type": "tool_uses", "value": 5}, "clear_at_least": {"type": "input_tokens", "value": 15000}, "exclude_tools": ["read_plan_file"], "clear_tool_inputs": False, } ] }, ) applied = response.context_management["applied_edits"] if applied: print(applied[0]["cleared_input_tokens"], "tokens cleared this turn") Lowering trigger fires the clear earlier, before the growing prefix gets expensive to read on every turn. Raising clear_at_least refuses to fire until a clear is big enough to be worth its own write premium. Both numbers are workload-specific; there's no default that's right for a two-tool agent and a thirty-tool one at the same time. Doing the math on whether a clear paid for itself Take the illustrative session in the diagram above: six turns, no editing, on Sonnet 5 pricing (base input $3/M, cache read roughly 0.1x at $0.30/M, cache write roughly 1.25x at $3.75/M). Left uncapped, per-turn cache reads climb with the prefix, 60K, 82K, 104K, 126K, 148K, 170K tokens, because nothing ever shrinks. Summed at the read rate, that's roughly $0.21 across six turns and still climbing on every turn after. With clear_tool_uses_20250919 triggered at 100K and clear_at_least set high enough to force a real clear, turn four pays a one-time write on the new ~56K-token prefix, about $0.21 for that turn alone, then turns five and six read the shrunk prefix at 56K and 68K tokens instead of 148K and 170K. The write premium isn't free, it shows up as a real spike on that one turn's bill, but it buys back every read after it. The break-even isn't "does clearing cost money," it always does, it's "does the session have enough turns left after the clear for the cheaper reads to outrun the one expensive write." A two-turn session that clears on its second-to-last call never gets there. A fifty-turn agent loop clears once and coasts. Where this sits next to the other tools for the same problem Auto-compaction summarizes the whole history with a model call, which is lossy, unpredictable in size, and busts the cache with no equivalent of clear_at_least to size the damage. clear_tool_uses_20250919 is deterministic instead: it removes exactly the oldest tool pairs past keep, nothing is paraphrased, and the size of every clear is inspectable in the response. A July 2026 research system called Self-GC goes a step further, deciding per-object whether to fold, mask, or prune based on future dependency rather than raw age, and reports holding 84.85% of future continuations unaffected in testing, but it's a paper's reference implementation, not a shipped API parameter you set today. Context editing is the version of "smart clearing" that's one betas header away from production, at the cost of a coarser, age-based clearing rule instead of a learned one. It also pairs with, rather than replaces, the memory tool: letting Claude write durable state to files outside the context window means a cleared tool result doesn't have to mean lost information, just information the model re-reads on demand instead of carrying on every turn. That combination is where Anthropic's 39% number comes from, and it's a second post's worth of implementation on its own. A checklist for turning this on Check whether you're already paying the uncontrolled version. If your harness auto-compacts via summarization once the window fills, you're already paying a cache-invalidation tax with no clear_at_least floor to size it. Structural clearing is very likely cheaper even before tuning. Set trigger below your context window ceiling, not at it. Clearing at the wall means the model already paid full, uncached price to read the bloated prefix once before the edit ever ran. Set clear_at_least deliberately, don't leave it unset. An untuned clear can fire on a few thousand tokens, pay the full write premium, and net negative. Size it to your session length: short sessions need a higher floor to make each clear worth it; long-running agents can afford to clear more often. Exclude anything load-bearing. A running plan file, a spec, a set of constraints the user stated once and expects remembered: put those tool names in exclude_tools before the first clear ever fires, not after an agent silently forgets one. Read applied_edits back, don't assume. The response tells you exactly how many tokens and tool uses were cleared on every call where an edit fired. That number is the actual input to the break-even math above, not the theoretical one. The clearing isn't free, and it was never going to be: removing tokens from a prefix a provider already cached means the next version of that prefix is new to the cache, and new prefixes get written, not read. What context editing buys over blind compaction is a deterministic, inspectable, tunable version of that same trade, with the knobs to make sure the write you're forced to pay actually buys back more than it cost. Start free and route the requests around whichever context strategy your agent uses, or read the complete guide to cutting LLM API costs for the rest of the stack. FAQ Q: What is Claude's context editing API and clear_tool_uses_20250919? A: It's a beta feature on the Claude Developer Platform that automatically clears the oldest tool_use/tool_result pairs from a conversation once a token or tool-use threshold is crossed, replacing them with a placeholder so the model knows something was removed. It runs server-side; your own client-side conversation history is untouched. Enable it with the context-management-2025-06-27 beta header. Q: Does context editing avoid the prompt-cache invalidation problem that compaction has? A: No. Anthropic's own documentation states that clearing tool results invalidates the cached prefix and that "you'll incur cache write costs each time content is cleared." What context editing adds over blind summarization compaction is the clear_at_least parameter, which lets you set a minimum token floor so a clear only fires when it's big enough to be worth the write premium it triggers. Q: How is context editing different from auto-compaction in coding agents like Claude Code or Cursor? A: Auto-compaction summarizes the entire conversation history with a model call, which is lossy and produces an unpredictable amount of change to the prefix. clear_tool_uses_20250919 deterministically removes the oldest tool call/result pairs past a configured keep count, with no summarization step, and reports exactly how many tokens and tool uses it cleared on every call. Q: What do the trigger, keep, and clear_at_least parameters control? A: trigger sets the token or tool-use count that activates clearing (100,000 input tokens by default). keep sets how many of the most recent tool use/result pairs are always preserved (3 by default). clear_at_least sets a minimum number of tokens a clear must free before it's allowed to fire at all, which exists specifically to stop a clear from paying a cache-write premium for a trivial amount of freed context. Q: Is context editing available on every Claude model? A: Yes, Anthropic documents it as available on all supported Claude models, including Opus, Sonnet, Haiku, Fable, and Mythos, accessed through the same beta header regardless of which model is handling the request.