web_search
Search the web to retrieve URLs and metadata snippets without loading full page content. Supports domain-restricted searches via lenses and site filters.
Instructions
Search the web for URLs and metadata without fetching page content. Returns JSON with fields: urls (string array), results (array of {title, url, snippet, displayLink}), query, resultCount. lens and site are mutually exclusive (lens overrides site if both provided). On no matches returns resultCount: 0 with empty results array; on failure returns isError with message. Subject to per-tenant rate limit (default 30 req/min) with automatic provider fallback and circuit breaker recovery. Supports lenses (programming, news, tech, legal, medical, finance, science, government) for domain-restricted search. Use search_and_scrape instead when you need full page content; use news_search for time-sensitive current events; use academic_search for scholarly papers. Results cached 30 min; use time_range to constrain freshness when cache staleness is a concern.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The search query text (1-500 chars). Be specific with key terms and qualifiers for better results.,required | |
| num_results | No | Number of results to return (1-10). Default: 5. Higher values increase latency. | |
| time_range | No | Restrict to a time period: day, week, month, or year. Omit for all-time results. | |
| safe | No | SafeSearch level: off, medium (default), or high. | |
| language | No | Filter by language using ISO 639-1 code (e.g. en, fr, de). | |
| site | No | Restrict to a single domain (e.g. stackoverflow.com). Cannot combine with lens. | |
| exact_terms | No | Phrase that must appear verbatim in results. | |
| exclude_terms | No | Terms to exclude from results (space-separated). | |
| country | No | Restrict to a country using ISO 3166-1 alpha-2 code (e.g. US, GB). | |
| lens | No | Apply a curated domain-restricted search lens: programming, news, tech, legal, medical, finance, science, government. Overrides site parameter. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | ||
| resultCount | No | ||
| results | No | ||
| urls | No |