Web search

Mercury offers web search through two tools under one provider-neutral contract: the provider's own live search, and Mercury's vendored WebSearch. Any session model can search, a local model included, and every result is plain hit groups of title, URL and snippet that every model can read.

Search tools

ProviderSearch: The provider's own live search. It is listed exactly when the session's main model belongs to a provider whose native search construct Mercury speaks, Anthropic or OpenAI, and it runs inside a provider-side call on the session's own account. A failure is one typed line naming WebSearch as the alternative.
WebSearch: Mercury's vendored search, for every session. Mercury picks only its backend, and it never spends a provider account.
WebFetch: Fetches a URL under Mercury's own URL validation and the hostname-scoped permission gate. It asks no policy service before a fetch, on any provider.

Where both search tools are listed, the model chooses per query. Mercury never forces one, never hides the other, and never falls through silently from the provider's search to WebSearch.

WebSearch backends

Brave Search: A keyed backend, tried first when its key is configured.
Tavily: A keyed backend, tried after Brave when its key is configured.
DuckDuckGo: The keyless backend, used when no keyed backend is available. Its no-JavaScript endpoints, html and then lite, are form-posted under a stable agent string that discloses nothing, with no cookies and one deadline each.

The keyless backend works the moment Mercury is installed, with no account anywhere. The first keyless answer of a session carries a hint about the keyed backends once, both of which offer a free tier, and no later result repeats it.

Configure a search key

To configure a search key, follow these steps:

Enter /router key brave or /router key tavily.

Mercury stores the key auth-scoped, with file mode 600, in the engines' secret store.

Environment pins win over stored keys:

BRAVE_API_KEY: The Brave Search key.
TAVILY_API_KEY: The Tavily key.

Both variables are filtered from evaluation kernels, as every credential is.

Select a search backend

To select a search backend, follow these steps:

Set MERCURY_SEARCH_BACKEND to auto, brave, tavily or duckduckgo in the session's environment.

WebSearch uses the named backend, and a named backend that cannot open is a typed refusal, never a silent fallback.

MERCURY_SEARCH_KEYLESS=0 closes the keyless backend, as an egress posture.

Result and failure information

Every result carries via: the transcript row and the model-facing result both say which backend answered. A backend that failed on the way leaves one line as a note.

Failures are typed values rendered as one line: rate-limited, parse-failed, no-backend, network, key-refused and provider-refused. A changed page or body shape is parse-failed, never a guessed hit.

A rate limit is a wait, not a wall. A backend that throttles or challenges the client, with a 202 challenge page or a 429 or 503 status, is retried once after a short jittered back-off, then cools down for 30 seconds, doubling per repeat and capped at ten minutes, and is not asked again inside its window. A query that already landed answers from the session's cache for ten minutes and says so.

When every backend refused, the model gets one line naming what refused, the cool-down left, the key commands and, where the provider has one, ProviderSearch. The AUTH section of /health states the facts of both tools for the session's model.

A keyless home searches and fetches with zero first-party requests and zero model calls. A prompted fetch's extraction is the one model call, and it rides the session's own provider, never a first-party hop.