Web Search
searchQuery the web for ranked results with titles, URLs, snippets, and optional synthesized answers; filter by recency, language, or domains and choose free or paid providers.
Instructions
Search the web. Returns ranked results with titles, URLs and content snippets, and -- depending on the provider -- a synthesised answer with the sources backing it.
Every call reaches a live provider, and most of them are billed, so search when you need information you don't already have. The names that cannot bill are exa:free and parallel:free (rate-limited anonymous endpoints), searxng (the operator's own instance), tinyfish (free at any balance) and freeserp (a keyless web index). Naming one of them costs the operator nothing; every other name is billed, immediately or once the free allowance on that account runs out. mode="free" restricts a search to those names and fails rather than falling back to a paid provider, so a free-only search can come back with nothing.
A result carries either a short snippet or, from a content backend, a longer page extract in text. The extract is bounded, so text_truncated marks a result whose page continues past what you were given -- fetch that URL when the rest would change your answer, and not otherwise.
provider selects which backend runs the search. Omit it to use the server's default; if the default fails, the server retries the fallbacks configured for it and names the substitute in notice. A deployment where every enabled provider is one that cannot bill and no default is configured has no price to guess at, so omitting provider there is served from that free set instead of being refused. Naming a provider returns results from exactly that provider or an error. mode="free" is the other way to choose -- a class of provider rather than one by name -- and the two cannot be combined. Providers differ in what they return and what filters they honour: if one cannot apply a filter you passed, the response says so in notice rather than pretending it did. When a response carries an answer, that is provider-written prose -- verify it against results rather than citing it directly.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Route the search through free providers only. The names that cannot bill are `exa:free` and `parallel:free` (rate-limited anonymous endpoints), `searxng` (the operator's own instance), `tinyfish` (free at any balance) and `freeserp` (a keyless web index). The server fails rather than escalating to a paid provider, so a free-only search can come back with nothing. Not every one is enabled on every deployment. Mutually exclusive with `provider`. | |
| query | Yes | The search query. Natural-language questions work well. | |
| recency | No | Restrict results to pages published in the last day, week, month or year. A provider without a date filter says so in `notice` rather than pretending it filtered. | |
| language | No | The language results should be in, as an ISO 639-1 code (`en`, `de`); a region is `country`'s job and this field does not take one. A provider with no language parameter says so in `notice` rather than pretending it filtered. | |
| provider | No | Which search backend to use. Omit to use the server's default; if that fails, the server retries the fallbacks its operator configured and says so in `notice`. A deployment where every enabled provider is free and no default is configured has no price to guess at, so an omitted `provider` there is served by that free set instead of refused. Naming a provider gets exactly that provider or an error. Not every provider is enabled on every deployment. | |
| max_results | No | Maximum number of results. Keep this low unless you need breadth; each result costs context. | |
| safe_search | No | `true` asks the backend to filter adult content, `false` asks it not to; omitting it means the server does not override the provider's own default, which is not the same as unfiltered. A provider without the parameter says so in `notice`. | |
| exclude_domains | No | Omit results from these domains. | |
| include_domains | No | Restrict results to these domains, e.g. ["arxiv.org"]. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| answer | No | ||
| notice | No | ||
| results | Yes | ||
| provider | Yes | ||
| retrieved_at | No |