D5 · Context & Reliability › Cluster 3 · Managing Long Conversations

3.4 · Context Editing (Clearing Tool Results)

Prune stale tool output

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:

🔑 It's a prune, not a summary. Cleared tool results are replaced with a placeholder — the model no longer sees the payload, but the turn scaffolding stays valid. Contrast 3.3, which summarizes old content into a block.

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.

⚠️ Cache impact: clearing tool results invalidates the prompt cache (the prefix changed). Use 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.
Where it fits vs. its neighbors: truncate (3.2) drops whole turns you own; compact (3.3) summarizes; context editing surgically clears stale tool output while keeping recent turns and the conversation shape — ideal for tool-heavy agents.

DIAGRAM Threshold trips → oldest tool results cleared

flowchart TD A["Agentic loop: tool results
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_edits so 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_least to pay off
  • Beta; strategy ordering matters (thinking-clear first)
Pair context editing with the memory tool (3.5): clear stale tool output from the window, but let Claude write anything worth keeping to a memory file first so it survives the clear.

EXAM TRAPS

Trap: "Context editing summarizes old context." → No — it clears (prunes) old tool results/thinking and replaces them with a placeholder. Summarizing is compaction (3.3).
Trap: "Context editing deletes turns from my message list." → It runs server-side; your client keeps the full history. The model just doesn't see the cleared parts this turn.
Trap: Forgetting the cache cost. → Clearing tool results invalidates the prompt cache. Set clear_at_least so each clear removes enough tokens to justify the re-write.
Trap: Guessing parameter names/values. → It's 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.