WebSearchTool: Web search

The WebSearchTool enables Claude Code to query the internet for up-to-date information.
The core problem it solves is not "opening a specific webpage", but rather:

How to safely initiate an internet search when the main thread needs to know what has recently happened in the world, what the latest documentation for a product is, or what public resources are available for a given issue.

Therefore, you must first clearly remember the difference between it and WebFetchTool:

• WebSearchTool: Finds information sources
• WebFetchTool: Reads specific pages

In real-world usage, these two tools are often used sequentially.

tools/WebSearchTool/WebSearchTool.ts:

const inputSchema = z.strictObject({
  query: z.string().min(2).describe('The search query to use'),
  allowed_domains: z.array(z.string()).optional(),
  blocked_domains: z.array(z.string()).optional(),
})

At first glance, there are only 3 fields, but they already cover the most critical search controls:

• What to search for
• Which domains to include
• Which domains to exclude

This means Claude Code's internet search is not a "random scrape," but supports constrained searching.

The most critical part in the source code regarding this tool's schema construction is:

function makeToolSchema(input: Input): BetaWebSearchTool20250305 {
  return {
    type: 'web_search_20250305',
    name: 'web_search',
    allowed_domains: input.allowed_domains,
    blocked_domains: input.blocked_domains,
    max_uses: 8,
  }
}

This shows that the WebSearchTool does not simulate a browser itself, nor does it call third-party search APIs via shell.
It actually integrates the official Web Search server tool into Claude Code's tooling system.

In other words, what it does is:

The main thread of Claude Code triggers it, and the underlying model capability supporting Web Search executes it.

Model needs latest info > WebSearchTool > Constructs web_search schema > queryModelWithStreaming

Triggers server tool: web_search > Returns search hits and commentary > Parses result blocks > Main thread continues referencing results.

This code in call() best reveals its essence:

const queryStream = queryModelWithStreaming({
  messages: [userMessage],
  systemPrompt: asSystemPrompt([
    'You are an assistant for performing a web search tool use',
  ]),
  tools: [],
  options: {
    extraToolSchemas: [toolSchema],
    querySource: 'web_search_tool',
    ...
  },
})

There are several key points here:

1. It initiates a new model call itself
2. The purpose of this call is not to provide a standard answer, but to execute a search
3. The search tool is injected via extraToolSchemas

This indicates that the WebSearchTool is essentially a wrapper-type tool:

• The outer layer is Claude Code's standard tool interface
• The inner layer initiates another model request supporting web search

There is a critical parsing logic in the source code:

function makeOutputFromSearchResponse(
  result: BetaContentBlock[],
  query: string,
  durationSeconds: number,
): Output

The comment is very direct: the returned content is not a simple array, but a series of mixed blocks:

• server_tool_use
• web_search_tool_result
• text
• Citation-related blocks

Therefore, a core function of the WebSearchTool is:

Reorganizing the search result blocks returned by the underlying layer into a structure that Claude Code can more easily consume.

There is a crucial section in the output schema:

results: z
  .array(z.union([searchResultSchema(), z.string()]))
  .describe('Search results and/or text commentary from the model')

This means the returned result is not a pure list of search hits, but may simultaneously contain:

• A set of search hits
• A block of explanatory text

In other words, the WebSearchTool doesn't just throw links back; it allows the model to supplement intermediate explanations alongside the search results.

Standard search APIs often return:

• Title
• URL
• Snippet/Summary

Whereas Claude Code's WebSearchTool will also process:

• Tool call blocks
• Text explanation blocks
• Citation and source requirements

This makes it more suitable for direct integration into the main loop, rather than serving only as a data source.

tools/WebSearchTool/prompt.ts：

CRITICAL REQUIREMENT - You MUST follow this:
  - After answering the user's question, you MUST include a "Sources:" section at the end of your response
  - In the Sources section, list all relevant URLs from the search results as markdown hyperlinks

This demonstrates that Anthropic's product requirements for this tool are very clear:

• Whenever a web search is used
• The final response must include sources

WebSearchTool > Retrieve latest search results > Main thread generates response > Append Sources link

From a product perspective, this is also what makes Claude Code more mature than systems where "a model secretly searches without telling you the sources."

IMPORTANT - Use the correct year in search queries:
  - The current month is ${currentMonthYear}. You MUST use this year when searching for recent information

This shows Anthropic has already recognized a very real issue:

If the model searches for "latest React docs" without including the current year, it will likely fetch outdated content.

So the prompt explicitly requires it to include the current year when searching for "the latest information."
This is a very typical product-hardening step.

if (provider === 'firstParty') return true
if (provider === 'vertex') {
  const supportsWebSearch =
    model.includes('claude-opus-4') ||
    model.includes('claude-sonnet-4') ||
    model.includes('claude-haiku-4')
  return supportsWebSearch
}
if (provider === 'foundry') return true
return false

This shows that WebSearchTool isn't a fixed capability available across "all Claude Code runtime environments."
It is subject to:

• API provider
• Model capabilities
• Platform support status

acting in concert.
This is exactly why such tools require a dedicated isEnabled().

async checkPermissions(_input): Promise<PermissionResult> {
  return {
    behavior: 'passthrough',
    message: 'WebSearchTool requires permission.',
    suggestions: [
      {
        type: 'addRules',
        rules: [{ toolName: WEB_SEARCH_TOOL_NAME }],
        behavior: 'allow',
        destination: 'localSettings',
      },
    ],
  }
}

This shows it leans more toward "tool-level permissions," unlike WebFetchTool, which refines rules down to the domain level.
The reasoning is straightforward:

• WebSearchTool handles generalized searches
• WebFetchTool handles specific URL access

The latter inherently offers finer-grained security boundaries.

WebSearchTool > Identify candidate sources > Select trusted URLs > WebFetchTool > Extract and distill page content

This workflow excels at:

• Querying the latest documentation
• News or recent announcements
• Comparing multiple sources of information
• Digging deeper into individual pages from search results

For example, if a user asks:

How is /usage currently documented on the official Claude Code commands page?

The main thread's typical path would be:

1. WebSearchTool searches official documentation or a specific domain
2. Locates the command documentation page
3. Passes it to WebFetchTool to fetch the full content
4. Finally assembles the response and appends sources

This is precisely why WebSearchTool acts more like a "gateway finder" rather than something that "directly completes the research."

Not entirely accurate.
It also includes:

• Model-initiated server tool calls
• Content block parsing
• Source constraints
• Environment and provider checks

Also incorrect.
Search results are typically just entry points; actually reading the content usually still requires WebFetchTool.

It merely provides web search capability, which doesn't guarantee that results will be flawless.
That's why Anthropic specifically requires in the prompt:

• Using the current year
• Listing sources in the response

All of these are intended to reduce the risk of "retrieving outdated information" or "being unable to clarify sources."

To summarize in a single sentence:

WebSearchTool is Claude Code's entry point for web retrieval; it initiates searches via the official web search schema, then formats the underlying search result blocks into structured output that the main loop can consume.

What truly makes it important goes beyond just being "able to search:"

It connects search results, source constraints, model/environment context, and subsequent web deep-dives into a complete, integrated web workflow.