search

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".