Create Issue

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

Annotations already indicate destructiveHint=true. The description adds valuable behavioral context: it creates an issue, supports optional Epic/parent links, returns a JSON string, and raises ValueError if read-only or client unavailable. 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 well-structured with Args, Returns, and Raises sections, but it is slightly verbose. It does not repeat schema descriptions inecessarily, and every sentence adds value, though the Args list could be omitted since schema covers it.

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's complexity (7 parameters, multiple optional fields, return JSON), the description covers creation details, optional features, and error conditions. It does not mention authentication or project existence, but these are implied or handled by separate tools. The return format benefits from the output schema, so description is adequately 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?

Schema coverage is 100% with detailed descriptions for all parameters. The description adds no new semantic information beyond what the schema provides, staying at the baseline score for high coverage.

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 it creates a new Jira issue, with optional Epic link or parent for subtasks. It is specific about the resource and action, but does not explicitly distinguish from siblings like jira_batch_create_issues or jira_update_issue, though the verb and scope imply difference.

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 lacks explicit when-to-use or when-not-to-use guidance. It does not mention that for batch creation one should use jira_batch_create_issues, nor does it state prerequisites like being logged in. The error section hints at read-only mode but provides no direct comparative advice.

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