jira_create_issue

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing beyond the word 'Create'. It does not mention that 'summary' is the only required field, that a project key falls back to a default, what the call returns (the new issue key, needed for follow-ups), or any permission/auth requirements. For a mutation tool with zero annotation coverage this is a significant gap.

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, purpose front-loaded, with the use cases earning their place by routing the agent from analysis siblings to this action tool. No filler or redundancy.

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 an 8-parameter mutation tool with no annotations and no output schema, the description is under-specified: it omits the required-field constraint, the default project fallback behavior, and any indication of the return value. An agent could call it, but not confidently or correctly in edge cases.

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?

With only 50% schema description coverage, half the parameters (labels, summary, description, assigneeAccountId) have no documentation in either the schema or the description. The description adds no parameter guidance at all, so it fails to compensate for the coverage gap.

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 states a specific verb and resource ('Create a Jira issue'), which is unambiguous and clearly distinguishable from siblings like jira_update_issue or jira_get_issue. It does not explicitly name those siblings, but the verb+resource pairing is precise enough that the agent knows what the tool does.

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 second sentence gives concrete triggering scenarios: filing bugs after analysis, opening tickets for RCA action items, and creating stories from implementation plans. This connects well to sibling tools like analyze_bug and generate_rca, giving clear context for when to reach for it, though it names no exclusions or explicit alternatives.

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