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

Goes well past the annotations (readOnlyHint/openWorldHint/non-destructive), which only cover the safety profile. It discloses the auth requirement, the accepted credential formats, the degraded-but-successful behavior without a key, and how to interpret the result via the basis ('closer_read' vs 'patterns') and confidence ('reviewed' vs 'low') fields — exactly the kind of hidden behavior an agent needs.

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-loads the purpose, then the auth requirement, then the result-interpretation rule; every sentence carries operational information. Mild redundancy in repeating 'the closer read' and a slightly promotional tone keep it from a 5.

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 compensates by explaining the result's basis/confidence fields, plus the credential prerequisites and fallback path. The remaining gap is sibling routing — it never says how this relates to `review_code` — which matters given how many review-adjacent tools are listed.

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% and each of code, diff, and lang is documented in-schema, including the 60,000-character cap and the diff-mode semantics. The description adds nothing about how parameters affect the two review stages or how code and diff interact, so baseline 3 applies.

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 (reviews code) plus the two-stage mechanism: instant checks followed by an AI reviewer that validates, drops, and adds findings with line quotes. That is far more concrete than a name restatement. It stops short of distinguishing itself from the sibling `review_code`, which by naming appears to be the plain variant, so the agent must infer the difference.

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 does give concrete operational guidance: a key in the Authorization header is required for the closer read, with the exact key prefixes and a URL, and the no-key fallback is spelled out. However, there is no statement of when to choose this tool over `review_code` or when either should be preferred, which is the main selection decision an agent faces here.

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