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

The annotations declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe read operation. The description adds significant behavioral context beyond that: it reveals that a confirmed critical caps the grade, that the band is withheld when evidence is insufficient, and that the tool returns a ranked findings list. It also warns the agent not to fabricate a band ('Report the withheld state rather than supplying a band yourself'), which is critical for correct use. No contradiction with annotations exists.

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 concise but packed with essential information: it states the purpose, outputs, two critical rules, and a key usage caveat in just three sentences. It front-loads the purpose and output list, then adds behavioral rules. Every sentence earns its place, with no redundancy or filler. Ideal length for a tool with moderate complexity.

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 (11 parameters, multiple rules, no output schema), the description is complete: it explains the purpose, output structure, special scoring rules (critical cap and withholding), and the necessity of reporting withheld state. The schema covers parameter details, so the description doesn't need to repeat them. The absence of an output schema is compensated by the description's clear list of return elements. The only minor gap is that it doesn't explicitly state input validation rules (e.g., minItems), but the schema already handles 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?

The schema description coverage is 100%, with all 11 parameters documented with rich descriptions in the schema. The tool description itself does not add further parameter-specific semantics, but it does instruct the agent to send only check ids and statuses, never figures or balances, which reinforces the 'results' parameter. Given high schema coverage, the baseline of 3 is appropriate; the description doesn't need to do more, but it doesn't go beyond the schema either.

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 uses a specific verb ('Score a books health check') and clearly states the resource and what the tool does—it computes a weighted health score from evidenced statuses. It distinguishes itself from sibling tools like list_books_checks and explain_books_check by detailing the output (weighted score, band, per-dimension breakdown, findings ranked worst first) and adding unique rules. The title 'Score books health' is directly expanded with actionable detail, making it clear and non-tautological.

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 tells the agent when to use this tool: when scoring a health check from actually evidenced statuses. It also provides crucial when-not guidance by stating 'Report the withheld state rather than supplying a band yourself,' preventing misuse. While it doesn't name alternative tools directly, it implies that this tool is for computing a score rather than explaining checks or listing obligations, which is sufficient given the sibling context.

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