get_top_blocked_issues

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

Annotations already declare readOnlyHint=true and idempotentHint=true, establishing a safe read operation. The description adds sorting behavior and grouping details but doesn't disclose return structure or edge cases. This is adequate but not extensive.

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?

The description is concise and well-structured with a clear one-line purpose followed by an Args list. Every sentence adds value, with no redundant phrasing.

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 value details are not needed. Annotations cover safety. The description covers all parameters and the core behavior. The main missing piece is usage guidance relative to sibling tools, but overall it is complete enough.

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 0%, so the description carries the full burden of explaining parameters. It provides meaningful context for each parameter, including defaults and the 'per product when grouped' clarification for limit. It doesn't elaborate on regex syntax for exclude_patterns, but the basics are covered.

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 clearly states the tool gets top blocked issues ranked by priority score, with a specific verb and resource. It distinguishes itself from siblings like get_top_active_issues by focusing on 'blocked' issues, though it doesn't explicitly name any sibling.

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 guidance is given on when to use this tool versus alternatives. The description only lists parameters without explaining the intended context or scenarios. Sibling tools like get_top_active_issues or get_at_risk_issues are not referenced, leaving the agent to infer usage.

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