Show Coordination Issue Workflow Issue

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

The annotations already declare the tool as readOnly, idempotent, and non-destructive. The description adds valuable behavioral context beyond these, such as the specific endpoint method (GET) and detailed access rules (project admins, issue creators, assignees, workflow members). No contradictions with annotations.

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 fairly concise but includes some redundancy (e.g., 'Returns a JSON object' after already stating returns). It is well-structured: begins with purpose, then access rules, then usage advice, then endpoint. Each sentence adds value, though could be slightly more streamlined.

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 the tool has 8 parameters (no output schema) and strong annotations, the description covers the essential context: what it does, who can use it, required parameters, and the endpoint. It does not explain optional parameters or pagination, but the input schema covers those fully. The access rules and endpoint specification make it fairly complete.

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?

The input schema has 100% description coverage for all 8 parameters. The description only lists the three required parameters (company_id, project_id, id) and mentions the endpoint path structure. It does not add additional meaning or elaboration on any parameter, so the baseline of 3 is appropriate.

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 that the tool returns a specific Coordination Issue with workflow metadata. It distinguishes from the sibling tool 'show_coordination_issue' (which is for non-workflow issues) by explicitly mentioning 'workflow metadata' and the endpoint path containing 'workflow_issues'. The title and description together convey a specific verb+resource combination.

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?

The description provides detailed access control rules, explaining who can use the tool. It also advises to use it for fetching full details of a specific Coordination Issue by identifier. However, it does not explicitly contrast with alternative tools like 'show_coordination_issue' or state when not to use it, leaving some ambiguity among the similar showing tools.

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