Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnly and openWorld annotations, the description discloses the full pipeline: each term is searched on each backend, results are locally re-ranked by relevance, duplicates are removed, and best pages are fetched as text. It also explains blocked-engine behavior, warnings for empty engines, and automatic retry with auto when all chosen engines are empty.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core research workflow and then uses a compact backend list to convey selection guidance. Every section earns its place, and the structure makes the default and fallback behavior easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the 12-parameter schema, full parameter descriptions, output schema, and read-only/open-world annotations, the description supplies the missing operational context: the multi-backend search pipeline, ranking, deduplication, page fetching, and engine fallback behavior. An agent has enough information to invoke this complex tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents most parameters in detail. The description still adds meaningful semantics for the backends parameter by explaining the practical behavior of auto, brave, wikipedia, and commonly blocked engines, which goes beyond the schema's brief default/unknown-name note.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: research a topic across multiple search terms and engines, then rank, deduplicate, and fetch pages. This is clearly distinguishable from a simple search or URL reader because it describes a multi-query, multi-backend research pipeline.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear contextual guidance for backend selection: auto is most reliable, brave is fast, wikipedia suits exact article lookups, and several engines are often blocked with fallback to auto. It does not explicitly compare against sibling tools like search or rag_search_ddgs, so it lacks named alternatives or when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes beyond the readOnly/openWorld annotations by disclosing the internal pipeline — results are re-ranked locally by semantic similarity before the top pages are fetched. This explains why the tool is heavier than a plain search and clarifies the two-stage cost (num_results ranked, top_k fetched). It says nothing about fetch failures or latency, which keeps it from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the action and output form, with the differentiator in a tight parenthetical. Slightly dense phrasing ('for when whole pages are wanted') costs it the top mark, but nothing is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists, so return values need no explanation, and the description covers the key behavioral fact an agent needs: results are fetched pages, ranked locally. It omits guidance on backend/recency interaction, though the schema descriptions carry that.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, and the description adds real value by explaining the two-stage relationship between ranking many results and fetching the top ones, which the schema documents only per-parameter. Numeric/format detail is left to the schema, which is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Search the web and return the most relevant pages as text') and immediately contrasts the output with the sibling 'search', which returns only passages. An agent can distinguish the two without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear selection condition: use this when whole pages are wanted rather than relevant passages. It does not position the tool against the other siblings (deep_research, read_url), so the when-to-use story is incomplete but the core routing decision is explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover safety (readOnlyHint) and world reach (openWorldHint), and the description adds real behavior beyond them: two output modes depending on whether a query is supplied, and truncation to a shared budget in the no-query case. It doesn't discuss failure modes or rate limits, but the URL restriction is already carried by the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the precondition, then formats, then the two-mode behavior. No filler and nothing repeated from the schema verbatim.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values needn't be described, and the description covers formats, the two extraction modes, and the budget cap. The only thin spot is what happens on refused or unreachable URLs, which is left entirely to the schema's url field.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by explaining the conditional semantics of `query` — that supplying one yields answer-bearing passages "the same way search does" — and that omitting it returns main text clipped to a budget. That connects `query` and `max_passages` behaviorally in a way the per-field descriptions do not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Read one page") and immediately scopes it to URLs the agent already possesses, which cleanly separates it from the search siblings. It also names the supported content types (HTML or PDF), so an agent knows what it can point this at without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase "whose URL you already have: a link the user pasted, or one from earlier results" tells the agent the precondition for use and implicitly rules out discovery (that's what search/deep_research are for). It stops short of naming a sibling as the alternative for the discovery case, so it's clear context rather than an explicit when/when-not pair.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint and openWorldHint; the description goes well beyond them by disclosing the internal pipeline — fetch top pages, split into ~600-char passages, BM25 keyword matching, local embedder as a meaning-based fallback. The "cheapest first" framing also signals relative cost, which annotations never convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and the routing cue, then a compact numbered pipeline. The tiered list is the right structure for a staged algorithm, and no sentence is filler — even the parenthetical about a tenth the text of rag_search_ddgs carries decision value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be explained, and the description still covers cost, fallback behavior, and failure handling for an 11-parameter tool. Nothing an agent needs in order to call it correctly or decide against a sibling is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage the baseline is 3, but the description earns more by explaining roles: `keywords` is described as the BM25 matching vocabulary in tier 2, and `top_pages` as the set of pages fetched and split. It does not clarify the interplay between num_results, top_pages, and max_passages, which is the one remaining ambiguity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (search the web) plus the defining scope constraint: it returns passages, not whole pages. It explicitly contrasts with sibling rag_search_ddgs ("about a tenth of the text"), so an agent can choose between them without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Use this first" gives explicit precedence over siblings, and the numbered tiers state the conditions under which the cheap path is kept versus when the embedder fallback is invoked ("only if that leaves too many candidates, or matches nothing"). It even covers the escalation path to the user when nothing matches.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.