Context editing on the Claude API: auto-clear old tool results so long agents stay cheap

Long-running agents on the Claude API develop a typical kind of "bloat": every file read, web search and database query gets appended to the history and travels with every later request. After 30 turns most of the context is old tool output the agent no longer needs, costing money and diluting the model's focus. Context editing is a beta feature that lets the server automatically clear that content before the prompt reaches Claude, while your client keeps the full history. This post explains the two strategies, the parameters and how to combine it with prompt caching.

Two strategies

Enable it with the beta header context-management-2025-06-27.

Parameters for clearing tool results

• trigger: when clearing starts; default 100,000 input tokens (can also count tool uses).
• keep: how many recent tool use/result pairs to keep; default 3.
• clear_at_least: each clear must remove at least this many tokens, otherwise nothing is cleared (so the cache loss is worth it).
• exclude_tools: tools whose results are never cleared (for example web search you need to cite).
• clear_tool_inputs: also clear the tool call parameters; default false.

Configuration example

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_thinking_20251015",
             "keep": {"type": "thinking_turns", "value": 2}},
            {"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"]},
        ]
    },
)

When combining both strategies, clear_thinking must come first. The response includes context_management.applied_edits showing how many tool uses and tokens were cleared; the token counting endpoint also accepts this config so you can estimate ahead of time.

Working with prompt caching

• Clearing tool results invalidates the cache from the edited point. So set clear_at_least high enough: clearing a little and losing the cache is a net loss.
• Thinking clearing: keeping preserves the cache, clearing invalidates it at that point.
• Choose a moderate trigger: frequent small clears are the worst pattern cost-wise.

Combining with the memory tool

Add the memory tool (memory_20250818) to your tools alongside the context editing config: as context approaches the clearing threshold, Claude gets a warning to save important information to memory files before the related tool results are cleared. The agent "forgets" details in context but keeps what matters outside.

Context editing or compaction?

The docs recommend server-side compaction (summarising history) for most long conversations. Context editing fits when you need fine control over what is cleared, for example an agent that reads many large files but only needs the last few results. The client-side compaction_control option in the SDKs is marked deprecated.

Risks and caveats

• The feature is in beta; type names carry date suffixes and may change.
• The agent may need a cleared result again and call the tool a second time; watch for repeated calls.
• Default thinking retention differs by model generation; set keep explicitly if your code runs on several models.

How to apply it

• Dev: For agents that read files/search a lot, enable tool result clearing with keep 3–5 and clear_at_least of a few thousand tokens; log applied_edits.
• Tech Lead: Compare cost and quality of three options on the same eval set before choosing: doing nothing, context editing, compaction.
• PM: Context editing is a cost lever for long-running agents that doesn't require changing models; add it to your cost optimisation list.