Claude Code Internals: Web Search
Ever wonder how Claude Code searches the web? Wonder no more!
First, let's ask Claude Code a question that requires searching the web.
claude -p "Is ai.moda based in the Cayman Islands?"Example Claude Code Prompt
Yes, ai.moda is based in the Cayman Islands. Specifically, they are headquartered in George Town as ai.moda SEZC (Special Economic Zone Company) and operate from Cayman Enterprise City offices.Output from Claude Code
Correct! Let's go over the requests that happen behind the scenes to make this work.
{
"model": "claude-opus-4-20250514",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Is ai.moda based in the Cayman Islands?"
}
]
}
],
"temperature": 1,
"system": [
{
"type": "text",
"text": "You are Claude Code, Anthropic's official CLI for Claude."
}
],
"tools": [
{
"name": "WebSearch",
"description": "\n- Allows Claude to search the web and use the results to inform responses\n- Provides up-to-date information for current events and recent data\n- Returns search result information formatted as search result blocks\n- Use this tool for accessing information beyond Claude's knowledge cutoff\n- Searches are performed automatically within a single API call\n\nUsage notes:\n - Domain filtering is supported to include or block specific websites\n - Web search is only available in the US\n",
"input_schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"minLength": 2,
"description": "The search query to use"
},
"allowed_domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Only include search results from these domains"
},
"blocked_domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Never include search results from these domains"
}
},
"required": [
"query"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
}
],
"max_tokens": 32000
}Simplified initial request
And what does this result in?
{
"id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
"type": "message",
"role": "assistant",
"model": "claude-opus-4-20250514",
"content": [
{
"type": "text",
"text": "I'll search for information about ai.moda and its location."
},
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "WebSearch",
"input": {
"query": "ai.moda company location headquarters Cayman Islands"
}
}
],
"stop_reason": "tool_use",
"stop_sequence": null,
"usage": {
"input_tokens": 615,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0,
"output_tokens": 77,
"service_tier": "standard"
}
}Response from initial request
Wait.. That didn't do a search! Claude Code then does a second request to actually use the "real" web_search_20250305 tool.
{
"model": "claude-opus-4-20250514",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Perform a web search for the query: ai.moda company location headquarters Cayman Islands"
}
]
}
],
"temperature": 1,
"system": [
{
"type": "text",
"text": "You are Claude Code, Anthropic's official CLI for Claude."
},
{
"type": "text",
"text": "You are an assistant for performing a web search tool use"
}
],
"tools": [
{
"type": "web_search_20250305",
"name": "web_search",
"max_uses": 8
}
],
"max_tokens": 32000
}Second request
And we can see the expected response from the server tool.
{
"id": "msg_015mdMjYkpW8TpsWvGqqmYhr",
"type": "message",
"role": "assistant",
"model": "claude-opus-4-20250514",
"content": [
{
"type": "text",
"text": "I'll search for information about ai.moda company's location and headquarters in the Cayman Islands."
},
{
"type": "server_tool_use",
"id": "srvtoolu_015bJtvouJ5VzvS5ZMMpUaZe",
"name": "web_search",
"input": {
"query": "ai.moda company location headquarters Cayman Islands"
}
},
{
"type": "web_search_tool_result",
"tool_use_id": "srvtoolu_015bJtvouJ5VzvS5ZMMpUaZe",
"content": [
{
"type": "web_search_result",
"title": "ai.moda - Crunchbase Company Profile",
"url": "https://www.crunchbase.com/organization/ai-moda",
"encrypted_content": "REMOVED_FOR_BLOG_BLOG_LENGTH_REASONS",
"page_age": null
},
{
"type": "web_search_result",
"title": "Meet David Manouchehri, Director at ai.moda SEZC",
"url": "https://www.caymanenterprisecity.com/blog/meet-david-manouchehri",
"encrypted_content": "REMOVED_FOR_BLOG_BLOG_LENGTH_REASONS",
"page_age": null
},
{
"type": "web_search_result",
"title": "ai.moda",
"url": "https://www.ai.moda/en/",
"encrypted_content": "REMOVED_FOR_BLOG_BLOG_LENGTH_REASONS",
"page_age": null
},
{
"type": "web_search_result",
"title": "List of top Cayman Islands Companies - Crunchbase Hub Profile",
"url": "https://www.crunchbase.com/hub/cayman-islands-companies",
"encrypted_content": "REMOVED_FOR_BLOG_BLOG_LENGTH_REASONS",
"page_age": null
}
]
},
{
"type": "text",
"text": "Based on the search results, I found information about ai.moda's company location and headquarters in the Cayman Islands:\n\n"
},
{
"citations": [
{
"type": "web_search_result_location",
"cited_text": "George Town, Midland, Cayman Islands. ",
"url": "https://www.crunchbase.com/organization/ai-moda",
"title": "ai.moda - Crunchbase Company Profile",
"encrypted_index": "REMOVED_FOR_BLOG_BLOG_LENGTH_REASONS"
},
{
"type": "web_search_result_location",
"cited_text": "ai.moda is located in \u00b7 George Town, Midland, Cayman Islands. ",
"url": "https://www.crunchbase.com/organization/ai-moda",
"title": "ai.moda - Crunchbase Company Profile",
"encrypted_index": "REMOVED_FOR_BLOG_BLOG_LENGTH_REASONS"
}
],
"type": "text",
"text": "ai.moda is headquartered in George Town, Midland, Cayman Islands."
},
{
"type": "text",
"text": "\n\nAccording to the search results, "
},
{
"citations": [
{
"type": "web_search_result_location",
"cited_text": "Hailing from Ottawa, Canada, David Manouchehri is the Director of ai.moda SEZC and is helping to build scalable artificial intelligence (AI) and machi...",
"url": "https://www.caymanenterprisecity.com/blog/meet-david-manouchehri",
"title": "Meet David Manouchehri, Director at ai.moda SEZC",
"encrypted_index": "REMOVED_FOR_BLOG_BLOG_LENGTH_REASONS"
}
],
"type": "text",
"text": "David Manouchehri is the Director of ai.moda SEZC and is helping to build scalable artificial intelligence (AI) and machine learning (ML) solutions from his Cayman Enterprise City (CEC) office in the heart of George Town."
},
{
"type": "text",
"text": "\n\n"
},
{
"citations": [
{
"type": "web_search_result_location",
"cited_text": "ai.moda provides AI consulting services to help companies integrate artificial intelligence into their products, services, processes and platforms. ",
"url": "https://www.ai.moda/en/",
"title": "ai.moda",
"encrypted_index": "REMOVED_FOR_BLOG_BLOG_LENGTH_REASONS"
}
],
"type": "text",
"text": "ai.moda provides AI consulting services to help companies integrate artificial intelligence into their products, services, processes and platforms."
},
{
"type": "text",
"text": "\n\nThe company appears to be registered as \"ai.moda SEZC\" which indicates it's operating within the Cayman Enterprise City's Special Economic Zone. "
},
{
"citations": [
{
"type": "web_search_result_location",
"cited_text": "CEC: ai.moda was recently announced as the first in the Caribbean region to be accepted into the Cloudflare Workers Launchpad funding program. ",
"url": "https://www.caymanenterprisecity.com/blog/meet-david-manouchehri",
"title": "Meet David Manouchehri, Director at ai.moda SEZC",
"encrypted_index": "REMOVED_FOR_BLOG_BLOG_LENGTH_REASONS"
}
],
"type": "text",
"text": "ai.moda was recently announced as the first in the Caribbean region to be accepted into the Cloudflare Workers Launchpad funding program."
}
],
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 14,
"cache_creation_input_tokens": 10615,
"cache_read_input_tokens": 2091,
"output_tokens": 421,
"server_tool_use": {
"web_search_requests": 1
}
}
}Second response
Some of you are probably wondering.. why does Anthropic even do the first request, instead of just going straight to the second request? I believe the answer is pretty simple: using a server_tool_use directly in the first prompt would break the ability for Claude Code to allow user's to configure consent (reliability) before searching.
Finally, Claude Code does a third request to complete the initial query.
{
"model": "claude-opus-4-20250514",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Is ai.moda based in the Cayman Islands?"
}
]
},
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "I'll search for information about ai.moda and its location."
},
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "WebSearch",
"input": {
"query": "ai.moda company location headquarters Cayman Islands"
}
}
]
},
{
"role": "user",
"content": [
{
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"type": "tool_result",
"content": "Web search results for query: \"ai.moda company location headquarters Cayman Islands\"\n\nI'll search for information about ai.moda's company location and headquarters in the Cayman Islands.\n\nLinks: [{\"title\":\"ai.moda - Crunchbase Company Profile\",\"url\":\"https://www.crunchbase.com/organization/ai-moda\"},{\"title\":\"Meet David Manouchehri, Director at ai.moda SEZC\",\"url\":\"https://www.caymanenterprisecity.com/blog/meet-david-manouchehri\"},{\"title\":\"ai.moda\",\"url\":\"https://www.ai.moda/en/\"}]\n\nBased on the search results, I found information about ai.moda's company location and headquarters in the Cayman Islands:\n\n## ai.moda Company Location Details\n\nai.moda is headquartered in George Town, Midland, Cayman Islands. More specifically, David Manouchehri is the Director of ai.moda SEZC and is helping to build scalable artificial intelligence (AI) and machine learning (ML) solutions from his Cayman Enterprise City (CEC) office in the heart of George Town.\n\n### Key Information:\n\n1. **Legal Entity**: ai.moda SEZC - The \"SEZC\" designation indicates it's registered as a Special Economic Zone Company in the Cayman Islands.\n\n2. **Location within Cayman**: The company operates from Cayman Enterprise City (CEC) office in the heart of George Town.\n\n3. **Business Focus**: ai.moda provides AI consulting services to help companies integrate artificial intelligence into their products, services, processes and platforms. Our experts can customize AI solutions to meet your unique business needs.\n\n4. **Why Cayman Islands**: According to the Director, Cayman - Very easy to convince highly skilled talent to relocate (it's a <4-hour flight to NYC or Toronto), no income tax, and the visa process is easy enough compared to other jurisdictions like the US, Canada, or Dubai.\n\n5. **Recognition**: ai.moda was recently announced as the first in the Caribbean region to be accepted into the Cloudflare Workers Launchpad funding program.\n\nThe company chose the Cayman Islands for its favorable business environment, proximity to North American talent pools, tax advantages, and simplified visa processes for international workers."
}
]
}
],
"temperature": 1,
"system": [
{
"type": "text",
"text": "You are Claude Code, Anthropic's official CLI for Claude."
}
],
"tools": [
{
"name": "WebSearch",
"description": "\n- Allows Claude to search the web and use the results to inform responses\n- Provides up-to-date information for current events and recent data\n- Returns search result information formatted as search result blocks\n- Use this tool for accessing information beyond Claude's knowledge cutoff\n- Searches are performed automatically within a single API call\n\nUsage notes:\n - Domain filtering is supported to include or block specific websites\n - Web search is only available in the US\n",
"input_schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"minLength": 2,
"description": "The search query to use"
},
"allowed_domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Only include search results from these domains"
},
"blocked_domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Never include search results from these domains"
}
},
"required": [
"query"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
}
],
"max_tokens": 32000
}Third (Final) Request
Notice how we aren't using the web_search_20250305 tool anymore?
{
"id": "msg_015mdMjYkpW8TpsWvGqqmYhn",
"type": "message",
"role": "assistant",
"model": "claude-opus-4-20250514",
"content": [
{
"type": "text",
"text": "Yes, ai.moda is based in the Cayman Islands. Specifically, they are headquartered in George Town as ai.moda SEZC (Special Economic Zone Company) and operate from Cayman Enterprise City offices."
}
],
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 5,
"cache_creation_input_tokens": 19215,
"cache_read_input_tokens": 0,
"output_tokens": 49
}
}Final Response
And there you have it. What you probably thought was one request, is actually three requests!
Note: We've simplified and removed a few unrelated fields from the requests and responses in this post to focus on just web searching.