Web search (multi-engine, no API key)
searchRead-only
Perform multi-engine web searches to get ranked, deduplicated link lists, ideal for discovery queries and supplying URLs for subsequent fetch operations.
Instructions
Run a multi-engine web search and return a ranked, deduplicated link list.
Best for:
- Discovery queries ("what is X", "find me X", "who is X").
- Getting a list of URLs you can hand to `fetch` / `fetch_batch` next.
- Topics likely to be after your knowledge cutoff (use `freshness="week"`).
- Filtering to specific domains (`include_domains=["python.org"]`) or
content types (`category="paper"|"pdf"|"github"|"news"|"forum"|"blog"`).
Not recommended for:
- You already know the URL -> use `fetch` instead.
- You want both links AND their full text in one call -> use `research`.
- You want to query pages already in the local cache -> use `cache_search`.
- Reading PDFs/DOCX from a known URL -> use `read_doc`.
Returns:
- markdown (default): numbered list of `n. title`, `<url>`, snippet — ~40%
fewer tokens than json.
- json: dict with `results` (list of {title,url,snippet,engines,score}),
`engines`, `cached`, optional `errors` map, optional `hint` string.
Common mistakes:
- Passing a URL as `query` — that's `fetch`'s job.
- Cranking `max_results` to 50 hoping for better recall; engines cap around
10-20 each, anything beyond is duplicate noise.
- Adding `engines=["startpage","brave","bing","baidu"]` by default — those
need browser rendering or captcha-friendly conditions; stick with the
defaults unless they returned 0. If the defaults DO return 0, the keyless
HTTP extras `engines=["google"]` or `engines=["anysearch"]` (no key, no
browser) are the best recovery before reaching for the browser-gated ones.
- Using `category="news"` for breaking news without also setting
`freshness="day"` — the index lag is days, not minutes.
Args:
query: Natural-language query (the same string a human would type).
engines: Subset of `engines()`. None = duckduckgo+mojeek+googlenews+bing.
(startpage is opt-in and browser-rendered.)
max_results: Merged result count after dedup. 5-20 is the useful range.
use_cache: Reuse the last result for this exact (query, engines,
max_results, AND all active filters — freshness, include/exclude
domains, category, include/exclude text) within the cache TTL.
Changing any filter is a different cache entry. False forces a
re-fetch.
max_age_hours: Treat cached results older than this as a read miss; a
fresh result is ALWAYS written back to the cache regardless of this
value, so caching is never disabled. Use 0 to force-refresh while
keeping cache writes; None = use server default TTL (7 days).
freshness: "day"|"week"|"month"|"year" — restrict to recent results.
Best-effort: applied as an engine time-window param AND a client-side
date check, but most HTML-engine results carry no parseable date, so
undated results are kept rather than dropped (unknown != old). Treat
it as a strong hint, not a hard filter; googlenews dates are exact.
include_domains: List of domains to restrict to (e.g. ["python.org"]).
exclude_domains: List of domains to exclude.
category: "news"|"pdf"|"github"|"paper"|"forum"|"blog" — content-type
shortcut. "paper" => arxiv/acm/springer/ieee/etc; "forum" =>
reddit/HN/stackexchange; "github" => code forges (github/gitlab/
codeberg/bitbucket/sourceforge/...). "news" keeps only ~33 major
outlets (client-side whitelist), so most DDG/Mojeek hits are dropped
— pair it with the default engines (googlenews is auto-added) and
note googlenews URLs resolve to the publisher on fetch/research.
include_text: Substring required in title or snippet (case-insensitive).
exclude_text: Substring forbidden in title or snippet.
format: "markdown" (default) or "json".
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| format | No | markdown | |
| engines | No | ||
| category | No | ||
| freshness | No | ||
| use_cache | No | ||
| max_results | No | ||
| exclude_text | No | ||
| include_text | No | ||
| max_age_hours | No | ||
| exclude_domains | No | ||
| include_domains | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |