A long-running agent doesn't usually fail because the model got weak. It fails because the window fills with stale tool output until the signal is buried — the failure mode behind context rot. Context editing is Anthropic's server-side lever for that: it clears the oldest tool results before the prompt reaches the model, keeping the window lean without you rewriting your message history. We've covered where it sits next to compaction and the memory tool; this is the level down — the four knobs that actually decide its behavior, and the one that quietly decides your bill.

Turning it on#

Context editing rides behind a beta header and a request parameter:

response = client.beta.messages.create(
    model="claude-sonnet-4-5",  # any Claude 4+ model
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [{"type": "clear_tool_uses_20250919"}]
    },
    max_tokens=4096,
    messages=messages,
    tools=tools,
)

That's the whole activation. With no options, the clear_tool_uses_20250919 strategy runs on defaults: it waits until your input crosses ~100,000 tokens, then clears the oldest tool results while keeping the 3 most-recent tool use/result pairs. Each cleared result is swapped for a short placeholder, and — critically — the tool call stays in the transcript, so the model knows a result existed and was removed, and can simply call the tool again if it needs the data back. Nothing is truly lost, because tool results are re-fetchable. That's what makes this the lightest-touch way to make room.

The defaults are safe, but they are conservative. Here's what each knob does.

Knob 1 — trigger: how full before you clear#

trigger is the input-token threshold that fires a clearing event. Default is around 100,000. Raise it and you clear less often (fewer cache invalidations, but a heavier window between clears); lower it and you keep the working window tighter at the cost of clearing more frequently. If your agent runs hot near the limit, a lower trigger buys headroom; if you're cache-sensitive, a higher one clears in rarer, bigger sweeps.

Knob 2 — keep: what you refuse to touch#

keep is how many of the most-recent tool use/result pairs are always preserved, default 3. This is your "recent work is sacred" setting. If the last few tool outputs are load-bearing — the file you're mid-edit on, the search result you're reasoning over — a higher keep protects them. The trade is that a higher keep frees less on each clear.

Knob 3 — clear_at_least: the knob that pays for itself#

This is the one most people miss, and it's the one that matters for cost. Clearing changes the cached prompt prefix, which invalidates your prompt cache and forces a re-write on the next call. So a clearing event that frees only a few thousand tokens can cost more in cache misses than it saves.

clear_at_least sets the minimum tokens a single clear must free, or it won't fire at all:

context_management={
    "edits": [{
        "type": "clear_tool_uses_20250919",
        "trigger": {"type": "input_tokens", "value": 120000},
        "keep": {"type": "tool_uses", "value": 5},
        "clear_at_least": {"type": "input_tokens", "value": 20000},
        "exclude_tools": ["read_plan", "get_current_file"],
    }]
}

Read that as: don't even think about clearing until I'm at 120k input tokens; always keep my 5 most-recent tool exchanges; and when you do clear, free at least 20k tokens so the cache re-write is worth it — otherwise skip this round. That single line turns context editing from "fires constantly and churns the cache" into "fires rarely and each fire earns its keep."

Knob 4 — exclude_tools (and clear_tool_inputs)#

exclude_tools pins specific tools' results so they're never cleared regardless of age — name your planning tool, your spec reader, the tool that returns the current file. Their output stays put; everything else is fair game once trigger and keep are satisfied.

clear_tool_inputs (default false) decides whether the tool call arguments get cleared too, not just the results. Leave it off unless your tool calls carry bulky, re-derivable payloads that are themselves eating the window.

Verify, don't assume#

After each call, read context_management.applied_edits on the response. It reports what actually happened — cleared_tool_uses, cleared_input_tokens — so you can see whether your clears are freeing enough to justify the cache churn, or whether trigger and clear_at_least need adjusting. Tuning blind is how you end up with a config that clears too often and wonders why the cache-hit rate cratered.

When context editing is the wrong tool#

Context editing only manages the live window. It cannot make a fact survive a full context reset, because the moment a result is cleared it's gone from the window (re-fetchable, but gone). If something must persist across sessions — a decision, a user preference, a spec the agent will need long after this run — don't lean on keep to hold it forever. Write it out with the memory tool, which lives outside the window, and let context editing do the one job it's good at: keeping the window lean and cheap while the agent works.