Claude Code can read your codebase natively — Grep, Glob, LSP references, the works. But the moment a task needs something outside the repo — a library's actual API docs, a spec page, a changelog, a Stack Overflow thread — it needs a different tool. That's WebFetch: the tool that turns a URL into readable content the model can reason over.
It sounds simple. It isn't just curl with extra steps. Here's what WebFetch actually does under the hood, how it differs from WebSearch, and the patterns that make it useful instead of a liability.
What WebFetch Actually Does
WebFetch takes a URL and a prompt, then does three things: fetches the page, converts the HTML to markdown, and runs that markdown through a small, fast model along with your prompt to extract exactly what you asked for. You don't get a raw HTML dump dropped into context — you get an answer, distilled from the page, sized to the question.
That distillation step matters more than it looks. A raw fetch of a docs page can be 40,000 tokens of nav bars, cookie banners, and boilerplate. Asking "what are the required parameters for this endpoint" and getting back a clean answer instead of the whole page is the difference between a tool that's usable mid-task and one that blows your context budget on the first call.
The Redirect Behavior You Need to Know
WebFetch upgrades HTTP to HTTPS automatically, and if a fetch hits a redirect, it doesn't silently follow it into somewhere you didn't ask to go. Instead it reports the redirect target back as a new URL, and the agent has to make a second, explicit WebFetch call to follow it. That's a deliberate design choice — an agent that transparently follows every redirect can be walked somewhere unintended by a malicious server. Requiring an explicit second call keeps a human-reviewable trail of exactly which URLs got fetched.
If you're building automation on top of Claude Code and a fetch seems to "fail" on a page that clearly exists, check whether it actually returned a redirect notice instead of an error. That's usually the case, and the fix is just calling WebFetch again on the new URL.
The 15-Minute Cache
Repeated WebFetch calls to the same URL with the same prompt within about 15 minutes are served from a self-cleaning cache instead of re-fetching. This is why a long agent session that references the same doc page five times in a row doesn't rack up five separate fetches — and why, if a page just changed and you need fresh content, you may need to wait out the cache window or change your prompt to force a new fetch. It's not something you configure; it's automatic behavior worth knowing about so you're not confused when a page seems "stuck" on stale content mid-session.
WebFetch vs. WebSearch: Different Jobs
These two tools get confused constantly because they both touch the internet, but they solve different problems:
- WebSearch takes a query and returns search results — titles, snippets, URLs. It's for finding things when you don't already know the exact page.
- WebFetch takes a specific URL you already have and extracts content from it. It's for reading things once you know where they are.
The most common real-world pattern is chaining them: WebSearch to find the current docs page for a library version, then WebFetch on the top result to actually read what it says. Skipping straight to WebFetch on a guessed URL is a common failure mode — agents (and engineers) love to construct a URL that should exist based on a naming pattern, and it doesn't. Search first when you're not certain the URL is real.
Practical Use Cases
1. Checking library docs before implementing against them
Rather than trusting training-data knowledge of an API that may be a year stale, WebFetch the current docs page for the exact method signature, deprecations, and required parameters before writing code against it. This single habit catches a surprising number of "the API changed since the model was trained" bugs before they ship.
2. Reading a linked GitHub issue or PR
When debugging a dependency's weird behavior, fetching the actual GitHub issue thread (not just a summary) surfaces workarounds and maintainer comments that never make it into changelogs.
3. Pulling a spec or RFC directly
For anything protocol-level — OAuth flows, webhook signature verification, a JSON schema definition — fetching the primary spec beats working from a half-remembered blog post about the spec.
4. Verifying a claim before it ships in content or code comments
If a task involves citing a stat, a pricing tier, or a policy detail, WebFetch on the source page is the fast way to confirm it's still accurate rather than assuming it hasn't changed.
Where WebFetch Falls Short
It's not a browser. Pages that require JavaScript execution to render their actual content — heavy client-side SPAs, content gated behind an interactive login, infinite-scroll feeds — often return a shell of markup with none of the real content, because WebFetch fetches and converts static HTML rather than executing scripts. If a fetch comes back suspiciously empty, that's usually why. In those cases, a real browser-automation tool is the correct escalation, not repeated identical fetches expecting a different result.
It also isn't a way to browse authenticated content. WebFetch has no session, no cookies, no login state — it sees exactly what an anonymous logged-out visitor sees. Anything behind a login wall is out of reach by design.
Security: Don't Let an Agent Guess URLs
The single most important operational rule for WebFetch is one every serious Claude Code setup enforces: never fetch a URL the agent invented on its own for anything beyond checking documentation directly relevant to the task at hand, and never fetch a URL constructed from user-controllable input without treating it as untrusted. Prompt injection via fetched page content is a real, demonstrated attack surface — a page can contain text instructing the agent to do something the user never asked for. Treat everything WebFetch returns as data, not instructions, and keep the tool scoped to URLs a human explicitly provided or that came from a trusted WebSearch result.
The Takeaway
WebFetch is the tool that keeps an agent's knowledge current instead of frozen at training time. Used well — WebSearch to find, WebFetch to read, healthy skepticism toward anything a fetched page tells the agent to do — it closes the single biggest gap between "knows a lot" and "knows what's actually true right now." Used carelessly — guessed URLs, blind trust in fetched content, ignoring the redirect trail — it's an attack surface. The tool doesn't decide which one you get. Your usage pattern does.