web_search

Search the web via Exa or Tavily. Returns one block per result, each with its OWN title, URL, highlights, and text — never a merged summary — plus a Sources trailer. In clients with built-in web search, use this as an independent complementary retrieval lane; when built-in search is disabled or unavailable, use it as the primary search path.

Args: query: the search query. num_results: how many results (default 8). mode: search mode — "auto" (default), "fast" (~450ms), "instant" (~250ms), or the deep-research family "deep-lite" (≈4s), "deep" ($12/1k), or "deep-reasoning" (12–40s, $15/1k). Deep modes request a synthesized answer via Exa's outputSchema and return a "## Synthesized answer" block — with a "Grounding:" citation line when Exa returns one — plus per-result blocks; this costs ~2s of synthesis latency on top of the mode's own search time, which is why it is scoped to the deep family only (their timeout budget already covers it). Legacy "neural"/"keyword" map to "auto" (deprecated). text_chars: per-result body length (default 1200; clamped 200–8000). Now governs BOTH the Exa request size (request-what-you-render) and the rendered cap — raise it to surface more body text per result. recency_days: only results published within the last N days (maps to startPublishedDate). Pass this for time-sensitive/"latest" queries — the tool does NOT auto-tighten dates on its own. recency_hours: like recency_days but HOUR granularity — reaches BOTH tiers (Exa via a full ISO timestamp; the Firecrawl fallback via tbs qdr:h/cdr:1,cd_min:…). Full precedence ladder, same on both tiers: explicit VALID start_published_date > recency_hours > recency_days. An invalid/absent value at each tier falls through to the next. start_published_date / end_published_date: ISO date bounds ("2026-01-15" or a full ISO timestamp). Wins over recency_hours/recency_days per the ladder above on both tiers. The fallback represents an explicit start with Firecrawl's custom-date-range syntax. Unparseable values are ignored (stderr note), never an error. category: Exa category hint ("news", "publication", "company", "people", "financial report", "personal site", or a free string). NOTE: "company" and "people" forbid date filters + excludeDomains (dropped automatically), and "people" restricts includeDomains to Exa's supported profile domains (it 400s otherwise — surfaced as SEARCH_FAILED / fallback). Enum migration: "research paper" was RENAMED to "publication" and is auto-aliased forward; "tweet" is GONE (Exa 400s) and is dropped, leaving the search unscoped; "pdf"/"github" are deprecated-but-live and pass through. Each of those emits a [category=… ] line in the response header, since dropping or renaming a category changes which results you get back. include_domains / exclude_domains: restrict/exclude result hosts (capped at 20 entries each). summary: when True, request a generated per-result summary instead of raw text/highlights (fewer tokens; text + highlights omitted from the request). sort_by_date: sort results by publish date instead of relevance. Honoured ONLY on the Firecrawl fallback tier (Firecrawl's sbd:1); Exa has no equivalent — when the Exa tier serves and this was requested, the response header discloses that it was not applied rather than silently ignoring it. provider: "exa" or "tavily". When omitted, WEB_SEARCH_PROVIDER is used, defaulting to Exa. Invalid values fail explicitly. Tavily requires the tavily extra and TAVILY_API_KEY.