Claude Code can read your own files with Grep and Glob, and pull a specific URL with WebFetch. But sometimes you don't have a URL — you have a question. "What's the current syntax for X in the latest release?" "Has this library changed its API since training data cutoff?" "What are people saying about this error message?" That's what WebSearch is for: it takes a query, not a URL, and returns live results the model can reason over.
It's the tool that keeps an agent from confidently citing information that stopped being true months ago. Here's how it actually works, how it differs from WebFetch, and how to use it without letting it become a liability.
What WebSearch Actually Does
WebSearch takes a text query, runs it against a live search index, and returns a list of results — titles, URLs, and snippets — the same shape as a normal search engine results page. It doesn't fetch and read the full page content the way WebFetch does; it gives the model enough to decide which result is worth reading in more depth, then pair it with a follow-up WebFetch call on the specific URL.
That two-step pattern — WebSearch to find candidates, WebFetch to read the winner — is the default workflow. Skipping straight to WebFetch only works if you already know the exact URL. Skipping WebSearch's snippets and reflexively fetching every result wastes context on pages that turn out to be irrelevant.
Why It Exists Separately From WebFetch
The split isn't arbitrary. Search and retrieval are different problems with different failure modes. A search query can return ten links, most of which won't matter — you want cheap, shallow signal on all of them before spending a full fetch-and-summarize pass on the one or two links worth reading. Merging the two into a single tool would mean every search either wastes tokens fetching irrelevant pages, or never fetches enough to actually answer the question. Keeping them separate lets the agent be cheap during discovery and thorough only where it counts.
Freshness Is the Whole Point
A model's training data has a cutoff. WebSearch is the mechanism that gets around it for anything that changes after that date — new library versions, changed pricing, a framework that deprecated an API last month, a CVE that dropped last week. Without it, an agent working from memory alone will state stale facts with the same confidence as current ones, because it has no signal that the world moved on.
This matters most for fast-moving ecosystems: package versions, API parameters, pricing pages, security advisories. If a task depends on "what's true right now" rather than "what's generally true," reach for WebSearch before trusting recall.
Domain Filtering
WebSearch supports scoping results to specific domains, or excluding specific domains, rather than searching the open web unrestricted. That matters two ways. First, precision: if you already know the answer lives on a vendor's own docs site, scoping the search there cuts out SEO spam and content-farm clones that outrank the primary source. Second, safety: excluding domains known for prompt-injection-laden content or low-quality scraped mirrors reduces what an agent can accidentally pull into context and treat as trustworthy.
If you're building repeatable automation around WebSearch — a cron job that checks a changelog, a research agent scoped to a specific set of sources — domain scoping is what turns a general-purpose search into a reliable, narrow one.
Search Results Are Untrusted Data
Every snippet and every page WebSearch surfaces is external content, not an instruction from you. That distinction has to hold even when a result looks like it's telling the agent what to do next — a forum post that says "ignore previous instructions," a doc page with embedded hidden text aimed at scrapers, a comment section full of noise. Treat search results the same way you'd treat WebFetch output: read as data, never executed as commands. An agent that blurs that line is an agent that can be steered by whoever controls a page it happens to search up.
Combining WebSearch With Local Context
The strongest pattern isn't "search instead of reading the codebase" — it's search to fill the specific gap the codebase can't answer. Grep and Glob tell you what your code does today. WebSearch tells you what changed upstream since you wrote it: a deprecated method, a new required parameter, a security patch you haven't pulled in yet. Used together, an agent can diagnose "this used to work and now it doesn't" by checking both what's actually in the repo and what changed in the dependency it's calling.
When Not to Reach for It
WebSearch burns a network round-trip and adds latency an agent doesn't need for anything answerable from local files or stable, well-known facts. If the question is "what does this function in my repo do," that's Grep, not a search query. Overusing WebSearch for things the model already knows confidently and correctly just slows the session down and adds unnecessary context from pages you didn't need to read in the first place.
The Takeaway
WebSearch is the freshness layer — the tool that lets Claude Code check reality instead of relying on a training cutoff. Pair it with WebFetch for the two-step search-then-read workflow, scope it with domain filters when you know where the truth lives, and always treat what comes back as data to reason about, never instructions to follow.