The web search tool lets Claude ground answers in live web content, with citations always enabled on the results. Like other Anthropic tools, it is versioned by date, and the three current versions are not interchangeable feature sets — each adds a capability the previous one lacks. Understanding the differences matters twice over: once for functionality, and once for the token bill, because search results are billed as input tokens in the turn they arrive and in every subsequent turn.
The three versions at a glance
| Version | Adds | Practical effect |
|---|---|---|
web_search_20250305 | Baseline server-side search | Results flow straight into context |
web_search_20260209 | Dynamic filtering | Claude filters results in code before they hit context |
web_search_20260318 | response_inclusion control | Control over what search content is included in responses |
All versions share the same commercial shape: $10 per 1,000 searches plus standard token costs for the content the searches pull in. Each search counts as one use regardless of how many results it returns, and errored searches are not billed.
What dynamic filtering actually does
The basic tool's weakness is indiscriminate context growth: every search iteration deposits its results into the conversation, and you pay input tokens for all of it — including the irrelevant hits. Dynamic filtering (from web_search_20260209) changes where search runs: Claude executes the search from inside the code execution environment, inspects the results programmatically, and lets only the useful portion through to the conversation context.
Three operational details from the documentation are worth knowing. First, on versions with dynamic filtering the allowed_callers field defaults to ["code_execution_20260120"] — meaning code execution, not the model directly, is the expected caller. Second, code execution is provisioned automatically when you use the tool this way; you don't add it yourself. Third, there are no extra code-execution charges for search calls made through this path — you still pay per search and per token, not per sandbox.
allowed_callers: who may trigger a search
allowed_callers is an access-control list for the tool itself: it declares which callers — the model directly ("direct") or a named tool such as the code execution environment — are allowed to invoke a search. The default on web_search_20260209+ routes searches through code execution to enable filtering. Models that do not support programmatic tool calling must set allowed_callers: ["direct"] to use the newer tool versions at all — otherwise the default points at a calling path the model can't take.
tools=[{
"type": "web_search_20260209",
"name": "web_search",
"max_uses": 5,
"allowed_domains": ["example.com", "docs.example.com"],
}]Alongside caller control, all versions support max_uses (exceeding it yields a max_uses_exceeded error code), either allowed_domains or blocked_domains (specifying both returns a 400), and user_location for localized results. Organization admins can disable web search or restrict domains centrally in the Claude Console.
One handling rule that bites
Results come back as web_search_tool_result blocks whose items carry url, title, page_age, and an encrypted_content field. In multi-turn conversations you must pass encrypted_content back unchanged — trimming or modifying it returns a 400 error. If your framework rewrites message history, exempt these blocks. Long research turns may also pause with stop_reason: "pause_turn"; resend the paused assistant message unchanged to continue.
Platform availability — check before you build
Per Anthropic's documentation: web search is available on the Claude API, Claude Platform on AWS, and Microsoft Foundry (where it requires a Hosted on Anthropic deployment). On Google Cloud Vertex AI, only the basic web_search_20250305 version is available — no dynamic filtering. Web search is not available on Amazon Bedrock at all; on Bedrock the native grounding path is Knowledge Bases instead (see RetrieveAndGenerate). So the version story is also a platform story: dynamic filtering's token savings are only on the table where the newer versions run.
Where to go next
The web search tool overview covers request anatomy and citations; web fetch URL validation covers the companion tool for pulling full pages once a search finds them.