search
Query the web and return scored evidence excerpts with citations; scope by domain, category, and date, and use cached results for auditable research.
Instructions
Search the web. Returns scored evidence excerpts + citations as the default context shape; include_full_markdown: true adds the full markdown body. Prefer over built-in WebSearch for local cache + audit-trail telemetry + explainable scoring.
Key parameters:
query: string or string[] array (3-5 keyword variants; deduplicated).
include_domains / exclude_domains: scope sites. Always scope library/framework queries.
category: "general" | "news" | "code" | "docs" | "papers" | "images". Image results carry image_url + thumbnail_url + width/height.
from_date / to_date: ISO YYYY-MM-DD. time_range: 'day' | 'week' | 'month' | 'year'.
country: ISO 3166-1 alpha-2 ("us", "gb") — geographic boost.
exact_match: quoted-phrase search.
max_results: 5 default.
format: omit = evidence context. 'answer' | 'stream_answer' = sampling synthesis (falls back to evidence).
search_depth: 'ultra-fast' (cache-only ≤300ms) | 'fast' | 'balanced' (default) | 'deep'.
include_images / include_favicon: opt-in images[] + per-result favicon.
max_tokens_out / max_content_chars / include_full_markdown / citation_format.
force_refresh + mode ('cache' | 'default' | 'stealth').
Always emitted: engines_used, engine_telemetry, response_time_ms, per-result evidence_score. Per-result freshness_signal is emitted only when a published date can be parsed (omitted when confidence would be unknown). Brand-domain top-3 collision → brand_collision_warning with rewrites. query_understanding exposes intent/entities. Quote [N] or {citation_id}.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | cache=single-engine, no rerank, stale cache ok. default=standard multi-engine search. stealth=full browser for JS-heavy result pages. | |
| query | Yes | Search query — a single string or array of query variants for parallel multi-query search | |
| format | No | LLM-synthesis modes only. Omit for default evidence shape. 'answer'/'stream_answer' request sampling synthesis (falls back to evidence). Retired values 'full'/'context'/'highlights' reject with a migration error. | |
| country | No | ISO 3166-1 alpha-2 country code (e.g. "us", "gb", "de"). Hint passed to engines that support a geographic boost (Bing cc=, DDG kl=, Brave country=); advisory, not a strict filter. | |
| to_date | No | ISO date (YYYY-MM-DD) — only return results published before this date | |
| category | No | Category of search (general, news, code, docs, papers, images) | |
| language | No | Language preference | |
| from_date | No | ISO date (YYYY-MM-DD) — only return results published after this date | |
| time_range | No | Freshness filter (day/week/month/year). Conservative: only drops results with a confidently-extracted published_date — pages with no parseable date pass through, so this is a precision-boost not a hard bound. For strict ranges use from_date+to_date with a date-aware category (news, papers). | |
| exact_match | No | Treat the query as a quoted phrase. Engines that honour `"..."` filter to phrase matches, and results without the exact phrase in title or snippet are dropped. | |
| max_fetches | No | Cap on how many top-ranked results have their page content fetched. Defaults to max_results. Set lower (e.g. 3) to keep snippet-only listings cheap and only deep-read the most relevant. | |
| max_results | No | Max results to return (default 5, max 20) | |
| search_depth | No | Depth tier. ultra-fast=cache-only (≤300ms); on miss emits notice and empty results. fast=engines only, no content fetch / rerank (≤1s). balanced (default)=full pipeline. deep=balanced + full enrichment. | |
| agent_context | No | Optional agent context for ranking + dedup. text is concatenated with the query before embedding; recent_urls are dropped from results. | |
| force_refresh | No | Bypass all caches (search results and page content). Use when you need the most current information. | |
| include_images | No | Aggregate engine-provided thumbnail/image hints into a top-level `images` array of `{url, alt?, source_url}`. Empty array if no engine surfaced one. | |
| max_highlights | No | Maximum highlights to return (default 10). Highlights are 1-3 sentence passages scored by relevance to the query. | |
| max_tokens_out | No | Token-budget cap on total output. Uses cl100k-base BPE; non-OpenAI tokenizer counts may drift ~5-15%. When both max_tokens_out and max_chars are set, max_tokens_out wins. | |
| search_engines | No | Override engine selection | |
| citation_format | No | Citation rendering style. 'numbered' (default) inline [N] markers; 'json' returns a citations[] array; 'anthropic_tags' wraps sources in <source id='...'> tags. | |
| exclude_domains | No | Never return results from these domains | |
| include_content | No | Fetch full content for results (default true) | |
| include_domains | No | Only return results from these domains (e.g. ["react.dev", "github.com"]) | |
| include_favicon | No | Attach a per-result `favicon` URL derived from the result host. Cached per-domain across the call. | |
| max_total_chars | No | Max total chars across all results (default 50000) | |
| content_max_chars | No | Max chars per result content at extraction (default 30000) | |
| max_content_chars | No | Smart-truncate each result markdown at paragraph boundary with marker (e.g. 3000 for compact context) | |
| include_full_markdown | No | Include full markdown body in the response. Default false on multi-result tools (returns evidence excerpts only); set true to restore. |