Web search

The agent's knowledge of a library ends where its training did, and the two questions it cannot otherwise answer — what does this error message mean, and what is this API called now — are the ones a search box answers in seconds. The wizard's fourth question decides whether it gets one, and the honest default is no: every other capability here stays inside the working tree, and a search query is written by the model out of whatever the model has read.

web_search	What it does	What it costs you
none	nothing; the tools are not registered and the model is never told they exist	—
claude	declares Anthropic's hosted web_search_20250305 tool, which runs on their side of the wire	billed per search by Anthropic; needs an endpoint that offers it
custom	registers web_search and web_fetch, which run here	a search command on your PATH

claude is a line in the request's tool array and nothing else — no install, no key, no HTML parsing. The searches come back as server_tool_use and web_search_tool_result blocks, which the loop turns into ordinary WebSearch(...) transcript entries so a search is something you can watch rather than a pause you have to guess at. A hosted search cannot be refused at the prompt, because it happens inside a request you already approved; the setting itself is the consent. It also needs the endpoint to implement it, so a gateway or a local server speaking the Messages API will generally refuse the whole request — if that happens, switch to custom.

custom runs a command. The default is

ddgs text -q {{query}} -m {{count}} -nc

which needs the DuckDuckGo CLI (pipx install ddgs) and no account at all. {{query}} and {{count}} are substituted as whole argv elements and the command is run without a shell, so a query containing ; or backticks is a query rather than a second command.

Note the absence of -o json, which is the flag you would reach for and the wrong one: it does not print JSON, it writes a file — into whatever directory the agent happens to be working in, once per search. The plain listing goes to stdout and is parsed, and -nc keeps the colour codes out of the titles.

Any tool will do, as long as it prints to stdout: a JSON array, one JSON object per line, a {"results": […]} wrapper, or ddgs's own aligned listing are all read. Titles may be title; links href, url or link; snippets body, snippet, description or abstract. Edit the command in the wizard, or set search_command in the config.

web_fetch is the other half, because a snippet is enough to choose a link and never enough to write code against. It resolves the host and refuses loopback, private, link-local and unique-local addresses, on the original URL and on every redirect hop — the model invents these URLs, and 169.254.169.254 is a cloud metadata endpoint. Pages come back as text, capped head and tail like bash output, wrapped in markers that say to treat what is between them as data rather than instructions. That does not make prompt injection impossible; it makes it visible in the transcript, which is the most a fetch tool can honestly offer.

Both tools prompt, and neither is in the read-only set: they read nothing local and send the model's words off the machine, which is the opposite of what that set is for. The query and the URL are the detail on the prompt, so what is leaving is on screen before it leaves. "Always this tool" is the answer most people give once.