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

Annotations already cover readOnly, idempotent and open-world, so the bar is lower; the description still adds real value by disclosing backend routing (public APIs for HN/V2EX/Stack Exchange vs Firecrawl elsewhere), the shape of forum results, and, most importantly, that login walls, captchas and paywalls are reported rather than bypassed. It omits rate limits and latency behavior.

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 tightly packed sentences with the core action front-loaded and no filler. The second sentence is dense with site names but each clause carries distinct routing or failure 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?

An output schema exists, so return-value explanation is not required, yet the description still sketches forum output fields. For a read-only tool with only four parameters, the missing semantics of `fresh` and `max_chars` are the main remaining hole.

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 only 50%: `url` and `focus` are documented in the schema, but `fresh` and `max_chars` carry no description anywhere. The tool description compensates for none of that gap, so an agent cannot tell what `fresh` controls or how `max_chars` truncation behaves.

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 known URL') and implicitly distinguishes itself from the `search` sibling by scoping to a URL the caller already has. An agent can tell instantly this is the single-page reader, not a discovery tool.

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 qualifier 'one known URL' tells the agent this is the right call when the link is already known, which points away from `search`, but no explicit when-not-to-use or alternative-by-name statement is given. The site-specific routing note further clarifies expected input shapes.

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 establish read-only, idempotent, closed-world behavior, so the bar is lower. The description still adds real context beyond them: probes are 'bounded' (latency-limited) and 'cached' (results may be reused rather than freshly measured), which an agent needs to interpret probe output correctly.

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 tight sentences with the resource contents front-loaded and the parameter behavior second. No padding, but the fragmentary first sentence is slightly ambiguous about whether it returns configuration or configures the provider, which only the readOnly annotation resolves.

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 no explanation, and the single parameter is covered by the description. Safety profile comes from annotations. What remains thin is the practical meaning of probing (cost, freshness), a minor gap for a one-parameter diagnostic 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?

Schema description coverage is 0%, so the description must carry the probe parameter. It explains that probe=true triggers bounded cached probes and, by contrast, implies the default (false) returns passively collected state without running probes. It compensates well for the coverage gap, though it never states the default explicitly.

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 names the exact resource and its contents: provider configuration, circuit-breaker state, and cache counters, plus the probe mode. It is a diagnostic/status read, clearly distinguishable from search, fetch, and read_result, though it is phrased as a noun list rather than a verb+resource statement.

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?

'probe=true runs bounded cached probes' implies the condition under which to enable probing versus leaving it off, which is useful. However there is no explicit when-to-use/when-not-to-use guidance, no stated cost or latency tradeoff of probing, and no alternative tool to route to.

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 the safety profile (readOnly, idempotent, closed-world), so the description is free to add the non-obvious behavior: offset/limit measure characters for answer/content but items for lists, and next_offset should be followed to continue. These are genuine execution-level details an agent would otherwise get wrong. It stops short of covering truncation via max_bytes or what happens on an unknown/expired result_id.

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 the core action, then two compact field inventories and a one-line pagination rule. Dense and waste-free, though the field lists partly restate what the output schema already exposes.

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, the return shape doesn't need re-explaining, and the pagination contract — the tool's real complexity — is covered. Gaps remain around max_bytes truncation behavior and how result_id is obtained, which matter for a 5-parameter 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?

Schema description coverage is only 20%, so the description must compensate, and it does so partially: it defines offset/limit units and enumerates valid values for fields per result type. However, max_bytes (a truncation control with 512–16384 bounds) and the meaning/format of result_id are left entirely to 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?

States a specific verb and resource ('Page through a stored search or fetch result') and immediately distinguishes itself from the sibling producer tools with 'without calling any provider.' An agent can tell this apart from search/fetch/health without opening a 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 'without calling any provider' implies the intended context (re-reading an already-produced result rather than issuing a new search/fetch), but the description never names search or fetch as the source of a result_id, nor states any exclusion or prerequisite. Usage is inferable but not spelled out.

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 genuine context the annotations don't carry: a coverage check against query facets (site, comments, recency, cross-language) and the fact that forum threads are read through their APIs. It says nothing about cost, rate limits, or cache behavior beyond what the schema's `depth`/`fresh` descriptions already state.

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?

A single front-loaded sentence beginning with the core verb+resource, with no filler or restated title. The trailing list of return contents is somewhat redundant given an output schema exists, but it is compact and readable.

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 an 8-parameter tool with 38% schema coverage, the description leaves meaningful gaps: `mode` is the key behavioral switch and is unexplained in both schema and description. Output schema and annotations carry the return shape and safety profile, so the remaining shortfall is primarily around parameter selection guidance.

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 only 38%, so the description needs to compensate, and it partially does by hinting at domain scoping (site restriction) and recency via the coverage facets. But the highest-leverage parameters, `mode` (6-valued enum with no schema description) and `vertical`, are never addressed, leaving the agent no help choosing among them.

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 public web') and ties the tool to its sibling by noting it returns 'a result_id for read_result', which clarifies the boundary with the read path. It stops short of explicitly contrasting itself with `fetch`, so the differentiation is partial rather than complete.

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 mention of 'a result_id for read_result' implies the search-then-read workflow, giving implicit guidance on how this fits with siblings. However, there is no explicit when-to-use statement, no when-not-to-use, and no guidance on selecting between this tool and `fetch` for content retrieval.

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