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

readOnlyHint=true already covers the safety profile, and the description usefully adds ordering and the shape of returned content (details plus example URLs). However, "All issues" conflicts with the limit parameter's default of 25, so the description overstates completeness and hides truncation behavior, which is a real gap for an agent reasoning about coverage.

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 with zero filler, front-loaded on what is returned before moving to ordering and then filtering. Every clause carries information an agent needs.

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?

With four parameters, no output schema, and only a readOnlyHint annotation, the description should do more: it never explains truncation/pagination (limit), what an empty result means, or the required scan_id's provenance. It conveys return shape and ordering but leaves the agent guessing about result coverage.

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 75% and the schema already documents category examples, the severity enum, and limit's default, so the baseline applies. The description's "filter by minimum severity or category" restates rather than extends the schema, and the required scan_id is undocumented in both places.

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 sentence names a concrete resource (issues) scoped to a specific origin (a completed scan) and adds ordering and payload hints ("most severe first, with details and example URLs"). It is unambiguously different from get_scan/list_scans/scan_site by resource, but never explicitly routes the agent away from those siblings.

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?

"Completed scan" implies a precondition (the scan must have finished) and the last clause names two supported filters, so usage is implied. There is no explicit when-to-use versus get_scan, no guidance for an in-progress scan, and no statement of the alternative when the agent wants raw scan metadata.

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