web-search-tool changedagents-and-tools/tool-use/web-search-tool
Nearest release: v2.1.319, published an hour after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+23added
Lines−21removed
From line
88
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits22to this page, all time
The whole hunk
from line 88, old and new numbered
/
from line 88
8888* Analysis of content already provided in the conversation
8989* Conversational turns and greetings
9090
91Triggering is steerable through your system prompt: you can encourage Claude to search more readily or to prefer answering directly. For a hard constraint, use `max_uses` to cap the number of searches for each request.
91Triggering is steerable through your system prompt: you can encourage Claude to search more readily or to prefer answering directly. To enforce a limit, use [`max_uses`](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool#max-uses) to cap the number of searches in a turn.
9292
9393### Dynamic filtering
9494
from line 237
237237 messages: [
238238 ['role' => 'user', 'content' => 'Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.'],
239239 ],
240 model: 'claude-opus-5-5',
240 model: Model::CLAUDE_OPUS_5_5,
241241 tools: [
242242 [
243243 'type' => 'web_search_20260318',
from line 285
285285 -H "content-type: application/json" \
286286 -d '{
287287 "model": "claude-opus-5-5",
288 "max_tokens": 1024,
288 "max_tokens": 4096,
289289 "messages": [
290290 {
291291 "role": "user",
from line 303
303303 ```bash CLI
304304 ant messages create \
305305 --model claude-opus-5-5 \
306 --max-tokens 1024 \
306 --max-tokens 4096 \
307307 --message '{role: user, content: What is the weather in NYC?}' \
308308 --tool '{type: web_search_20250305, name: web_search, max_uses: 5}'
309309 ```
from line 313
313313
314314 response = client.messages.create(
315315 model="claude-opus-5-5",
316 max_tokens=1024,
316 max_tokens=4096,
317317 messages=[{"role": "user", "content": "What's the weather in NYC?"}],
318318 tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}],
319319 )
from line 325
325325
326326 const response = await client.messages.create({
327327 model: "claude-opus-5-5",
328 max_tokens: 1024,
328 max_tokens: 4096,
329329 messages: [
330330 {
331331 role: "user",
from line 350
350350 var parameters = new MessageCreateParams
351351 {
352352 Model = Model.ClaudeOpus5_5,
353 MaxTokens = 1024,
353 MaxTokens = 4096,
354354 Messages = [new UserMessageParam { Content = "What's the weather in NYC?" }],
355355 Tools = [new ToolUnion(new WebSearchTool20250305() { MaxUses = 5 })]
356356 };
from line 364
364364
365365 response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
366366 Model: anthropic.ModelClaudeOpus5_5,
367 MaxTokens: 1024,
367 MaxTokens: 4096,
368368 Messages: []anthropic.MessageParam{
369369 anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather in NYC?")),
370370 },
from line 388
388388
389389 MessageCreateParams params = MessageCreateParams.builder()
390390 .model(Model.CLAUDE_OPUS_5_5)
391 .maxTokens(1024L)
391 .maxTokens(4096L)
392392 .addUserMessage("What's the weather in NYC?")
393393 .addTool(WebSearchTool20250305.builder()
394394 .maxUses(5L)
from line 404
404404 $client = new Client();
405405
406406 $message = $client->messages->create(
407 maxTokens: 1024,
407 maxTokens: 4096,
408408 messages: [
409409 ['role' => 'user', 'content' => "What's the weather in NYC?"],
410410 ],
411 model: 'claude-opus-5-5',
411 model: Model::CLAUDE_OPUS_5_5,
412412 tools: [
413413 [
414414 'type' => 'web_search_20250305',
from line 426
426426
427427 message = client.messages.create(
428428 model: Anthropic::Model::CLAUDE_OPUS_5_5,
429 max_tokens: 1024,
429 max_tokens: 4096,
430430 messages: [
431431 { role: "user", content: "What's the weather in NYC?" }
432432 ],
from line 449
449449 "type": "web_search_20250305",
450450 "name": "web_search",
451451
452 // Optional: Limit the number of searches for each request
452 // Optional: Limit the number of searches
453453 "max_uses": 5,
454454
455455 // Optional: Only include results from these domains.
from line 474
474474
475475### Max uses
476476
477The `max_uses` parameter limits the number of searches performed. If Claude attempts more searches than allowed, the `web_search_tool_result` is an error with the `max_uses_exceeded` error code.
477The `max_uses` parameter limits the number of searches in a single turn. Single-fact queries typically use 1–3 searches; comparative or multientity research can use 10 or more.
478478
479Simple factual queries typically use 1–3 searches; comparative or multientity research can use 10 or more. For guidance on choosing a value, see [Server tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools).
479Failed searches count against the limit. If Claude calls web search directly more times than allowed, the `web_search_tool_result` is an error with the `max_uses_exceeded` error code. If Claude calls web search from code execution more times than allowed, the code execution run ends with an error.
480480
481A turn can span several requests. A request continues a turn when it resumes after [`pause_turn`](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn) or when its last message contains only `tool_result` blocks. Searches from earlier requests in that turn count against the limit, unless Claude ran them from code execution through [dynamic filtering](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool#dynamic-filtering).
482
481483### Domain filtering
482484
483485Provide `allowed_domains` or `blocked_domains`, not both. If a request includes both, the API returns a 400 error. Entries are bare domains with an optional path, for example `example.com` or `example.com/blog`, without a scheme.
from line 506
504506 Requires `web_search_20260318` or later.
505507</Note>
506508
507The `response_inclusion` parameter controls how search result blocks appear in the API response when the result was consumed by a completed [code execution](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool) call in the same turn. Set `"response_inclusion": "excluded"` to drop those nested `server_tool_use` and result block pairs entirely from the response, reducing output token costs for agentic workflows that don’t need to echo raw search content back to the client. The default is `"full"`. Results from direct calls, or from code execution calls that paused before completing, are always returned in full so they can be sent back on the next turn.
509The `response_inclusion` parameter controls how search result blocks appear in the API response when a completed [code execution](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool) call in the same response consumed the result. Set `"response_inclusion": "excluded"` to drop those nested `server_tool_use` and result block pairs entirely from the response, for agentic workflows that don’t need the raw search content. Token usage is unaffected, because Claude reads the code’s output rather than these blocks. The default is `"full"`. The API always returns results from direct calls, or from code execution calls that paused before completing, in full so that you can send them back in the next request.
508510
509511```json JSON
510512{
from line 598
596598* `page_age`: When the site was last updated
597599* `encrypted_content`: Encrypted content that you must pass back in multi-turn conversations
598600
599To continue a conversation that contains search results, send the assistant’s content blocks back exactly as you received them, including each result’s `encrypted_content`. The API decrypts that content on later turns to restore the search results in Claude’s context. If `encrypted_content` is missing or modified, the request fails with a 400 validation error.
601To continue a conversation that contains search results, send the assistant’s content blocks back exactly as you received them, including each result’s `encrypted_content`. The API decrypts that content in later requests to restore the search results in Claude’s context. If `encrypted_content` is missing or modified, the request fails with a 400 validation error.
600602
601603### Citations
602604
from line 655
653655
654656## Streaming
655657
656With streaming enabled, you’ll receive search events as part of the stream. There is a pause while the search runs:
658With streaming enabled, you receive search events as part of the stream. There is a pause while the search runs:
657659
658660```sse Output
659661event: message_start
from line 684
682684
683685## Batch requests
684686
685You can include the web search tool in the [Messages Batches API](https://platform.claude.com/docs/en/build-with-claude/batch-processing). Web search tool calls through the Messages Batches API are priced the same as those in regular Messages API requests.
687You can include the web search tool in the [Message Batches API](https://platform.claude.com/docs/en/build-with-claude/batch-processing). Web search tool calls through the Message Batches API are priced the same as those in regular Messages API requests.
686688
687689To protect shared capacity, the Batches API throttles web search requests for each organization, so large batches with many searches might take longer to complete. You can see your organization’s web search rate limit on the [Rate limits](https://platform.claude.com/usage/limits) page in the Claude Console. To request a higher limit, contact sales from that page.
688690
from line 708
706708
707709Web search is available on the Claude API for **$10 USD per 1,000 searches**, plus standard token costs for search-generated content. Web search results retrieved throughout a conversation are counted as input tokens, in search iterations run during a single turn and in subsequent conversation turns.
708710
709Each web search counts as one use, regardless of the number of results returned. If an error occurs during web search, the web search will not be billed.
711Each web search counts as one use, regardless of the number of results returned. A web search that fails with an error is not billed.
710712
711713## Next steps
712714
No line in this hunk matches that.