fsv_compare_scans

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

No annotations exist, so the description carries the full burden, and it does disclose the diff categories returned, the risk-score delta, the improved/regressed verdict, and that triaged-away findings are excluded to avoid false-positive skew. It never states that this is a non-mutating analysis operation or whether the two scans must share a target/scan profile, which is the remaining material gap.

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 sentences, front-loaded with the action and its inputs, then the return contents and the exclusion rule. Every clause adds information; nothing is redundant with the schema or title.

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 the description is not obliged to enumerate return fields, yet it usefully names the verdict categories anyway. For a two-param read-style analysis tool with no annotations, the main thing still missing is any statement about preconditions or comparability of the two scans.

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% and both parameters (baseline_id, current_id) are bare strings, so the description must compensate. It references 'scan_id' generically and the before-vs-after framing loosely maps 'before' to baseline and 'after' to current, but it never explicitly binds baseline_id to the older scan or states whether the IDs must be from comparable targets.

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 and resource ('Compare two scans by scan_id') and immediately characterizes the output: resolved, new, persisting findings plus a risk-score delta and a verdict. That is far more discriminating than any sibling, which are scan/check/list/triage operations rather than pairwise comparison.

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?

'e.g. before vs after a fix' gives a concrete usage scenario, and the exclusion of triaged-away findings flags a meaningful filtering behavior. It does not name alternatives such as fsv_target_trend or fsv_list_scans, so there is no explicit when-not routing, which keeps it out of the 5 tier.

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