Claude Code Tools Deep Dive (11): WebFetch + WebSearch

This is the eleventh article in my series on Claude Code tools. The first ten covered Claude Code’s mostly inward-facing toolkit: aligning with the user, operating the local filesystem, running commands, spawning subagents, and managing todos. All of those tools are built around the local environment.

Real engineering work often requires Claude to leave the local environment: read Anthropic’s API documentation, inspect a third-party library’s GitHub README, find a current npm tutorial, or verify an official specification. That information may not be local—or it may postdate the training data.

Claude Code answers with a pair of internet tools: WebFetch retrieves content from one known URL; WebSearch finds URLs across the web from a query.

This series begins with a prerequisite article explaining what tools are and how Claude uses them. Like the other articles, this one follows the four-layer framework introduced there.

WebFetch + WebSearch

These tools are covered together for the same reason as Grep + Glob: their semantics are tightly coupled. One fetches by URL and the other searches by query, and they are frequently combined—Search finds an entry point, then Fetch extracts the content.

Family overview

Tool	Input	Output	Typical use
WebFetch	One known URL	Page content, transformed from HTML to Markdown	“Read this documentation and extract X”
WebSearch	A query	Search results with titles and URLs	“Find the latest way to do X”

The division is simple:

• Know the URL? Call WebFetch directly.
• Do not know the URL? Use WebSearch, then WebFetch the useful results.

This mirrors Grep + Glob in the local filesystem. Grep + Glob search and locate locally; WebSearch + WebFetch do the same work on the public internet. The mental model stays the same; only the domain changes.

What they do

Together, WebFetch and WebSearch solve how Claude can break through the time and scope limits of training data and obtain current, specific external information:

1. Break through the training cutoff: search and fetch can retrieve information published today.
2. Break through training coverage: an obscure library may not appear in training data, but its official docs can be fetched.
3. Verify official information: when an answer promises citations or official wording, the source must actually be read.
4. Compress content: WebFetch uses AI to return only what the prompt asks for instead of placing an entire HTML page in context.

This family differs from every earlier tool in one decisive way: it is the only one that crosses the local boundary. The first ten tools operate on the local machine; WebFetch and WebSearch connect Claude to the public web.

A concrete example

Scenario: The user says, “I think Anthropic recently released a Claude 4.5 Sonnet model. Look up how to use its API, especially what changed from Claude 4, and check the pricing.”

The information is online, may postdate training, and is too volatile to answer from memory:

• the model may be newly released
• API parameters may have changed
• pricing numbers are not safe to guess

Step 1: Find an entry point with WebSearch

Claude does not know the exact URL but knows the information should come from Anthropic:

WebSearch(
  query: "Claude 4.5 Sonnet API pricing announcement 2026",
  allowed_domains: ["anthropic.com", "docs.anthropic.com"]
)

allowed_domains narrows the search to official sites and excludes marketing pages or second-hand summaries.

The results might be:

1. Claude 4.5 Sonnet — Anthropic
   https://www.anthropic.com/news/claude-4-5-sonnet
2. Models Overview — Anthropic Docs
   https://docs.anthropic.com/en/docs/about-claude/models
3. Pricing — Anthropic
   https://www.anthropic.com/pricing

Each result is a title and URL, not the full page. Claude now has three precise entry points.

Step 2: Extract the details with WebFetch

Claude fetches each URL with a specific prompt:

WebFetch(
  url: "https://www.anthropic.com/news/claude-4-5-sonnet",
  prompt: "Extract the release date, improvements over Claude 4, benchmark numbers, and API model ID."
)

The second argument does not mean “return the full page.” It means process the page for this purpose. Behind the scenes, the runtime:

• fetches the URL
• converts HTML to Markdown
• uses a smaller, faster model to extract what the prompt requests
• returns only the extracted result

A 5,000-word article may become 200 words in the main context. Like Agent, WebFetch is a context-compression mechanism.

After three WebFetch calls, Claude has structured summaries sufficient to answer the API, comparison, and pricing questions.

Key insight: WebFetch is curl with AI

Traditional curl means “URL in, raw HTML out.” WebFetch means “URL plus intent in, processed result out.”

• With curl, Claude must parse HTML, remove CSS and navigation noise, and ignore advertisements.
• With WebFetch, the runtime’s AI does that work and returns content already extracted for the question.

WebFetch is therefore an on-demand internet extraction primitive, not merely a webpage downloader.

When they are triggered

Use WebSearch when:

• you need current information beyond the training cutoff
• you do not know the exact URL
• you want to compare several sources
• you need to search within a particular domain using allowed_domains
• you want to exclude particular domains using blocked_domains

Use WebFetch when:

• the URL is known from the user or WebSearch
• you need official docs, specifications, or API references summarized against a specific prompt
• you need to verify a citation
• you need a GitHub README or documentation page, although gh is usually better for GitHub

Combine them when:

• Search finds URLs → choose authoritative results → Fetch details → synthesize the answer
• Search finds three to five sources → Fetch each → cross-check them

Do not use them when:

• the answer is stable and already in training knowledge, such as basic JavaScript syntax
• the content is GitHub-specific; use gh through Bash when possible
• the URL requires authentication; WebFetch cannot access Google Docs, Confluence, Jira, or private GitHub repositories
• the information is local; use Grep instead of WebSearch

The central principle is: do not go online unnecessarily. The web is slower, more expensive, and vulnerable to network failures and page changes. Use it only when local files and training knowledge are insufficient.

Technical design

WebFetch and WebSearch are sibling tools with a shared design philosophy. Their roles are distinct but complementary, so we can examine both through the four-layer framework.

---

WebFetch

1. Naming

WebFetch

The name says exactly what it does: fetch a web resource. “Fetch” is an industry verb from the Fetch API and git fetch, suggesting retrieval rather than exploration. The url field is immediately familiar to anyone who has worked with the web.

ReadURL would be misleading because WebFetch is not a lossless Read operation. It performs AI-assisted, on-demand extraction. HTTPGet would be too low-level and would lose the promise of processing content against a prompt. Fetch sits between raw retrieval and AI processing, which is exactly the intended semantic boundary.

2. Tool-level description

WebFetch’s description is heavier than most tools. It begins with an all-caps IMPORTANT and follows with usage notes focused on four concerns: authentication failures, MCP precedence, GitHub specialization, and redirect safety.

IMPORTANT: authenticated services are out of scope

IMPORTANT: WebFetch WILL FAIL for authenticated or private URLs. Before using this tool, check if the URL points to an authenticated service such as Google Docs, Confluence, Jira, or GitHub. If so, look for a specialized MCP tool that provides authenticated access.

This is the strongest sentence in the WebFetch description. IMPORTANT plus WILL FAIL prevents a wasted call into a 401 or 403. It also gives a replacement: find an authenticated MCP tool.

Every “no” comes with a “yes”: not this fetcher, but that specialized tool. Claude learns to inspect the available tool ecosystem before acting.

MCP takes precedence

IMPORTANT: If an MCP-provided web fetch tool is available, prefer using that tool instead, as it may have fewer restrictions.

WebFetch explicitly acknowledges its limits. If a specialized MCP fetcher exists, use it. This humility is unusual in tool descriptions and reinforces the rule that authentication and capability-specific access belong to a better adapter.

GitHub gets a specialized instruction

For GitHub URLs, prefer using the gh CLI via Bash instead, such as gh pr view, gh issue view, or gh api.

GitHub is singled out because it is common and because gh can use the user’s local credentials. It can access private repositories and review comments that an anonymous WebFetch cannot. This is a case where a specific workflow outranks the general-purpose tool.

Cross-host redirects require an explicit protocol

When a URL redirects to a different host, the tool will inform you and provide the redirect URL in a special format. You should then make a new WebFetch request with the redirect URL.

WebFetch does not silently follow a cross-host redirect. It reports the new URL and lets Claude decide whether to fetch it. Same-host redirects can remain convenient; cross-host redirects become an explicit security boundary. This protects against pages that quietly send the fetcher somewhere unexpected.

Transparent 15-minute caching

Includes a self-cleaning 15-minute cache for faster responses when repeatedly accessing the same URL.

Claude is told that repeated calls to the same URL may be faster. The disclosure encourages useful re-fetching in one session without making Claude worry that every retry is wasteful.

Automatic HTTP-to-HTTPS upgrade

HTTP URLs will be automatically upgraded to HTTPS.

This makes a hidden behavior explicit. Claude can provide http:// and the runtime upgrades it without requiring a manual edit—lowering error rates without relying on silent magic.

3. Field-level descriptions

WebFetch has only two fields, but both are required:

• url: the complete URL
• prompt: what to extract from the page

Why is prompt required? Because WebFetch does not return the full page. It returns content processed according to the prompt. Without one, the small runtime model would not know what to extract or how much to return.

Compare the two mental models:

curl https://example.com
→ raw HTML, potentially tens of thousands of words

WebFetch(url, prompt: "Extract the three key points")
→ a focused summary

Writing the prompt is like briefing a new colleague. “Read this page” is shallow; “Find every rate-limit number, list each one, and say explicitly if none is present” is precise.

Making prompt required is WebFetch’s most elegant field decision. It forces Claude to decide what it needs before fetching, protecting the context budget instead of fetching first and filtering later.

4. Schema validation

WebFetch’s schema has almost no hard constraints:

Field	Type	Constraint
url	string	URI format validation
prompt	string	required; no length constraint

The one physical barrier is url with a URI format. A value such as foo is rejected before the tool call is sent. Claude must provide a complete URL.

Everything else—authentication, GitHub, MCP, redirects, and when to use the tool—lives in natural-language guidance. WebFetch’s complexity is not parameter validation; it is judging when the tool should not be used.

---

WebSearch

1. Naming

WebSearch

The tool uses Search rather than WebQuery or GoogleSearch, preserving generality and avoiding a search-engine brand. Its behavior is “query in, result set out,” exactly what Search means.

Together with WebFetch, the names form a clean pair: Fetch retrieves a known URL; Search discovers URLs from terms.

2. Tool-level description

WebSearch contains two unusually strong constraints: citation obligations and explicit time awareness. Its description focuses on four ideas: capability, mandatory Sources, domain filtering, and the correct year.

Basic capability

Allows Claude to search the web and use the results to inform responses. Provides up-to-date information for current events and recent data.

These two sentences state why WebSearch exists: to overcome the freshness limits of training data.

Mandatory citations at CRITICAL strength

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 that section, list all relevant URLs from the search results as Markdown hyperlinks: Title.
• This is MANDATORY—never skip the Sources section.

This is the heaviest paragraph in the WebSearch description. CRITICAL, MUST repeated three times, and MANDATORY elevate citation from advice to law.

Why require Sources? Search results come from uncontrolled sources: some are biased, stale, or optimized for SEO. A Sources section provides traceability so the user can inspect whether the answer rests on reliable material.

It also enforces the fact-checking discipline established at the beginning of the series. If Claude promises official or cited information, it must actually retrieve the source, and WebSearch must expose the URLs.

Domain filtering

Domain filtering is supported to include or block specific websites.

This reminds Claude that allowed_domains can create an official-source whitelist, while blocked_domains can exclude low-quality or unwanted sites. To verify Anthropic’s official wording, for example, search only anthropic.com.

The current-year rule

IMPORTANT - Use the correct year in search queries. The current month is July 2026. You MUST use this year when searching for recent information, documentation, or current events. For “latest React docs,” search with the current year, not last year.

Hardcoding the current time in a tool description is unusual, but the reason is profound: Claude may not know which month it is after its training cutoff. Search freshness depends on dates. Adding the year to the query helps distinguish current documentation from old results.

The React example turns an abstract rule into a concrete comparison: correct current year versus stale year.

US-only availability

Domain filtering is supported to include or block specific websites. Web search is only available in the US.

This small boundary statement prevents failed calls in unsupported regions.

3. Field-level descriptions

• query: required search terms
• allowed_domains: optional whitelist array
• blocked_domains: optional blacklist array

The two domain filters expose two independent information postures:

• allowed_domains: search only sources Claude trusts, such as anthropic.com or docs.python.org.
• blocked_domains: exclude sources Claude does not want, such as outdated or low-quality sites.

The same domain should not logically appear in both lists, but the tool leaves that judgment to Claude rather than forbidding both arrays at the schema level.

The only explicit field-level minimum is that query must contain at least two characters, preventing meaningless one-character searches.

4. Schema validation

Field	Type	Constraint
query	string	minLength: 2
allowed_domains	array of strings	optional
blocked_domains	array of strings	optional

minLength: 2 is a physical schema barrier. A one-character query is rejected directly, even though a single Chinese character might sometimes be meaningful. The tool chooses a simple universal rule.

The domain arrays are intentionally permissive. The schema allows both to be populated; prompt guidance handles the logical conflict. Capability remains open while judgment stays with Claude.

---

Why dedicated WebFetch and WebSearch instead of Bash + curl/search APIs?

Bash could theoretically combine curl with a search API, but that creates several problems:

• HTML parsing: raw curl output includes CSS, navigation, and advertisements.
• Credential leakage: a local curl might accidentally use .netrc or cookies.
• Search API key management: someone must provide and protect Google or Bing API credentials.
• No citation obligation: Claude could summarize curl output without reporting sources.
• No content compression: a 50,000-word page could flood the context.

The dedicated tools solve these problems: HTML becomes Markdown automatically, fetching is anonymous, API credentials are managed by the runtime, WebSearch requires Sources, and WebFetch extracts against a prompt. This is another example of the division: Bash is the catch-all; dedicated tools are the refined interface.

---

Division of responsibility among neighboring tools

Dimension	Interaction trio	Locate + perceive + execute	Bash	Agent	Task family	WebFetch / WebSearch
Role	Collaborative alignment	Modify code	Execute commands	Derive Claude	Externalize working memory	Reach the public web
Input source	User	Disk	Command	Prompt	User / AI	URL / query
Output	Structured	Text / diff	Raw text	Subagent result	State	HTML → Markdown / summaries
Authentication	None	Existing user session	User credentials	Forked session	User session	Anonymous; no credentials
Main benefit	User alignment	Precise code changes	Engineering workflow	Context space	Against forgetting	Controllable information access

WebFetch + WebSearch mirror Grep + Glob:

• Grep + Glob: find by content or path inside a project.
• WebFetch + WebSearch: fetch by URL or search by terms on the public web.

Both pairs implement “one precise target plus one exploratory search,” but the web pair faces an untrusted external world. That is why it adds MCP precedence, explicit cross-host redirects, and mandatory Sources.

The boundary with Bash is equally clear. Curl and search APIs could do the work, but they expose parsing, credentials, keys, citations, and context to risk. Dedicated tools package those concerns into a controlled interface.

---

Summary

WebFetch + WebSearch split the broad request “let the AI browse the web” into two specialized tools and use all four design layers:

• Naming: Fetch and Search borrow industry conventions. Fetch implies a known target; Search implies exploratory discovery.
• Tool-level descriptions: WebFetch emphasizes authentication failures, MCP precedence, GitHub specialization, and redirect safety. WebSearch emphasizes mandatory Sources and the current-year rule—one protects traceability, the other compensates for Claude’s weak time awareness.
• Field design: WebFetch has only two fields, but making prompt required elevates on-demand extraction and protects context. WebSearch exposes allowed and blocked domains as independent trust controls.
• Schema validation: WebFetch rejects non-URI strings; WebSearch rejects one-character queries. Basic mistakes are stopped physically at the schema boundary.

Several signals are unique across the tool ecosystem:

• Required prompt: WebFetch becomes an extraction primitive rather than a page downloader.
• Mandatory Sources: WebSearch is the only tool whose description uses CRITICAL and MANDATORY to enforce response formatting and citation transparency.
• Hardcoded current time: a dynamic date is inserted into a static prompt to compensate for Claude’s missing sense of the current month.
• Humility toward MCP: the tool explicitly says “not me—use the authenticated or more capable MCP tool.”
• No automatic cross-host redirects: the security decision is handed to Claude through an explicit protocol rather than silent behavior.

Together these signals turn the ability to reach the public web into an external information interface that is controlled, traceable, and willing to defer to better tools.

The next article will examine the Cron family, shifting from the spatial dimension—project and public web—to the time dimension: scheduled and future execution.