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
  a kind of source (`category="paper"` / `"finance"`, or a sub-group like
  `category="paper.biomed"` / `"finance.filings"`; see `engines()` for the
  full tree).
- Looking a fact up at its registry, with no category needed: a current
  version or support end date ("latest fastapi version"), a CVE
  ("CVE-2024-3094": NVD record, OSV advisories, CISA exploited status),
  a forecast ("上海明天天气"), an exchange rate ("100 usd to cny": ECB, and
  the PBOC parity for 人民币), a coin price, a country indicator ("china
  gdp", "japan population"), public holidays ("2026年放假安排"), the current
  time in a city, a domain's expiry, a company's legal entity, an iOS
  app's version, Wikidata facts ("Shanghai population"). The source that
  fits the words joins the search and its record arrives as the first
  result with the publisher's date in `dated …`, so it can be cited
  without a fetch. Name the thing plainly. `category=` ("software",
  "security", "weather", "finance.fx", "stats", "calendar", "reference",
  "docs", "gov") asks the same sources explicitly.

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`.
- Following one paper's references or citations -> use `paper_graph`.

Returns:
- markdown (default): numbered list of `n. title`, `<url>`, snippet. About 40%
  fewer tokens than json.
- json: dict with `results` (list of {title,url,snippet,engines,score}),
  `engines`, `cached`, optional `errors` map, optional `hint` string.
  `engines` is what was actually ASKED for this answer; each result's own
  `engines` is what found it. A default engine that failed recently is not
  asked and appears under `benched_engines` instead; a rescue pass that
  substituted a source appears as `rescued_via`.

Common mistakes:
- Answering from snippets. A snippet is an engine's summary of a page as it
  looked when crawled: it drops qualifiers and is often years old. Use
  `search` to find the URL, then read the page (`fetch`, `research`) for
  any date, amount, rule, deadline or number you will state.
- Treating a result as recent because `freshness=` was set. The filter keeps
  undated results; the header says how many could be dated (`dated: 3/10`)
  and each result is marked `dated …`, `… (from snippet text)` or `undated`.
- Passing a URL as `query`: that is `fetch`'s job.
- Cranking `max_results` up hoping for better recall; engines cap around
  10-20 each, anything beyond is duplicate noise (and 50 is the ceiling).
- Naming engines by default. The default pool is already the set that works
  keylessly over plain HTTP, it benches an engine that starts failing and
  seats a reserve when it gets thin, and naming engines switches all of
  that, and `category=` routing, off. Name engines when you want a
  specific index: `engines=["so360","baidu"]` for Chinese-language sites,
  `engines=["brave"]` or `["startpage"]` (both need the browser) for a
  second opinion.
- Using `category="news"` for breaking news without also setting
  `freshness="day"`: the index lags by days.

Args:
    query: Natural-language query (the same string a human would type).
    engines: Subset of `engines()`. None (recommended) = the health-aware
        default pool: duckduckgo, bing, anysearch and mojeek, plus
        googlenews when `freshness` is "day"/"week" and a Chinese index for
        a Chinese query.
    max_results: Merged result count after dedup, clamped to 1-50. It is
        also the PER-ENGINE budget, so it multiplies across the fan-out;
        5-20 is the useful range and anything past that is duplicate noise
        bought with real latency. Omit it for the configured default.
    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". Restricts 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: Which KIND of source to search. The enum lists every value.
        A bare group widens: "paper" adds one specialist per sub-group to the
        default web pool. A dotted sub-group narrows to just the sources that
        index it ("paper.biomed" => the biomedical indexes only). It also
        RERANKS: engines that natively index the category count double in
        the fusion, so the filing outranks the commentary about it, and a
        record looked up by the query (a PyPI release, a CVE, an ECB rate,
        a forecast) counts five times, so it leads the list. Call
        `engines()` for the group -> sub-group -> engine tree with a line on
        each source. Two behaviours worth knowing: "image"/"dataset" REPLACE
        the web pool rather than augment it (a web engine cannot return an
        image file), and "news"/"paper"/"forum"/"github"/"blog" also filter
        general-web hits by hostname, so a strict category can thin those
        engines out. The specialists it routes to are exempt.
    include_text: Substring required in title or snippet (case-insensitive).
    exclude_text: Substring forbidden in title or snippet.
    format: "markdown" (default) or "json".

Handles any http(s) resource, not just HTML:
- HTML pages -> reader-mode Markdown (nav/footer/scripts stripped).
- PDF/DOCX/XLSX/PPTX/EPUB/CSV/code/archives -> parsed text (same engine as
  `read_doc`, which you should prefer when you need pagination).
- Images, video, audio, fonts, opaque binaries -> a description
  (media type, byte size, dimensions, sha256), NOT the bytes.

Best for:
- You already have a URL (from `search`, the user, or your own knowledge)
  and need the actual page text.
- Verifying a single claim by reading the source.
- Checking what a resource IS before deciding to spend tokens on it.

Not recommended for:
- Multiple URLs at once -> use `fetch_batch` (concurrent, one round-trip).
- "Search then read top N" -> use `research` (one call, not two).
- Long documents you need to page through -> use `read_doc` (start/length).
- You don't have a URL yet -> use `search` first.

Returns:
- markdown (default): a small header (URL, render method, token count)
  plus the cleaned page body.
- json: {url, title, content, method, truncated, tokens_estimated,
  author, published_date, sitename}, plus {media_type, bytes_size, sha256,
  width, height} for non-text resources.
- With `inline=True` on an image: the image itself, viewable by a
  vision-capable model.

Common mistakes:
- Passing a search query instead of a URL.
- Using `render="http"` on a JS-only SPA: it returns near-empty content;
  use "auto" (default) or "browser".
- Setting `inline=True` on a large image out of habit. A 1MB image costs
  well over a thousand tokens; fetch it plainly first and inline only if
  the description says it's worth looking at.
- Forgetting that results are cached 7 days: use `force_refresh=True`
  or `max_age_hours=0` for a fresh pull. The header says `cached N days ago`
  when you are not looking at the live page; for deadlines, prices and
  anything else that moves, that is the cue to refresh.
- Reading `no publication date found` as "recent". It means unknown.

Args:
    url: Absolute http(s) URL.
    render: "auto" (try HTTP, fall back to stealth Chromium), "http"
        (fast, fails on JS), "browser" (slow, robust).
    force_refresh: Bypass the page cache entirely.
    max_age_hours: Treat cached pages older than this as a miss. 0 = same
        as force_refresh. None = server default TTL (7 days).
    inline: For images only. Returns the image itself instead of a
        description, so a vision-capable model can see it. Ignored for
        text resources.
    format: "markdown" or "json".

Best for:
- 2+ URLs you want to read in one round-trip.
- Reading the top N results of a previous `search` call.

Not recommended for:
- A single URL -> `fetch` (no list-wrapping overhead).
- "Search and then read" -> `research` collapses both into one tool call.
- PDFs/DOCX -> `read_doc` per file.

Returns:
- markdown (default): each page rendered as a Markdown section, separated
  by horizontal rules; failed URLs become inline error notes.
- json: list[dict], one entry per URL, with `error` set on failures.

Common mistakes:
- Passing a single URL inside a 1-element list: use `fetch` directly.
- Assuming an exception means the whole batch failed; check each item's
  `error` field instead.

Args:
    urls: List of absolute http(s) URLs (max 20 per call).
    render: Same as `fetch`.
    format: "markdown" or "json".

Best for:
- Remote PDFs and DOCX from an http(s) URL (parsed locally, no remote API).
- Local PDF/DOCX/text/Markdown files, ONLY when local reads are enabled
  (see Security below).
- Paginating through a long document via `start` / `length`.

Not recommended for:
- Arbitrary HTML web pages -> `fetch` does reader-mode cleanup that this
  tool does not.
- Pages discovered through search -> `fetch` or `research`.

Security (local files are sandboxed and OFF by default):
- Local-file reads are DISABLED unless the server operator sets the
  SEARCH_MCP_DOCUMENT_ROOT env var to a directory. With it unset, a local
  path raises a "local file reads are disabled" error. Pass an http(s)
  URL instead, or ask the operator to enable the sandbox.
- When enabled, `source` must resolve INSIDE that root; relative paths
  resolve against the root (not the process CWD) and any `..` traversal
  that escapes the root is rejected. `file://` URLs are always rejected.
- Remote http(s) sources are unaffected by this setting.

Returns:
- markdown (default): rendered document text with a small header.
- json: {content, title, format, total_chars, start, returned_chars,
  truncated}. Use `total_chars` and `returned_chars` to drive pagination.

Common mistakes:
- Calling this on a normal article URL: you'll get raw HTML noise. Use
  `fetch` instead.
- Forgetting to advance `start` when paginating: next call should pass
  `start = previous_start + returned_chars`.
- Passing a negative `length` (raises an error) or a `start` past the end
  (clamped to EOF: you'll get `returned_chars == 0`, `start == total_chars`,
  and `truncated == False`, which is the signal you've paged off the end).

Args:
    source: http(s) URL, or a local path UNDER SEARCH_MCP_DOCUMENT_ROOT when
        local reads are enabled (disabled by default; see Security).
    start: Character offset to begin reading from. Default 0. Clamped into
        [0, total_chars]; a negative value is treated as 0.
    length: Max characters to return; None = read to end (still capped by
        the per-call max content size). Must be >= 0. A negative length
        is rejected with a ValueError.
    format: "markdown" or "json".

Best for:
- Open-ended questions that need finding sources AND reading them
  ("what's new with X", "summarize the controversy around Y").
- Replacing a `search` + N x `fetch` chain with one call.
- Producing a citable brief with [n]-style source references.

Not recommended for:
- You only need links -> `search` (cheaper, no fetching).
- You only need to read one URL you already have -> `fetch`.
- You want to query previously-fetched cached pages -> `cache_search`.
- Checking or expanding one paper's citations -> `paper_graph`.

Returns:
- markdown (default): a "Research brief" with a Sources index then the
  full Markdown body of each fetched document, separated by horizontal
  rules; includes a token estimate.
- json: {question, engines, sources:[{rank,title,url,snippet,...}],
  documents:[...], tokens_estimated, errors}.

Common mistakes:
- Using `depth=8` for a quick lookup: that's 8 page fetches, and 2-3 is
  almost always enough.
- Calling `research` for a known URL: that is what `fetch` is for.
- Forgetting that `fetch=False` returns sources only (much cheaper if
  the LLM only needs to pick which one to read).

Args:
    question: What you want to know, in natural language.
    depth: How many top results to fetch (1-8). 3 is a good default.
    engines: Override the engine set (see `engines()` for names). Prefer
        `category=`. Naming engines turns category routing off.
    fetch: If False, return source list without reading them.
    freshness: "day"|"week"|"month"|"year". Restricts to recent results.
        Best-effort; undated results are kept rather than dropped.
    include_domains: Restrict to these domains (e.g. ["python.org"]).
    exclude_domains: Drop results from these domains.
    category: Which KIND of source to search; a bare group widens, a dotted
        sub-group narrows. Same values as `search`; see `engines()`.
    include_text: Substring required in title or snippet (case-insensitive).
    exclude_text: Substring forbidden in title or snippet.
    use_cache: Reuse cached search/page data within TTL.
    max_age_hours: Treat cached search results AND cached page bodies older
        than this as a read miss; fresh data is always written back. 0 =
        force-refresh both the engine search and every fetched page body;
        None = server default TTL (7 days). A non-zero value is honored for
        both halves (it used to be ignored for anything but 0).
    format: "markdown" or "json".

`search` finds papers that MENTION your words. This follows the edges
instead: what a specific paper built on, and what has built on it since.

Best for:
- Checking a citation before repeating it: is the DOI real, and has the
  paper been retracted or corrected?
- "What happened after this result": citing works come back ordered by how
  much the field cited them, so a 2019 paper leads to the current state of
  the art rather than to the most recent preprint about it.
- Building a reading list backwards from one good paper.

Not recommended for:
- Finding papers by topic -> `search(category="paper")`, or a sub-group
  like `"paper.biomed"` / `"paper.cs"` / `"paper.preprint"`.
- Reading the paper itself -> `read_doc` on the returned URL.

Returns:
- markdown (default): the paper with its retraction/correction notices,
  then "References" and "Cited by" sections.
- json: {paper, references, citations, notes}, where `paper.crossref`
  carries `registered` and every post-publication `notices` entry.

Common mistakes:
- Passing a topic instead of a paper. A title resolves to its single best
  match; a phrase that names no specific paper resolves to the wrong one.
- Reading an empty `citations` list as "uncited" when `notes` says the
  lookup was truncated.

Args:
    paper: DOI (`10.1145/1571941.1572114`, or a doi.org URL), an OpenAlex
        ID (`W2148972377`), or the paper's exact title.
    direction: "both", "references" (what it cites) or "citations" (what
        cites it).
    limit: Max neighbours per direction, 1-50.
    format: "markdown" or "json".

Best for:
- Recalling something the user/agent fetched earlier in the conversation
  ("what did that Wikipedia page say about X").
- Avoiding re-fetching content already in the local cache.
- Quick keyword grep across the corpus you've built up.

Not recommended for:
- Discovering new pages on the open web -> use `search` or `research`.
- When the cache is empty (fresh install) -> `search`/`research` first to
  populate it.

Returns:
- markdown (default): a per-hit list of title, URL, and a `[bracket]`-
  highlighted snippet around the matched terms.
- json: list of {url, title, snippet, author, date, sitename}. The last
  three are "" when the cached row predates metadata capture.

Common mistakes:
- Treating this like web search: it ONLY hits pages already in the local
  cache. If the user hasn't fetched anything, you'll get zero hits.
- Using natural-language phrases without quoting them; FTS5 splits on
  whitespace as AND. For an exact phrase use `"like this"`.

Args:
    query: FTS5 query. Bare terms = AND. Supports OR / NOT, prefix
        (`term*`), and phrase (`"exact phrase"`).
    limit: Max hits to return.
    format: "markdown" or "json".

Best for:
- Choosing a source deliberately: which one indexes filings, or preprints,
  or Chinese-language pages.
- Checking a name before passing it to `engines=` on `search` / `research`.

Not recommended for:
- Calling on every search: the list is static, so read it once.

Returns (markdown): a `group -> sub-group -> engine` tree, one line of
description per engine. `group="paper"` restricts it to that group.
Returns (json): `{"engines": [...names...], "taxonomy": {...},
"descriptions": {...}}`.

Prefer `category=` over `engines=`. `category="paper"` WIDENS: it routes to
one specialist per sub-group. A dotted sub-group NARROWS: `"paper.biomed"`
queries only the biomedical indexes. Naming engines explicitly turns that
routing off entirely, so reach for it only to force a specific source.

Common mistakes:
- Passing one of these names as `query`: they belong in `engines=`.
- Passing a key-only engine with no key configured; it returns an
  actionable error, not results.

Best for:
- Side-by-side product/feature/article comparisons.
- "Compare X to Y" or "How does A differ from B" queries.
- Triangulating a fact across multiple sources.

Not recommended for:
- >5 URLs -> use `fetch_batch`.
- 1 URL -> use `fetch`.
- Don't have URLs yet -> use `search` or `research` first.

Returns:
- markdown (default): a comparison brief with per-URL sections, each
  containing title, sitename, published date, and a smart-truncated excerpt.
- json: {question, urls, excerpts:[{url, title, excerpt, ...}],
  tokens_estimated}.

Common mistakes:
- Asking `compare` to actually answer the question: it returns material,
  the LLM does the comparison.
- Passing >5 URLs and expecting them all to fit in context: use
  `fetch_batch` for bulk reads.

Args:
    question: The comparison question the LLM will answer using the
        returned excerpts.
    urls: 2-5 absolute http(s) URLs.
    format: "markdown" (default) or "json".

Best for:
- Product pages (price, currency, availability, brand, rating).
- Article pages (author, publish date, image, headline).
- Recipe / event / video pages where rich metadata IS the answer.
- Cases where `fetch` returns prose but you need fields.

Not recommended for:
- Just reading a page -> use `fetch`.
- PDFs / DOCX -> use `read_doc`.
- Pages that don't publish schema.org metadata (most blogs): you'll get
  empty lists; fall back to `fetch`.

Returns:
- json: {url, json_ld:[], microdata:[], opengraph:[], rdfa:[]}. Twitter
  card meta tags are surfaced inside the `opengraph` list.
- markdown (default): a flattened key/value view with each block printed
  as a JSON code block under its syntax heading.

Common mistakes:
- Calling on every URL "just in case": most sites have no structured
  data, and `fetch` is what you actually want.

Args:
    url: Absolute http(s) URL.
    format: "markdown" (default) or "json".

Downloads are enabled by default and saved under
`SEARCH_MCP_CACHE_DIR/downloads`. Set `SEARCH_MCP_DOWNLOAD_ENABLED=false`
to disable them or `SEARCH_MCP_DOWNLOAD_DIR` to override the destination.

Best for:
- Keeping an actual file (installer, dataset, archive, image) rather than
  its text.
- Handing a path to another tool that needs a real file on disk.

Not recommended for:
- Reading a document's contents -> use `read_doc`, which parses it without
  touching the filesystem.
- Looking at a web page -> use `fetch`.
- Viewing an image -> use `fetch(inline=True)`.

Returns:
- markdown (default): where the file was saved, its size and type.
- json: {url, saved_path, media_type, bytes_size, sha256, expires_in_hours}.
  An expires_in_hours value of 0 means TTL cleanup is disabled.

Retention: files older than SEARCH_MCP_DOWNLOAD_TTL_HOURS (default 24) are
deleted before the next download and at startup. A value of 0 disables TTL
cleanup. Otherwise, treat the path as short-lived and copy it elsewhere if
you need to keep it.

Args:
    url: Absolute http(s) URL of the file to save.
    format: "markdown" or "json".