update_issue

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

With no annotations provided, the description carries the full burden of behavioral disclosure. While it correctly identifies this as an update operation, it doesn't mention important behavioral aspects like what permissions are required, whether the update is atomic or partial, what happens to unspecified fields, or error conditions. The tip about custom fields adds some context but doesn't compensate for the lack of mutation-specific behavioral information.

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 appropriately brief with two sentences, both of which add value. The first sentence states the core purpose, and the second provides a practical tip. There's no wasted verbiage, though it could be slightly more structured with clearer separation between purpose and 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?

For a mutation tool with 7 parameters, no annotations, and no output schema, the description is minimally adequate. It identifies the operation type and provides one helpful tip, but doesn't address important contextual aspects like what the tool returns, error handling, or how it differs from similar mutation tools in the sibling set. The lack of output information is particularly notable given there's no output schema.

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 schema description coverage is 100%, so the schema already documents all 7 parameters thoroughly. The description adds minimal value beyond the schema - it mentions 'fields' generally and provides a tip about custom fields, but doesn't explain parameter interactions, constraints, or provide additional semantic context that isn't already in the parameter descriptions.

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 action ('Update fields') and resource ('existing Jira issue'), making the purpose immediately understandable. However, it doesn't explicitly differentiate this tool from similar siblings like 'assign_issue' or 'transition_issue' which also modify issues, missing the highest level of sibling distinction.

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 a helpful tip about using 'get_create_metadata' to discover custom fields, which gives some context about when this tool might be needed. However, it doesn't explicitly state when to use this tool versus alternatives like 'assign_issue' or 'transition_issue' for specific modifications, nor does it mention prerequisites or exclusions.

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