Don't Carry Search Results Twice: Trimming Consumed Blocks with response_inclusion

The minimal setup to enable excluded

The implementation is a single line added to the tool definition. Dynamic filtering presupposes that code execution is enabled, so you pass both. A nice operational detail: when used alongside search or fetch, the code execution calls are billed at no extra charge.

import anthropic
 
client = anthropic.Anthropic()
 
resp = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": (
            "Look up the latest inference prices for the major clouds and "
            "return only a table of the relative cost per 1M tokens. "
            "You don't need to return the raw page content."
        ),
    }],
    tools=[
        {"type": "code_execution_20250825", "name": "code_execution"},
        {
            "type": "web_search_20260318",
            "name": "web_search",
            "max_uses": 8,
            "response_inclusion": "excluded",
        },
    ],
)
 
print(resp.usage)

In this request, the model iterates its searches, narrows the results inside code execution, and returns only the relative-cost table at the end. Because excluded is set, the search originals consumed during filtering drop out of the response, and output_tokens carries only the final table and the reasoning that led to it.

Whether the reduction is working becomes obvious the moment you count what is in the response content. The helper below prints the number of echoed raw result blocks alongside usage.

def summarize(resp) -> None:
    echoed = sum(
        1 for b in resp.content
        if b.type == "web_search_tool_result"
    )
    sts = resp.usage.server_tool_use
    print(f"output_tokens        = {resp.usage.output_tokens}")
    print(f"web_search_requests  = {sts.web_search_requests if sts else 0}")
    print(f"echoed_result_blocks = {echoed}")

Run the same prompt once with full and once with excluded, and you see web_search_requests stay identical while echoed_result_blocks drops to 0, with output_tokens falling in step. The same number of searches, a lighter output — that shape is your proof the setting is taking effect.

When it is safe to drop, and when to keep full

excluded is not a universal switch. Depending on how the response is used, there are cases where you must keep full. Here is the line I draw in production.

The deciding axis is simple: will you use that raw block again after receiving this turn's response? If yes, full; if no, excluded. The research agent in my auto-posting pipeline hands only structured findings to the next stage, so I tip almost all of its searches to excluded. The one agent that shows readers source links is the only one I leave on full.

How it differs from clear_tool_uses and client-side compression

There are other levers for the problem of tool returns bloating context. To avoid stacking two fixes in the same place, it is worth pinning down that they act in different places.

These three do not compete. response_inclusion lightens this turn's output. Context editing's clear_tool_uses removes past tool history that accumulated across turns from the input. Client-side compression of your own tools narrows the return of tools you wrote yourself — not server tools — at the moment they return.

In my own setup I keep them in three layers: response_inclusion for server tools (search and fetch), client-side compression for my custom MCP tools, and context editing for the loop as a whole when it runs long. Try to cover everything with just one of them and something always slips through.

Confirm the output reduction with usage before you ship

Finally, the check I run before putting the setting into production. Numbers, not gut feel.

With the same prompt and the same max_uses, run full and excluded once each and record the difference in output_tokens. The heavier the search load, the larger the gap. In one of my research agents, on tasks with around six web_search_requests, switching to excluded cut output_tokens by roughly 30–40%. On shallow single-shot tasks the gap was small — the deeper the loop and the more searches, the more it pays, which is the intuitive trend.

def compare(make_request) -> None:
    """make_request(inclusion) returns a response"""
    for mode in ("full", "excluded"):
        r = make_request(mode)
        echoed = sum(1 for b in r.content if b.type == "web_search_tool_result")
        print(f"[{mode:8}] out={r.usage.output_tokens:>6}  echoed_blocks={echoed}")

I confirm two things before shipping: that the difference shows up as expected, and that with excluded the substance of the final response (summary, table, verdict) has not degraded. A lighter output is worthless if the conclusion drifts. The one path where I show sources to users stays on full through this comparison by deliberate choice.

Where it settles for solo automation

response_inclusion is the kind of feature whose value only clicks once you stare at the billing and realize search charges you on both input and output. If you stop at trimming the input with dynamic filtering, you miss the originals carried twice on the output side.

Running pipelines for several sites alone as an indie developer, small leaks like this pile up a little each day. I have settled on excluding by default for agents whose purpose is research and filtering and that never pass originals downstream, and keeping full only on the path that shows readers their sources.

Start with your most search-heavy agent: run full and excluded once each and look at the gap in output_tokens. If a gap appears, that is the cost you were quietly paying on every run. Thank you for reading.