Jira PUT Request

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

With no annotations provided, the description carries full burden and delivers substantial behavioral context. It discloses that PUT 'replaces the entire resource' (important destructive behavior), provides cost optimization guidance about token usage, explains output format options, and references the API documentation. It doesn't cover rate limits or authentication requirements, but provides significant operational guidance.

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 (important notes, output format, common operations) and uses bold formatting effectively. Every sentence adds value - from the core purpose statement to practical examples and optimization advice. It could be slightly more front-loaded, but overall demonstrates efficient information density without wasted text.

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 complex mutation tool with 5 parameters, no annotations, and no output schema, the description provides substantial context. It covers the destructive nature of PUT operations, gives practical examples, explains parameter interactions, provides optimization guidance, and references external documentation. The main gap is lack of explicit information about authentication requirements or error handling, but overall it's quite comprehensive.

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 baseline would be 3, but the description adds meaningful context beyond the schema. It provides concrete examples of common operations that map parameters to real use cases (e.g., how path and body combine for issue updates), explains the 'jq' parameter's importance for cost optimization, and clarifies the practical implications of outputFormat choices. This adds substantial semantic value.

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 explicitly states 'Replace Jira resources (full update)', providing a specific verb ('Replace') and resource scope ('Jira resources'). It distinguishes from siblings by noting 'For partial updates, prefer PATCH' and contrasts with jira_patch. The description goes beyond the name/title by explaining the full update nature and return format.

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 explicit guidance on when to use this tool vs alternatives: 'For partial updates, prefer PATCH' directly references the sibling jira_patch tool. It also includes 'Common operations' with specific endpoint examples, giving practical context for when to apply this PUT method. The cost optimization advice further guides usage decisions.

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