fsv_get_report

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

With no annotations, the description carries the full behavioral burden. It usefully signals that the scan must be "completed" and clarifies that html is self-contained and sarif targets CI, but it says nothing about what happens on an incomplete/unknown scan_id, whether output is size-limited, or that this is a read-only retrieval.

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 sentence, front-loaded with the action and resource, followed by a terse enumeration where each item contributes a valid value absent from the schema. No filler or repetition.

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-shape explanation is unnecessary, and the format enumeration covers the main ambiguity. The remaining gap is practical: the agent is never told where a scan_id comes from (e.g., fsv_list_scans) or what failure looks like for an incomplete scan.

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 the format field has no enum in the schema, so the exhaustive value list with per-value meaning and the stated default ("md") adds real value that the schema cannot provide. The scan_id parameter, however, is left entirely undocumented — no mention of what it is or how to obtain it.

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 ("Get a formatted report") plus the precondition ("for a completed scan"), which is enough to distinguish it from fsv_scan and fsv_list_scans. It does not explicitly name a sibling or say where scan_id comes from, so it stops just short of full differentiation.

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?

Usage is only implied: the reader infers the tool applies to already-completed scans and infers format choice from the parenthetical hints ("for CI/code-scanning"). There is no explicit when-to-use/when-not statement and no pointer to alternatives such as fsv_fixes for remediation output.

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