list_critical_findings

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

With no annotations supplied, the description carries the full burden, and it does disclose meaningful behavior: the result set is restricted to active findings and excludes three non-actionable statuses. It still omits read-only confirmation, result ordering, pagination/limits, and whether counts or truncation apply to large result sets, which matters for an unbounded list tool.

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 short sentences, zero filler, with the result-set definition front-loaded and parameter guidance after it. Nothing is redundant and every clause carries information.

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 not required, and the filter semantics are well covered. For a two-parameter filtered list tool, though, missing ordering, pagination, and product identifier format leaves gaps an agent could stumble on.

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%, so the description must compensate, and it does address both parameters — product scoping and the include_duplicates toggle with its default-false behavior implied. It falls short on how product is identified (name vs. ID/slug), which is the main ambiguity an agent would hit when calling.

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 verb and resource ("List actionable CRITICAL findings") and defines the filter precisely by enumerating excluded statuses (false-positive/risk-accepted/mitigated). It is clear on its own, but never distinguishes itself from siblings like list_findings_by_severity or list_duplicate_findings, leaving the agent to infer the boundary.

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?

It gives operational hints (scope to one product, set include_duplicates=True for duplicates), which is useful when-configuration. However it offers no when-to-use-vs-alternative guidance despite three closely related sibling tools, and no note that this is the narrowed 'critical only' view versus the severity-parameterized sibling.

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