list_issue_statuses

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds one behavioral detail beyond them — that results are 'grouped by phase' — which hints at the response shape, useful since there is no output schema. It does not cover ordering, whether archived/closed statuses are included, or scoping.

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 front-loaded sentence with no filler; the parenthetical is the only elaboration and it earns its place by clarifying 'statuses'. Brevity here is close to the minimum, leaving little room to be wasteful.

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?

For a simple read-only list tool, the core purpose is covered and annotations carry the safety profile. Gaps remain: the meaning of the undocumented 'workspace' param, whether all phases/statuses are included, and any result shape detail beyond 'grouped by phase', especially since no output schema exists.

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% for the single 'workspace' parameter, so the description would ideally explain what it scopes and whether omission means a default workspace or all workspaces. It says nothing about it; however, with only one optional parameter and a well-understood concept ('workspace'), the baseline-3 penalty for a thin single-param tool applies rather than a full failure.

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 gives a specific verb and resource ('List all issue statuses') and disambiguates the domain term with '(workflow states)', which tells an agent these are statuses of an issue workflow rather than e.g. HTTP statuses. It does not explicitly differentiate from siblings, but the resource name is distinctive enough that confusion with list_labels or list_components is unlikely.

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?

There is no guidance on when to call this versus alternatives, nor on prerequisites or follow-up use (e.g. obtaining status IDs before calling update_issue or move_issue). The use case is only inferable from the verb 'List' plus the resource, with no exclusions or context stated.

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