web_search

Web search through our own metasearch layer over several independent search engines. Returns links together with information about WHO found them and how far that source can be trusted.

WHEN TO CALL. You need fresh information from the web; you need to find an organisation or a person by name. For the second and third page of results, use the same call with page=1, 2 and so on; pages are numbered from zero.

TO CHECK A FACT AGAINST INDEPENDENT SOURCES, ASK FOR IT. By default the sweep STOPS at the first engine that gave enough links — that is the cheap path, and one engine is one witness. min_engines: 3 (or corroborate: true) keeps asking, and only then do corroborated_by_url and corroborated_by_domain count anything. It costs several times the outbound requests.

IT READS BY DEFAULT. The top three links are fetched and their text arrives in the same answer in the content field — no second call is needed for the content. If you only need an overview, set read=false and the call again costs a fraction of a second.

WHEN NOT TO CALL. You need the text of a KNOWN page (you already have the address) — that is web_read, which reads up to five addresses and offers a cursor over a long document. You need a finished ANSWER across several sources rather than material — that is web_deep_search. Not suitable for searching inside a known document or repository.

HOW IT DIFFERS FROM web_deep_search. Here there is ONE pass: what was found is what was read, and you compose the answer yourself from content. There the tool composes the queries itself, goes in waves and returns a DIGESTED ANSWER together with what it failed to find. This one hands you material, that one hands you a judgement.

WHAT IT RETURNS. results[] with title, url, snippet, domain, content (the page text for the ones that were read), chars, read_status; pages_read, pages_empty, pages_failed — how many pages were paid for and how many of them turned out to be a block; timing_ms split into search and reading; via — which engines found this particular link; corroborated_by_url and corroborated_by_domain — by how many engines the page and the site are independently corroborated; search_aborted is non-empty if the metasearch stopped answering MID-SWEEP, in which case the results are incomplete by no decision of ours and the engines that were missed are named in engines_unasked.

HOW TO READ THE ANSWER — five things that are easy to get wrong.

1. AN EMPTY LIST IS A SUCCESS, not a failure: we looked and found nothing. A failure arrives separately, with ok=false and a reason. Do not repeat the query because the list was empty — repeat it rephrased.

2. engines_skipped means "not asked" (the rate limit applied), NOT "asked and stayed silent". The silent ones are in unresponsive_engines, the ones that answered a different question are in engines_irrelevant.

3. CORROBORATION IS NOT CORRECTNESS. corroborated_by_url means "this many independent engines found this same link" and does NOT mean "this answer is truer". On an ambiguous query the most corroboration goes to the best-indexed namesake rather than to the subject asked about: one name can belong to a retailer, an investigations platform, a maker of enclosures and a maker of portable power supplies at once, and all of them are real. If the sources describe DIFFERENT subjects under one name, the correct answer is "there are several, here they are", not a choice by the number of corroborations.

4. engines_trust labels each engine: clean — checked against references and does not substitute the subject; substitutes — has answered about a namesake; not checked or unavailable — there is no information. If all_engines_clean is false, the results are worth verifying against features of the subject sought: an engine may have answered about a different company of the same name. The label candidate means "no misses yet, but fewer than three observations" — not "clean".

5. A RESULT WITH text_source="not_recognised (scan)" IS A DOCUMENT WE DID NOT READ, not a page without text. It is a scanned PDF: search does not pay for a vision model on a link it merely found. If you need it, call web_read on that address — reading recognises it.