Delete issue

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

Annotations already mark destructiveHint=true and readOnlyHint=false, and the description goes much further by specifying irreversibility, lack of undo/trash, destruction of comments/worklogs/attachments, and the JIRA_ALLOW_IRREVERSIBLE=true server requirement. It also clarifies that plan mode still works without the flag, adding operational nuance needed for a destructive call.

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?

Five sentences each carry required information: purpose, irrevocability, server requirement, subtask caveat, and a safer alternative. The most critical warning ('IRREVERSIBLE') appears immediately after the purpose, and the content is front-loaded with no filler or tautological phrasing.

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 destructive tool with no output schema and rich annotations, the description supplies the missing decisions: whether the operation is safe, what server config is needed, how plan mode behaves, and how subtasks are handled. Combined with the schema's parameter details, an agent has enough to select and correctly invoke it, including the need to obtain a plan_id first.

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 already documents all 5 parameters with 100% coverage, including apply's plan/execute distinction and deleteSubtasks' default refusal behavior. The description adds value by tying these to the workflow, e.g., plan mode shows what would be destroyed and execution requires the server flag, which the raw schema does not convey. It repeats some schema content but adds useful operational context.

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 opens with 'Permanently delete one issue' – a specific verb, resource, and irreversibility qualifier. This clearly distinguishes jira_delete_issue from sibling delete tools like jira_delete_comment and jira_delete_worklog, and from mutation tools like jira_update_issue.

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 gives concrete when-not guidance: 'Consider closing the issue instead' and explains that an issue with subtasks is refused unless deleteSubtasks is true. It does not explicitly name the alternative tool (jira_transition_issue) or enumerate all conditions where this tool should be preferred, but the conditional and alternative guidance is strong.

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