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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: the state machine a scan moves through, that warnings are returned, and that evaluation results only appear once completed — useful for an agent deciding whether to re-poll.

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 well-formed sentence with the payload (status and lifecycle) front-loaded before the conditional evaluation detail. The nested parentheses are slightly dense but every clause carries information; nothing is redundant.

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?

There is no output schema, so the description must sketch the return shape — and it does, covering status, warnings, and the post-completion evaluation. For a one-parameter read tool this is close to sufficient; only the pre-completion behavior (what fields are absent while queued/running) is left implicit.

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?

There is a single parameter with 100% schema description coverage ('Scan id (scan_…)'), so the schema already carries the burden. The description adds nothing about the identifier's format or accepted values, so it stays at the baseline for a fully documented schema.

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 names a specific resource (a single scan) and enumerates its returned content: status lifecycle (queued → running → completed | failed), warnings, and the evaluation it produced. It doesn't explicitly contrast with siblings like get_test_run or get_site_status, but the mention of the evaluation's site-status/to-do-list output gives an agent enough to distinguish it from a generic status getter.

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?

No explicit when-to-use or when-not-to-use guidance, and no mention of run_scan as the tool that creates the scan this one polls. The status lifecycle implies a polling use case after starting a scan, but that inference is left to the agent rather than stated.

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