In a long agent run, every turn re-sends the whole history, including old file contents and search results nobody needs again. Clearing stale tool results cuts input tokens, but it invalidates cached prefixes, so clear in larger, infrequent steps and measure the net effect with your usage data.
Why agents get expensive
Each model call includes the full conversation so far. An agent that reads ten large files on turns one through ten pays for those files again on every later turn. Cost grows faster than the number of turns. Prompt caching softens this by discounting the repeated prefix, but the tokens still occupy context and still count toward limits when written.
What context editing does
The Claude documentation describes a beta feature, context editing, that runs server side just before the prompt reaches the model. Your client keeps the full history. Two strategies are described:
- Tool result clearing. Clears the oldest tool results first and replaces them with placeholder text, so the model knows something was removed. By default only results are cleared. An option also clears the tool call parameters.
- Thinking block clearing. Manages thinking blocks from earlier assistant turns, with a setting for how many recent turns keep theirs.
The docs also say server side compaction is the primary strategy for most cases, and context editing is for finer grained control. Feature status changes, so check the page for the current state and any required beta header.
The settings that matter
For tool result clearing, the docs list a trigger with a default of 100,000 input tokens, a keep value defaulting to three recent tool uses, an optional minimum to clear, a list of tools to exclude, and the option to clear inputs. The responses report what was cleared, and the token counting endpoint can preview savings.
The cache tradeoff
Clearing removes content from the prefix, which invalidates the cache from that point. The docs advise using the minimum to clear setting so each clear removes enough tokens to justify rewriting the cache, after which later requests reuse the new prefix.
So the rule of thumb is:
- Do not clear a little on every turn. That resets the cache constantly.
- Set a high trigger and a meaningful minimum to clear.
- Exclude tools whose results the agent must keep, such as search results it cites.
Measure before and after
Run the same task set with and without clearing. Compare total billed input, cache reads, task success rate, and latency. If success drops, the model may need a result you cleared, so widen the keep window or exclude that tool.
Other levers
Cap loop length per task, return smaller tool outputs at the source, and summarize large results before they enter the context. The cheapest token is one you never put in the prompt.
Quick check
Does context editing change my stored history?
The docs say your client keeps the full, unmodified history. The edit happens server side before the prompt reaches the model.
Can clearing hurt quality?
Yes, if the model needs a cleared result later. Test on real tasks and exclude tools whose output must persist.
Sources
Last reviewed: 19 October 2026.
