CONCEPT A first-class feature that clears old tool results
Context editing is a built-in API capability (beta header
context-management-2025-06-27) that automatically clears older tool results — and
optionally thinking blocks — from the window once a token threshold is hit, keeping the most recent
context intact. In heavy agentic loops, stale tool output (a big file dump, an old search result) piles up and
crowds the window; context editing prunes exactly that noise while leaving the conversation structure in place.
You configure it with context_management.edits, a list of strategies:
clear_tool_uses_20250919— clears old tool results. Defaulttrigger: 100,000 input tokens. Defaultkeep: the 3 most recent tool use/result pairs. Options includeclear_at_least(minimum tokens to clear),exclude_tools(never clear these), andclear_tool_inputs(defaultfalse— also clear the tool-call parameters).clear_thinking_20251015— clears older extended-thinking blocks beyond akeepthreshold.
CONCEPT Server-side clearing — you keep the full history
Clearing happens server-side, before Claude sees the prompt. Crucially, your client
still keeps the full, unedited history — the API doesn't mutate your messages list; it
just doesn't show the model the cleared portions this turn. The response reports what was removed in
context_management.applied_edits (e.g. cleared_tool_uses,
cleared_input_tokens), so you can observe the savings. This differs from client-side truncation
(3.2), where you actually delete turns you own.
clear_at_least so each clear removes enough tokens to be worth the cache
write. Clearing thinking blocks only invalidates the cache when blocks are actually cleared. If you combine both
strategies, clear_thinking_20251015 must be listed first.DIAGRAM Threshold trips → oldest tool results cleared
pile up in context"] --> Q{"input tokens ≥
trigger (default 100k)?"} Q -->|"no"| PASS["Send unchanged"] Q -->|"yes"| CLEAR["Server clears OLDEST tool results
(keep last 3 · exclude_tools honored)"] CLEAR --> KEEP["Recent tool uses + all turns kept;
cleared payloads → placeholder"] KEEP --> RPT["Response: applied_edits
cleared_input_tokens"] CLEAR -.->|"your client keeps
the FULL history"| LOCAL["messages[] unchanged locally"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef info fill:#d4edda,stroke:#28a745,color:#155724; class PASS,KEEP,RPT,LOCAL ok; class Q,CLEAR gate;
CODE Enable tool-result clearing on the beta endpoint
Turn on context editing with the beta header and a clear_tool_uses strategy; the server prunes
old tool output past the trigger and reports what it cleared.
# Beta: server clears old tool results past a token threshold. resp = client.beta.messages.create( model="claude-opus-4-8", max_tokens=4096, betas=["context-management-2025-06-27"], context_management={ "edits": [{ "type": "clear_tool_uses_20250919", "trigger": {"type": "input_tokens", "value": 100_000}, # default "keep": {"type": "tool_uses", "value": 3}, # keep 3 recent pairs "clear_at_least": {"type": "input_tokens", "value": 5_000}, # worth the cache write "exclude_tools": ["web_search"], # never clear these # "clear_tool_inputs": True, # also drop tool-call params }], }, tools=tools, messages=messages, # ← still your FULL history; server clears server-side ) # Observe what was actually removed this turn. for edit in resp.context_management.applied_edits: print(edit.type, edit.cleared_input_tokens)
TRADE-OFFS Context editing vs. compaction
✅ Context editing (clear)
- Surgical: removes stale tool payloads, keeps conversation shape
- Server-side + configurable; you keep full history locally
- Reports
applied_editsso savings are observable
⚠️ Where it falls short
- Cleared payloads are gone from context — no gist retained (unlike compaction)
- Clearing invalidates the cache; needs
clear_at_leastto pay off - Beta; strategy ordering matters (thinking-clear first)
EXAM TRAPS
clear_at_least so each clear removes enough tokens to justify the re-write.context_management.edits with
clear_tool_uses_20250919 (default trigger 100k tokens, keep 3) and
clear_thinking_20251015, behind beta context-management-2025-06-27.PRACTICE
Q1 · What does context editing do, and how is it different from compaction?
It automatically clears older tool results (and optionally thinking blocks) once a token trigger is hit, keeping recent context — a prune, replaced by a placeholder. Compaction instead summarizes old content into a block. Editing removes; compaction compresses.
Q2 · Where does the clearing happen, and what does your client still hold?
Clearing is server-side, before Claude sees the prompt. Your client keeps the
full, unedited history — the API doesn't mutate your messages. The response's
applied_edits reports what was cleared this turn.
Q3 · Why set clear_at_least, and what does keep control?
clear_at_least ensures each clear removes enough tokens to be worth the prompt-cache
invalidation the clear causes. keep sets how many recent tool use/result pairs to preserve (default
3) so the agent's immediate working context stays intact.