project_backlog_report

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

Annotations already declare readOnlyHint=true, so the description's mention of report contents (zombie issues, TODOs, stale issues, etc.) adds context about the output scope. No need to reiterate safety. Provides value by detailing what the report covers.

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?

Single sentence, informative, no redundant words. Front-loaded with action and key deliverables.

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?

Given 5 parameters with full schema coverage, the description sufficiently outlines the report's composition. However, it lacks indication of the output format (e.g., text, table, JSON) and any post-usage side effects, though readOnlyHint mitigates concern.

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 100%, so baseline is 3. The description does not add any additional meaning to the parameters; it simply describes the overall output without referencing input parameters like repo or staleThresholdDays.

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?

Describes specific action (generate comprehensive backlog health report) and lists distinct components (zombie issues, TODOs, stale issues, priority distribution, health score). Clearly differentiates from sibling tools like project_scan_todos and project_scan_zombies which focus on individual aspects.

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?

States the tool generates a comprehensive health report, implying use for an overview, but does not explicitly specify when to use over siblings or provide exclusion criteria. Lacks clear when-to-use or when-not-to-use guidance.

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