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

Annotations declare readOnlyHint, openWorldHint=false, and idempotentHint, but the description adds substantial context: it explains cache-only behavior, FTS5 query semantics, default format, snippet highlighting, empty cache behavior, and empty metadata fields for old rows. 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?

The description is well-structured with clear section headers (Best for, Not recommended for, Returns, Common mistakes, Args). It is longer than average but every sentence contributes functional guidance; no filler or repetition.

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?

Despite an output schema, the description explains return value details (per-hit list, bracket highlighting, JSON fields, empty strings for old data). It also covers edge cases like empty cache and common usage mistakes, making it fully contextual for an AI agent.

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%, but the description explains all three parameters clearly: query syntax (AND, OR, NOT, prefix, phrase), limit as max hits, and format with 'markdown' or 'json' values and their output differences. This fully compensates for the lack of schema 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 opens with a specific verb and resource: 'Full-text search over pages already fetched into the local SQLite FTS5 index.' It clearly distinguishes the tool from siblings like 'search' and 'research' by emphasizing 'local cache only' and explicitly contrasting with web 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?

The 'Best for' and 'Not recommended for' sections provide explicit usage criteria, including when to use alternatives ('use `search` or `research`'). This directly answers when to use vs. avoid the 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?

Even with annotations declaring readOnlyHint and idempotentHint, the description adds valuable behavioral context: concurrent fetching, smart truncation, returned formats (markdown/json), tokens_estimated, and the common mistake that `compare` does not itself answer the question. 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 long but every sentence earns its place. It is structured with clear sections (Best for, Not recommended for, Returns, Common mistakes, Args), making it scannable and informative without redundancy.

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 tool with 3 parameters and an output schema, the description covers all necessary context: use cases, limits, return formats, and common pitfalls. It is fully self-contained and an agent can invoke it correctly without needing external information.

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%, but the description fully compensates with an 'Args' section explaining each parameter, including the default for `format`, the 2-5 URL constraint, and that `question` is the comparison question. This adds meaning well 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 leads with a specific verb+resource+scope: 'Fetch 2-5 URLs concurrently and return per-URL excerpts'. It clearly differentiates from siblings by explicitly naming use cases and not-recommended cases, such as using fetch_batch for >5 URLs and fetch for 1 URL.

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?

Usage guidance is exemplary: it lists exact scenarios for use ('Compare X to Y', 'Triangulating a fact') and explicitly names alternatives (fetch_batch, fetch, search, research) with conditions. This leaves no ambiguity about when to invoke this 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?

The description discloses important behavioral details beyond annotations: auto-expiring directory, TTL cleanup, environment variable overrides, and the JSON return format including sha256 and expires_in_hours. It clearly states files are short-lived and advises copying if persistence is needed, which is valuable context for agents.

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 a clear opening sentence, bullet-like 'Best for' and 'Not recommended for' sections, and a concise 'Args' list. Every section adds value without redundancy, and the most critical information is front-loaded.

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 covers purpose, configuration, retention behavior, return formats, and alternative tools. It also addresses the open-world aspect (external URLs) and idempotency implicitly. Given the output schema exists, the description still enriches context with environment variables and cleanup schedules, making it complete for an AI agent.

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?

Although the schema has no descriptions for parameters, the description compensates fully by documenting 'url: Absolute http(s) URL' and 'format: markdown or json'. It also explains the default format and the different return structures for each, adding semantics beyond the 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 clearly states the tool's function: 'Save a file from a URL to a local, auto-expiring download directory.' It distinguishes itself from siblings by listing alternatives like read_doc and fetch for other use cases.

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 specific alternatives (read_doc, fetch, fetch(inline=True)) and explaining when to use each. This leaves no ambiguity about when to select this 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?

Building on the readOnly and idempotent annotations, the description adds substantial behavioral detail: the list is live and complete, buckets are illustrative, the tool may return an actionable error for key-only engines with no key, and engine results are static/cacheable. It also discloses operational nuances like HTTP-first behavior and captcha issues, which go far beyond the annotation hints.

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 well-structured with clear section labels ('Best for', 'Not recommended for', 'Returns', 'Common mistakes', and engine category groupings). The core purpose is front-loaded, and while the engine-by-engine details are extensive, they are substantive and directly useful for selecting the right engine. A minor deduction for slightly verbose enumeration that could be partly externalized.

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 simple listing tool, the description is remarkably complete: it explains the return type, provides defaults, keyless opt-ins, verticals, key-required engines, common mistakes, and sibling relationships. The output schema exists, but the description still covers behavior and integration context, making it fully self-sufficient.

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?

The tool has zero parameters, so the input schema is empty and the description needs no parameter explanation. It earns the baseline 4 by clearly explaining the meaning and usage of the returned values (engine name strings) in the context of other tools, even though an output schema exists. It adds value by clarifying how these names are consumed by `search` and `research`.

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 crisp, specific statement: 'List engine names accepted by the `engines=` parameter of `search` / `research`.' This uses a clear verb+resource and immediately distinguishes this tool from sibling search/fetch tools by focusing on engine name discovery. It answers both what and why.

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 explicitly states when to use ('Best for: Discovering what's installable before passing a non-default engine', 'Building user-facing UIs') and when not (not for calling on every search, cache it). It also details the alternative of using `category=` with `search`/`research` instead of explicit engines, giving clear, actionable 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?

The description provides rich behavioral context beyond the annotations: it details the exact return shape (`json` and `markdown` views), notes that Twitter cards are surfaced inside the `opengraph` list, and warns that pages without schema.org metadata will yield empty lists. This is far more than the read-only/idempotent hints already 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 well-structured with clear section headers, bullet lists, and a compact Args section. Every sentence earns its place — the length is justified by the need to convey use cases, return formats, and common pitfalls without redundancy.

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?

Despite the moderate complexity, the description covers purpose, usage guidelines, return formats, behavior on empty results, and parameter semantics. It also cross-references sibling tools appropriately. With an output schema present, the description doesn't need to repeat return type details, but it still explains the two output formats clearly.

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%, but the description fully compensates: it specifies that `url` must be an absolute http(s) URL, and explains `format` options (markdown default vs json) with context from the Returns section. This adds meaning that the raw schema (type + enum) does not provide.

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 starts with 'Pull JSON-LD, OpenGraph, Twitter cards, and microdata from a web page' — a specific verb and resource that clearly states what the tool does. It also explicitly contrasts with sibling tools, noting when to use `fetch` or `read_doc` instead, which fully distinguishes it from alternatives.

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 give explicit use cases with concrete page types and explicit fallback alternatives. The 'Common mistakes' section further clarifies when not to use the tool, providing strong usage guidance beyond mere capability.

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 annotations, the description discloses significant behavioral details: rendering modes (auto/http/browser) and their tradeoffs, parsing behavior for different file types, a 7-day cache with force_refresh/max_age_hours controls, token cost implications of inline images, and common mistakes like using render='http' on SPAs.

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 excellently structured with headers, bullet lists, and short paragraphs. Every sentence adds functional value—no filler—and the front-loaded summary plus examples make it 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?

Despite lacking an output schema, the description fully specifies return formats (markdown/json), non-text resource details, error-prone scenarios, and parameter semantics. It covers all necessary context for correct invocation, making it complete for a complex tool.

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?

Since the input schema has zero description coverage, the description fully compensates with an 'Args' section that explains each of the 6 parameters, including defaults, allowed values, and specific behavior (e.g., inline ignored for text resources, max_age_hours semantics). This goes far beyond the 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 opens with 'Fetch one URL: page text, or a description of a non-text resource,' providing a specific verb and resource. It also distinguishes itself by covering multiple resource types and hinting at its relationship with siblings like fetch_batch and read_doc.

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 name direct alternatives (fetch_batch, research, read_doc, search) and outline precise scenarios, such as verifying a single claim versus searching and reading top N.

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 (readOnlyHint, idempotentHint), the description discloses key behaviors: per-URL failures do not raise, failed URLs appear as inline error notes in markdown or error fields in JSON, and the max batch size of 20. This enriches the agent's understanding of edge cases.

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 moderately long, the description is well-structured with clear sections (Best for, Not recommended for, Returns, Common mistakes, Args). Every sentence provides actionable information, and there is no redundant repetition of schema or annotations.

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 complex tool with multiple parameters, error semantics, and alternatives. The description covers batch limits, error handling, return formats, render behavior, and sibling distinctions. With an output schema already present, the extra return-value detail is a bonus, making the description complete for an AI agent.

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?

The schema has 0% description coverage, but the description fully compensates with an Args section explaining each parameter: `urls` (absolute http(s), max 20), `render` (same as fetch), and `format` (markdown or json). It also clarifies the output behavior tied to format.

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 'Fetch a list of URLs in parallel' with a specific verb and resource. It distinguishes itself from siblings by explicitly saying when to use `fetch` (single URL), `research` (search+read), and `read_doc` (PDFs/DOCX).

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?

Provides explicit 'Best for' and 'Not recommended for' sections that name alternatives (`fetch`, `research`, `read_doc`). This gives the agent clear decision rules 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 already declare read-only, idempotent, and open-world hints, but the description adds substantial behavioral detail: local-file sandboxing, environment variable gating, file:// rejection, path traversal protection, clamping behavior for start/length, and the exact signals for paging off the end. 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?

The description is long but every section earns its place: Best-for/Not-recommended, Security, Returns, Common mistakes, and Args. Information is front-loaded with the core verb+resource first, and the structure makes it easy to scan. No redundancy 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?

Despite having an output schema, the description still explains the json format fields and pagination signals. It fully covers the tool's complexity: security sandbox, env var dependency, error conditions, sibling differentiation, and parameter semantics. Nothing important is left ambiguous for a tool with this many nuances.

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 has 0% description coverage, so the description must fully explain parameters. The 'Args' section does this thoroughly: source (URL vs local path, security constraints), start (offset, clamping, negative handled as 0), length (None means to end, must be >= 0, ValueError on negative), and format (markdown vs json). Goes far beyond the schema's bare types and defaults.

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 reads http(s) documents or sandboxed local files into Markdown. It distinguishes itself from siblings by explicitly noting it is not for arbitrary HTML pages (use fetch) or search-discovered pages (use fetch/research).

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?

Provides explicit 'Best for' and 'Not recommended for' sections with named alternatives (fetch, research). Also includes critical usage context like when local reads are enabled and how pagination should work.

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 spartan annotations, the description discloses cache write-back behavior, TTL semantics for `max_age_hours`, return format details, token estimation, and failure-prone usage patterns. It even notes a historically surprising behavior (non-zero `max_age_hours` now applies to both search and pages), adding real transparency.

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 it is highly structured with scannable headings, bullets, and a clear linear flow. Every section adds distinct value: purpose, use cases, exclusions, return format, common mistakes, and parameter details. The length is justified by the tool's complexity and parameter count.

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, the description covers purpose, usage boundaries, output formats, and parameter behavior well, and the output schema exists to formalize return values. Still, the description omits several parameters (e.g., `category`, `freshness`, domain filters), which leaves some operational gaps for an agent trying to use the full feature set.

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 burden. It explains `question`, `depth`, `engines`, `fetch`, `use_cache`, `max_age_hours`, and `format` with actionable detail, but leaves `category`, `freshness`, `exclude_text`, `include_text`, `exclude_domains`, and `include_domains` unexplained. The covered parameters are handled very well, but the six omitted ones are a clear 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+resource: 'search the web, fetch the top results, return both.' It clearly distinguishes this tool from siblings by framing it as a combined search-and-fetch operation, with the title 'Search and read in one call' reinforcing the purpose.

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 concrete alternatives: `search`, `fetch`, and `cache_search`. It also includes common mistakes and specific scenarios, giving an agent clear decision criteria for when to use this tool versus siblings.

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 and openWorldHint, and the description adds substantial behavioral context beyond that: cache read/write semantics, freshness best-effort behavior and exactness for googlenews, category whitelist client-side filtering, engine limitations (browser-rendered, captcha), and deduplication behavior. It also discloses the return format and potential 'hint' string, all of which go beyond the structured annotation fields.

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 extremely well-structured: it opens with a one-sentence summary, uses bullet lists for best/not-recommended use, separates return format details, and includes a 'Common mistakes' section. Every section adds actionable content for a 12-parameter tool, so the length is justified and the information is front-loaded with the core purpose.

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 12 parameters, no required schema descriptions, and rich annotations, this description covers all critical aspects: purpose, return formats, cache behavior, engine caveats, filter semantics, and failure recovery. The presence of an output schema is reinforced by an explicit explanation of markdown vs. JSON return structures, making the description fully self-sufficient for an agent to select and 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?

Despite 0% schema description coverage in the structured fields, the description thoroughly documents every parameter: query (natural-language), engines (with default set and opt-in caveat), max_results (useful range and cap behavior), use_cache (cache key specificity), max_age_hours (write-back behavior), freshness (semantics and limitations), include/exclude_domains, category (with concrete examples like 'paper' => arxiv/acm/springer), include/exclude_text, and format. 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?

Description opens with a specific verb+resource+scope: 'Run a multi-engine web search and return a ranked, deduplicated link list.' It distinguishes itself from siblings by explicitly naming alternatives like fetch, research, and cache_search in the 'Not recommended for' section, 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?

Usage is clearly segmented into 'Best for' (discovery queries, URL list generation, post-cutoff topics, domain/filtered searches) and 'Not recommended for' with explicit sibling alternatives (fetch, research, cache_search, read_doc). It also includes common mistakes that steer agents away from misuse, offering strong when-to-use vs. 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.