Jira DELETE Request

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

With no annotations provided, the description carries full burden for behavioral disclosure. It adds valuable context about HTTP response codes ('Most DELETE endpoints return 204 No Content on success'), output format options, and provides API reference. However, it doesn't mention authentication requirements, rate limits, error handling, or destructive consequences of deletions.

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 clear sections (output format, common operations, API reference) and uses bullet points effectively. While comprehensive, some information like the API reference URL could be considered extraneous. Most sentences earn their place by providing actionable guidance.

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 this is a destructive DELETE tool with no annotations and no output schema, the description does reasonably well by covering common operations, response codes, and format options. However, for a tool that permanently deletes resources, it should more explicitly warn about destructive consequences and mention authentication/authorization requirements.

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 100% schema description coverage, the schema already documents all 4 parameters thoroughly. The description adds marginal value by mentioning outputFormat parameter options in the opening section and providing endpoint examples that relate to the path parameter. However, it doesn't significantly enhance understanding beyond what the schema provides.

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 the tool's purpose as 'Delete Jira resources' with specific verb+resource. It distinguishes from siblings (jira_get, jira_patch, jira_post, jira_put) by focusing exclusively on DELETE operations, and provides concrete examples of what can be deleted (issues, comments, worklogs, attachments, watchers).

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 clear context for when to use this tool by listing common DELETE operations with specific endpoint patterns. It implicitly distinguishes from sibling tools by focusing on deletion operations only. However, it doesn't explicitly state when NOT to use this tool or provide direct alternatives for specific scenarios.

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