USE THIS when the needed source or URL is not yet known, when you need a new
independent source, or when search-engine discovery itself is required.
DO NOT search again merely to find another page inside a strong source when
that page is likely linked from the current page; use web_links instead.

Domain filtering example: web_search(query="asyncio", domain="python.org",
exclude_domains=["discuss.python.org"], max_results=20). Domain operators
depend on the provider. Search pagination is not supported.

Results are candidates, not verified page evidence: snippet is a search-engine
preview and result.url has not been fetched. For a candidate:
- web_links(url=result.url): inspect chapters, pagination, references or related
  pages exposed by that source without crawling them;
- web_fetch(url=result.url, max_chars=500): preview/read the selected document;
- research_collect(urls=[...]): collect bounded evidence from selected URLs.

Returns results, query_used, unresponsive_engines and cached. Always inspect
unresponsive_engines: nonempty means incomplete search coverage. Expected
failures return {error, hint}.

USE THIS when you already know which document you want to read, preview, or
expand around a collected excerpt. If you know the source but need to find
its chapter, appendix, next page, reference, or related document first, use web_links instead.
If you do not yet know a source, use web_search.

Preview with max_chars=500 to limit model context; this does not reduce the
initial network download. When more retained text is useful, copy
continuation.arguments into the indicated tool rather than recalculating the
next offset. Null continuation means the retained text has ended.

continuation and excerpt.expand use expected_content_hash. If the retained
text version changed, content_changed returns no slice: reacquire the document
and choose coordinates again. A matching hash protects coordinates, not
origin freshness.

A page can have too little readable text for web_fetch while still exposing
useful ordinary HTML links through web_links; treat such pages as possible
navigation hubs instead of assuming the source has no usable structure.

Returns content, title, final URL, source category, Unicode-coordinate paging,
cache/hash fields and continuation. truncated means more retained text can be
continued; text_truncated means a tail was discarded by the hard retention
ceiling and cannot be recovered by pagination. Expected failures return
{error, hint}.

USE THIS when you already found a useful source but need its structure:
documentation sections, report chapters, table-of-contents entries,
next/previous publication pages, appendices, references, datasets, standards,
or related pages. It is the bridge between web_search discovery and web_fetch reading.
Prefer this over another search when the desired page is plausibly
linked from the source you already have.

This is NOT a crawler or browser. It inspects ordinary <a href> links in this
one fetched HTML page only. It does not follow them, click controls, execute
JavaScript, submit forms, DNS-resolve destinations, or safety-approve them.
Selecting a returned URL for web_fetch/web_links later triggers the normal
outbound SSRF policy.

same_origin=true keeps only links with the same scheme, normalized hostname
and effective port as the final fetched page. Leave same_origin=null when
external citations or primary sources may matter; same origin does not mean
same organization, and cross-origin does not mean untrusted.

The retained list preserves document order after deterministic URL
deduplication. Fragments remain part of link identity. same_document=true
means only that the destination has the same document identity ignoring the
fragment; web_fetch still navigates text by Unicode offsets, not HTML anchors.

Filtering happens BEFORE pagination. Copy continuation.arguments to retrieve
the next retained link page. links_hash versions the whole retained ordered
list before filtering/pagination; links_changed means the old start_index must
not be reused. continuation means more retained links exist; links_truncated
means some admissible links were lost to hard page-level resource ceilings
and continuation cannot recover them.

Each link returns url, best-effort label, rel, fragment, same_origin and
same_document. An empty links list does not prove that the site has no other
pages. Expected failures return {error, hint}.

USE THIS for multi-source evidence gathering when you have explicit URLs,
several search formulations, or both. It searches/fetches candidate documents,
extracts literal passages and reports acquisition gaps. It does NOT crawl links
found inside those documents. If a strong source must first be navigated to a
chapter, appendix or related page, use web_links and then pass the selected
URLs here or to web_fetch.

Supply queries=["variant one", "variant two"] and/or urls=["https://..."].
topic only ranks excerpts; topic alone does not search. Explicit URLs consume
the source budget first. If they already fill max_sources, no search is run.
Remaining candidate slots are distributed round-robin across query variants.
For domain/exclude_domains filtering, use web_search first and pass selected
result URLs here.

Returns raw material, not synthesis: query_variants, sources and gaps. Each
source has stable source_id, final URL, source_type, content_hash,
text_truncated and literal excerpts with Unicode offsets. BM25 selects passages;
source_type and ranking are not credibility judgments.

For more context around an excerpt, copy excerpt.expand.arguments into the
indicated tool; URL, offset, budget and expected_content_hash are already
supplied. content_changed returns no stale-coordinate slice.

Always inspect gaps before judging coverage. They can report failed/empty
searches, unresponsive engines, blocked/unreadable pages, insufficient text,
redirect duplicates, omitted candidates and truncation. Empty gaps do not prove
topic completeness. Expected request failures return {error, hint}; individual
source failures can coexist with successful sources.