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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description goes well beyond by disclosing FTS5 semantics (AND on whitespace, phrase quoting, prefix/OR/NOT), return format differences, and the common mistake of treating it like web search. It adds rich behavioral context without contradicting annotations.

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 structured with clear sections and front-loaded with the core purpose. It's longer than average but each section (best-for, not-recommended, returns, mistakes, args) adds distinct value. Slightly verbose, but nothing is redundant or filler.

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?

The tool has 3 params and no output schema, so the description must cover both invocation and return semantics. It does: it explains the return formats, metadata caveats, and pitfalls. An agent has everything needed to call this correctly, including edge cases like empty cache and phrase quoting.

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 description coverage is 0%, so the description carries full burden. It explains `query` with FTS5 syntax (AND, OR, NOT, prefix, phrase), `limit` as max hits, and `format` with output differences (markdown vs json, plus the metadata caveat). This is far more than the schema provides.

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 opens with a precise verb+resource: 'Full-text search over pages already fetched into the local SQLite FTS5 index.' It immediately distinguishes itself from siblings by explicitly naming `search`/`research` as the alternatives for discovering new pages, making the tool's scope unambiguous.

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 has a 'Best for' section listing concrete use cases (recalling fetched content, avoiding re-fetches, keyword grep) and a 'Not recommended for' section that names alternatives (`search`/`research`) and even covers the empty-cache case. This is explicit routing with no inference needed.

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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses concurrency, smart truncation, return format specifics (markdown/json with tokens_estimated), and common mistakes (e.g., asking it to answer the question). No contradiction with annotations; it adds valuable behavioral context.

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 well-structured with sections (intro, best for, not recommended, returns, mistakes, args). It front-loads the core purpose and each sentence earns its place, providing high information density without fluff.

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?

The description is fully self-contained: it covers when to use, when not to use, parameter details, return formats, and common pitfalls. No output schema exists, but the return description is detailed enough for an agent to handle responses 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 description coverage is 0%, so the description must compensate. The 'Args' section explains every parameter: question (purpose), urls (count and format), format (enum with default). This is complete and adds meaning beyond the bare schema.

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 action ('Fetch 2-5 URLs concurrently and return per-URL excerpts'), identifies the resource (URLs), and clarifies the outcome (enables comparison). It also distinguishes itself from siblings by naming fetch_batch and fetch as alternatives for different URL counts, leaving no ambiguity.

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?

Explicit 'Best for' and 'Not recommended for' sections give concrete usage conditions: >5 URLs → fetch_batch, 1 URL → fetch, no URLs → search/research. This is direct, actionable guidance on when to use this tool versus alternatives.

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?

Beyond annotations, the description discloses filesystem effects, default-enabled behavior, environment variable controls, auto-expiring paths, TTL cleanup, and return details. This is substantial additive transparency consistent with readOnlyHint=false and there is no contradiction with the annotations.

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 organized into clear labeled sections (best for, not recommended, returns, retention, args) with no filler. The core action is front-loaded, and every section earns its place by providing actionable information.

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 lack of an output schema, the description provides both markdown and JSON return shapes, including the sha256 and expiry fields. It also covers retention, configuration, and use cases, making it complete enough for an agent to invoke safely and 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?

With 0% schema description coverage, the description compensates by specifying that url must be an absolute http(s) URL and by explaining format through the Returns section. It could go slightly deeper on format semantics, but the return value details largely close the gap.

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: 'Save a file from a URL to a local, auto-expiring download directory.' It clearly differentiates from siblings like read_doc and fetch by saying it keeps an actual file rather than parsing content or viewing a page.

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 'Best for' and 'Not recommended for' sections explicitly name alternatives: read_doc for document content, fetch for web pages, and fetch(inline=True) for images. This gives an agent unambiguous when-to-use versus 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?

Annotations already mark the tool read-only and idempotent, and the description adds genuinely useful behavioral context: the list is static and should be read once, returns can be markdown or JSON, and key-only engines produce actionable errors. This goes well beyond what annotations 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?

Although long, the description is tightly organized with functional headers, scannable bullet-ish sections, and every sentence adds routing or error-avoidance value. The core purpose is front-loaded, and the detailed guidance is where an agent needs it.

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?

For a read-only list tool with two optional parameters and no output schema, this description is complete: it explains when to use it, what the parameters do, what output format to expect, and likely failure modes. No critical calling information 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?

Schema coverage is 0%, so the description carries the full burden of explaining parameters. It clarifies `group` values, how dotted sub-groups narrow, how `category=` differs from `engines=`, and what both markdown and JSON output shapes look like. This compensates fully for the schema's lack of parameter descriptions.

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 clearly states the tool lists available sources/engines grouped by what they index, which is specific and immediately distinct from siblings like `search`, `research`, and `fetch`. It names the resource and the organizing principle without ambiguity.

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 explicit best-for scenarios, a not-recommended scenario, and detailed routing guidance comparing `category=` vs `engines=` and group/sub-group semantics. It also lists common mistakes, giving an agent both positive and negative selection criteria.

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 declare readOnlyHint, openWorldHint, and idempotentHint. The description adds value beyond these: it discloses the return format details (JSON key structure, markdown flattening behavior), the Twitter-card-inside-opengraph quirk, and the open-world caveat that most pages yield empty lists. No contradiction with annotations.

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?

Well-organized with clear section headers (Best for, Not recommended, Returns, Common mistakes, Args). It is longer than minimal, but each section earns its place and the core purpose is front-loaded. Slightly verbose but purposefully structured.

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?

Complete for a multi-format extraction tool with no output schema. The description carries the return-format burden itself, listing the JSON keys, the markdown default behavior, and parameter meanings. It also sets expectations about empty results. An agent has everything needed to call it 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 description coverage is 0%, so the description must compensate — and it does. The Args section clarifies that url must be an 'Absolute http(s) URL' (a constraint not in the schema) and explains format's options and default. This adds real meaning beyond the bare schema definitions.

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-resource pair: 'Pull JSON-LD, OpenGraph, Twitter cards, and microdata from a web page.' It lists the exact data formats extracted, and distinguishes itself from siblings by name (fetch, read_doc), making the tool's identity unambiguous.

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?

Exceptionally explicit. It provides 'Best for' scenarios (product, article, recipe/event/video pages), 'Not recommended for' cases with named alternatives (use fetch, use read_doc), and a 'Common mistakes' warning that most sites lack structured data and fetch is preferred. Nothing is left to inference.

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 declare readOnlyHint, openWorldHint, and idempotentHint, and the description adds extensive context beyond them: cache behavior with 7-day TTL and force_refresh semantics, render mode differences including caveats for JS-only SPAs, inline image token costs, and the meaning of 'no publication date found'. No contradictions with annotations.

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 lengthy but densely structured with clear headers, bullet lists, and code-style naming. Every section adds actionable information: return formats, common mistakes, and parameter semantics. No redundant fluff; the structure makes the length digestible.

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?

For a complex tool with six parameters and no output schema, the description is remarkably complete. It covers input requirements, output shapes for markdown and json, non-text resource descriptions, caching, render strategies, and failure-prone usage patterns. An agent has everything needed to invoke this 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 description coverage is 0%, so the description carries the full burden, and it delivers a detailed Args section explaining every parameter, including defaults (render='auto', format='markdown') and nuanced behavior (max_age_hours=0 means force_refresh, None means server TTL). This fully compensates for the schema's lack of descriptions.

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: 'Fetch one URL: page text, or a description of a non-text resource.' It clearly identifies what the tool does and differentiates it from siblings by listing what it is not (batch fetch, research, read_doc). An agent can select it correctly.

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 provides explicit 'Best for' and 'Not recommended for' sections, naming alternatives like fetch_batch, research, read_doc, and search with precise conditions. This is exactly the level of guidance needed to route the agent to the right tool.

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 declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds crucial behavioral details: per-URL failures do not raise exceptions, the markdown output embeds inline error notes, and the JSON format includes an error field per entry. It also warns against common mistakes, exceeding what annotations alone 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?

The description is organized into labeled sections (Best for, Not recommended, Returns, Common mistakes, Args) that are easy to scan. Every sentence adds value—there is no filler. The core purpose is stated first, and the detailed subsections are appropriately sequenced.

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 there is no output schema, the description fully specifies the two return formats (markdown sections with inline errors, and JSON list with error fields). It covers edge cases (single URL, failed items, maximum batch size) and references sibling tools for alternatives. An agent has everything needed to invoke it 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 description coverage is 0%, so the description carries the full burden. It explains each parameter: urls as absolute http(s) with a max of 20, render as 'Same as fetch' (referencing the sibling), and format with its two allowed values. It also clarifies the failure semantics associated with the urls parameter, which the schema does 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?

The description opens with a specific verb and resource ('Fetch a list of URLs in parallel') and immediately differentiates itself from siblings by naming fetch, research, and read_doc with explicit conditions. The purpose is unambiguous and the scope is clearly bounded.

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?

It provides a 'Best for' section listing concrete scenarios (2+ URLs, top N results of a search) and a 'Not recommended for' section with explicit alternatives (single URL -> fetch, search-and-read -> research, PDFs/DOCX -> read_doc). This gives an agent clear decision criteria for tool selection.

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 provide readOnlyHint, openWorldHint, and idempotentHint, but the description adds substantial behavioral context: retraction/correction notices, citation ordering by field impact, truncation behavior in citations list, and specific return format details. It also explains the 'notes' field for truncated lookups. No contradictions with annotations.

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?

Though lengthy, the description is meticulously structured with headers, bullet lists, and code blocks. The core purpose and differentiation are front-loaded, and every section (Best for, Not recommended, Returns, Common mistakes) provides non-redundant, actionable information.

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 there is no output schema, the description fully explains both markdown and json return formats, including nested fields like paper.crossref and notices. It covers edge cases like truncated citations and retraction notices, ensuring an agent has all necessary information to invoke the 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 0%, so the description fully compensates. It explains the paper parameter with concrete examples (DOI, OpenAlex ID, exact title), the direction enum with meanings, the limit range (1-50), and format with return-type implications. This goes far beyond the schema's bare definitions.

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 the specific verb 'follow the citations' and the resource 'ONE paper', clearly differentiating from search which finds mentions. It also explains the distinction between edge-following and text-matching, making the purpose unambiguous.

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?

Explicitly provides 'Best for' and 'Not recommended for' sections, naming alternatives like search(category=...), read_doc, and giving concrete scenarios. Also includes 'Common mistakes' that warn against passing topics instead of papers, which directly guides correct usage.

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 provide readOnlyHint, openWorldHint, and idempotentHint, but the description goes far beyond them: it details sandboxing rules (env var requirement, path traversal rejection, file:// rejection), error behavior (disabled error, negative length ValueError), clamping semantics, and the exact pagination signal (`returned_chars == 0`). This is rich behavioral context that annotations alone could 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?

The description is long but every section serves a purpose: 'Best for' and 'Not recommended for' give usage guidance, 'Security' explains the critical env var behavior, 'Returns' details output formats, 'Common mistakes' prevents misusage, and 'Args' is a compact parameter reference. It front-loads the core purpose in the first line and organizes details logically, earning its length.

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?

This is a genuinely complex tool (remote vs local, pagination, security, multiple output formats), yet the description covers every aspect needed to call it correctly: input expectations, edge cases (clamping, negative length), output structure (markdown header, json fields), and how to detect end-of-document. With no output schema present, the description fully substitutes that information. Nothing essential 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 schema description coverage at 0%, the description fully compensates. The Args section explains each parameter: source's format and security constraints, start's default and clamping behavior, length's range and rejection condition, and format's enum meaning. It also provides the json return fields to drive pagination, making each parameter's role crystal clear.

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 opening line states a specific verb and resource ('Read an http(s) document or sandboxed local file into Markdown'), and the 'Best for' / 'Not recommended for' sections explicitly differentiate it from siblings like fetch and research. An agent can immediately tell what this tool does and what it doesn't.

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?

There are explicit usage recommendations with named alternatives: 'Not recommended for: Arbitrary HTML web pages -> `fetch` does reader-mode cleanup...' and 'Pages discovered through search -> `fetch` or `research`.' It also explains the crucial security prerequisite for local files. No ambiguity remains.

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 declare readOnlyHint=true and openWorldHint=true, but the description goes far beyond that: it discloses fetch behavior, cache semantics (use_cache, max_age_hours with 0 vs None), freshness handling, the difference between markdown and json return formats, the effect of fetch=False, and even behavioral nuances like 'Naming engines turns category routing off'. It also explains that non-zero max_age_hours is honored for both halves, correcting a past behavior. This is rich, accurate, and does not contradict the annotations.

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 long but impeccably structured: a one-line summary, then 'Best for', 'Not recommended for', 'Returns', 'Common mistakes', and 'Args' sections. Every sentence adds value—even the 'Common mistakes' section reinforces the usage guidelines. It is front-loaded with the core purpose, and the Args section is efficiently organized with one-line-per-parameter explanations. 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?

Given the tool's complexity (13 parameters, no output schema) and the absence of an output schema, the description covers everything an agent needs: return formats (markdown vs json) with descriptions, parameter semantics, usage guidance, and even error handling (json 'errors' field). It also provides token estimates and source structure, making it self-contained for correct invocation.

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 description coverage is 0%, so the description carries full responsibility for parameter meaning. It does this exceptionally: each of the 13 parameters is explained in natural language with defaults, effects, and interactions (e.g., depth=3 as good default, engines override category routing, include_text substring semantics). This far exceeds the schema's basic types and enums.

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 opening line 'One-shot research: search the web, fetch the top results, return both' states a specific verb+resource and a composite action. It distinguishes itself from siblings via the 'Not recommended for' section, naming 'search', 'fetch', and 'cache_search' with explicit conditions. This leaves no ambiguity about what the tool does.

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 'Best for' and 'Not recommended for' sections are explicit, concrete, and name the exact sibling tools to use instead (search, fetch, cache_search, paper_graph) with the conditions that select them. It even gives example use cases and common mistakes (e.g., using depth=8 for quick lookups), leaving no inference to the agent.

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 read-only/open-world/idempotency, but the description adds substantial context beyond them: cache key composition and TTL semantics, engine benching and rescue passes, best-effort freshness with undated results kept, per-engine result caps, and the risk that an agent-sourced Answer block is unverified. It even flags the failure mode of trusting snippets for dates and numbers.

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?

Headers, bullet lists, and front-loaded scope make a long description navigable, and the 'Common mistakes' block earns its space by preventing real misuse. It is nonetheless verbose — repeated restatements of category behavior and category values appear in both the bullet list and the Args section.

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?

No output schema exists, and the description fully specifies both return formats including the json field set (results, engines, cached, errors, hint, agent, benched_engines, rescued_via, agent_lane). For a 12-parameter, multi-engine tool with conditional routing, nothing an agent needs to call it correctly 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?

Schema description coverage is 0%, so the description carries the full burden and does: every one of the 12 params gets semantics beyond type — max_results is both merged count and per-engine budget with a 1-50 clamp, use_cache keys on the full filter tuple, max_age_hours never disables writes, freshness is a hint not a filter, and category is explained as widen/narrow plus a reranking signal.

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 opening sentence names a specific verb, resource, and output shape ('multi-engine web search ... ranked, deduplicated link list'), and the surrounding sections make it unmistakable against siblings like fetch, research, and cache_search.

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?

There is an explicit 'Best for' list, a 'Not recommended for' list that names the alternative for each excluded case (fetch, research, cache_search, read_doc, paper_graph), and per-category routing advice. An agent can decide between siblings without opening another schema.

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