Agent and AI engineering · Practical technical guide · 23 October 2026
When a long agent run fills the context window, you can clear old tool results by rule or compact the whole history into a summary. This compares the two, reads the Anthropic context-editing fields exactly, and shows why clearing breaks the prompt cache and how to size it so it is worth it.
The window fills with tool results, not reasoning
In an agent loop that uses tools heavily, the context does not fill with the model reasoning. It fills with tool results: file contents, search hits, API responses, each one kept verbatim in the history so later turns can refer to it. After thirty tool calls, most of the window is output from calls whose result the model has already used and will not read again. You have two documented ways to reclaim that space, and they behave differently enough that choosing wrong wastes money or loses information.
The first is context editing, which clears specific old content by rule while leaving the rest of the history exactly as it was. The second is compaction, which replaces older turns with a summary the model writes. Anthropic documents context editing with two server-side strategies, enabled with the beta header context-management-2025-06-27: clear_tool_uses_20250919 for tool results and clear_thinking_20251015 for thinking blocks. This article is about the first.
Clearing by rule versus summarizing
The distinction is what happens to the cleared content. Clearing removes it and leaves a placeholder saying it was removed; compaction reads it and folds its meaning into a summary. Clearing keeps the exact wording of what remains; compaction rewrites the past into prose.
| Property | Tool-result clearing | Compaction |
|---|---|---|
| What leaves the context | The oldest tool results, verbatim | The older turns, replaced by a summary |
| What is kept exactly | Everything not cleared | Only the recent turns you choose to keep |
| Information lost | The cleared results, replaced by a placeholder | Detail the summary drops |
| Who writes anything | No model call to clear | The model writes the summary |
| Best when | Old tool output is dead weight | The thread itself is long and needs condensing |
Clearing is the right tool when old results are simply no longer needed: once the model has read a file and acted, the file contents are dead weight. Compaction is the right tool when the conversation itself, not just its tool output, has grown past what the model should re-read every turn.
Reading the fields exactly
The strategy has four parameters worth knowing, with the defaults Anthropic documents: trigger (default 100,000 input tokens) decides when clearing activates; keep (default 3 tool uses) is how many recent tool use and result pairs survive; clear_at_least ensures a minimum is cleared each time; and exclude_tools names tools whose results are never cleared. By default only tool results are cleared and the model calls themselves stay visible, unless you set clear_tool_inputs.
Illustrative python, checked for syntax; adapt names and storage to your system.
response = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=messages,
tools=tools,
betas=["context-management-2025-06-27"],
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 reports what was cleared:
for edit in response.context_management.applied_edits:
print(edit.type, edit.cleared_tool_uses, edit.cleared_input_tokens)The important discipline is to read applied_edits rather than assume clearing happened. The response field reports cleared_tool_uses and cleared_input_tokens, and for a streaming response the same data arrives in the final message_delta event. If those numbers are zero, nothing was cleared, and you are paying for the full history.
Why clearing breaks the cache, and the arithmetic that fixes it
Prompt caching keys on an exact, unbroken prefix. Clearing a tool result from the middle of the history changes that prefix, so the cache entry that covered it is invalidated, and the next request pays to write a new cache entry for the new prefix. Anthropic states this directly: tool-result clearing invalidates cached prompt prefixes when content is cleared. That is why clear_at_least exists. If you clear a trickle of tokens each turn, you pay the cache-write penalty every turn and save almost nothing; if you wait and clear a large block at once, you pay the penalty once and then reuse the new prefix across many turns.
The rule is: set trigger high enough and clear_at_least large enough that the tokens you free clearly exceed the tokens you will re-cache. Small clearing can cost more in cache rewrites than it saves; larger clearing reused across later turns may pay off. These are workload-dependent estimates: compare billed reads, writes and subsequent turns rather than treating a token threshold as universal. Use the token-counting endpoint, which supports context management, to preview the post-clear size before you commit to a threshold.
A worked example
An agent runs fifty tool calls in one task. Each result averages 1,500 input tokens, so by call forty the prompt carries roughly 60,000 tokens of tool output alone. Three policies, with illustrative figures that follow from the documented behaviour, not from a benchmark:
| Policy | Cache writes caused by clearing | Tokens carried at call 50 | Note |
|---|---|---|---|
| No clearing | 0 | ~75,000 | Full history every turn; highest input cost |
| Clear every turn past 30k, no minimum | ~20 | ~30,000 | Small window kept, but a cache write almost every turn |
| Trigger 60k, clear_at_least 40k, keep 3 | ~1 | ~35,000 | One cache write, then reuse; usually cheapest |
The middle row is the trap: it keeps the window small but pays the re-cache penalty constantly. The last row frees almost as much space for a single cache write. Which of the last two wins depends on your cache hit rate and the price of a cache write versus an uncached input token, so measure both on your own traffic rather than trusting the table.
Failure modes
- Clearing a tool whose result a later turn still needs; put it in
exclude_toolsor raisekeep. - A trickle policy with no
clear_at_least, which pays the cache-write penalty every turn. - Assuming clearing happened; always read
applied_editsand alert when it clears nothing under load. - Rewriting your own local history to match the edited one, which is unnecessary because editing is server-side and your client keeps the full history.
- Reaching for clearing when the thread itself is long; that is compaction work, and the two can be combined with thinking-clearing listed first.
Verification
In a staging run with a scripted sequence of tool calls, assert that applied_edits reports a non-zero cleared_input_tokens once the trigger is crossed, and that a tool named in exclude_tools is never among the cleared ones. Compare the total input tokens billed across the run with and without clearing, and separately track cache-write tokens, so you can see the re-cache cost rather than only the saving. Preview the post-clear token count with the token-counting endpoint and check it against what the response reports. Keep the cleared-tokens-per-cache-write ratio on a dashboard; when it falls, your threshold is too low.
Sources and scope
Checked against these sources on 23 October 2026. Examples and figures are illustrative, not measurements.
Clear old tool results by rule when they are dead weight, keep enough recent ones and exclude the tools a later turn needs, set clear_at_least large enough that the freed tokens beat the re-cache cost, read applied_edits rather than assume, and use compaction instead when the thread itself is long.