Skip to content

Search the web

Canonical tool: occam_search

Open-web search (query → result URLs). Default when OCCAM_SEARCH_PROVIDER is unset: keyless DuckDuckGo HTML SERP with provider: "duckduckgo" disclosed in the response. Occam does not index the web — it delegates discovery and names the source.

Override with OCCAM_SEARCH_PROVIDER=searxng | brave | tavily | donsetch (plus URL/key/binary as required), or off / none for the air-gap search_unconfigured contract. See configuration.

When to use

  • No URLs yet → search, then feed handle or url into probe / transcode / digest.
  • Each hit includes id (S1…Sn, latest-search shorthand) and handle (H…, durable in this MCP process for 60 minutes / 64 entries). A later search remaps S1 — keep handle or the raw url to retain a hit.
  • Discovering pages within one known site → occam_map is cheaper.
  • rerank=true probes every hit and reorders so clean, HTTP-extractable pages rank above paywalls/anti-bot walls/JS stubs — worth the extra latency when you will transcode the winners.

Parameters

Parameter Type Default Required Description
query string — yes Search query
max_results int 8 no 1–20
rerank bool false no Probe each hit and sort by extractability; adds extractability (0–1) + recommendedBackend per result. Extra probe latency

Returns

Success envelope:

  • ok: true, query, provider, count
  • results[] — {id, handle, title, url, snippet?}; with rerank=true also extractability and recommendedBackend (a hit whose probe failed keeps a mid-low score and no backend annotation)
  • handleTtlS (3600) and handleScope (process) — once per success envelope
  • agentHints.suggestedNext — pass handle or url; S1 is the latest search only

Failure envelope: ok: false, query, failure: {code, message}.

Failure codes

invalid_arguments, search_unconfigured (provider off / incomplete explicit config), search_timeout (retry or raise OCCAM_SEARCH_TIMEOUT_MS), search_http_<status>, search_error (empty/blocked SERP or parse miss). See failure codes.

Example

Call (no env required after install):

{ "query": "nginx rate limiting configuration", "max_results": 5 }

Trimmed response:

{
  "ok": true,
  "query": "nginx rate limiting configuration",
  "provider": "duckduckgo",
  "count": 5,
  "results": [
    { "id": "S1", "handle": "H00000001", "title": "Rate Limiting with NGINX", "url": "https://blog.nginx.org/…", "snippet": "…" }
  ],
  "handleTtlS": 3600,
  "handleScope": "process",
  "agentHints": { "suggestedNext": "Pass result.handle or url to occam_transcode…" }
}