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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's job is to add context beyond those. It explicitly states 'Every call is read-only and idempotent,' which reinforces the annotations. More importantly, it details error behavior ('never raises a protocol error — it returns {"error": ...}') and describes the scanning scope ('Only added (+) lines are scanned'), which are behavioral traits not captured by annotations. A slight deduction because it does not mention any rate limits, cost implications, or auth requirements, though for a non-destructive, free tool this is minor.

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 compact (about 10 sentences) yet rich in information. It front-loads the core purpose in the first line, then efficiently covers scope, risk patterns, example usage, when-to-use vs not, and error behavior. No sentence is wasted — each adds distinct value. The use of bold and bullet-like lists in the output format description enhances readability without extra words.

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 has only 1 parameter with 100% schema coverage, comprehensive annotations, and an output schema (evident from detailed output description), the description covers all important aspects: purpose, sibling differentiation, error handling, idempotence, and input constraints. The only minor gap is that it does not explicitly list all supported output fields individually, but the output schema presumably handles that. For a tool of this complexity, no additional context is needed.

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 100% with a single required parameter 'diff' described as 'A unified diff exactly as produced by git diff — text with @@ hunk headers and +/- line prefixes. Only added (+) lines are scanned.' This is already quite complete. The description adds value by showing a typical usage example ('{"diff": "<git diff output>"}') and explaining how only added lines are scanned, which augments the schema description. It could be a 5 if it also described optional parameters or edge cases in input formatting.

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 'Risk-scan a unified diff the way a senior reviewer triages a PR,' providing a specific verb ('risk-scan') and resource ('a unified diff'). It clearly distinguishes this tool from siblings like complexity_report and ai_code_smell_scan by focusing on changes only and listing specific risk patterns it flags (injection sinks, disabled TLS, etc.). The description also explains what input is expected and what output format to expect, leaving no ambiguity about its 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 gives explicit guidance: 'Use on a unified diff, when only the change matters.' It directly states when not to use it ('Not for whole-file analysis') and names two sibling alternatives (complexity_report, ai_code_smell_scan) for those scenarios. Additionally, it explains error handling ('never raises a protocol error — it returns {"error": ...}') and safety profile ('read-only and idempotent, safe to retry'), which informs proper usage patterns.

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