Jira: Update Issue Fields

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

With no annotations provided, the description must carry the burden of behavioral disclosure. It confirms the tool mutates data ('Update') and mentions requirements for field IDs and value shapes, but lacks details on idempotency, validation, error handling, permissions, or response behavior. The caution about user picker requiring accountId adds some transparency.

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 three concise sentences. The first states the core action, the second lists supported features, and the third gives critical usage advice. No unnecessary words or repetition.

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, nested objects, no output schema), the description is somewhat incomplete. It does not explain return values or whether the tool returns the updated issue, nor does it mention prerequisites like issue existence or authorization needs. It covers the main action but lacks broader context.

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%, so baseline is 3. The description enhances parameter semantics by providing a concrete example ('user picker needs accountId') and warning about correct field IDs and ADF docs. This adds value beyond the schema's 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 verb 'Update' and the resource 'Jira issue fields'. It mentions the specific API endpoint and supported field types (customfield_*, ADF docs), which distinguishes it from siblings like jira_create_issue or jira_get_issue. However, it does not contrast with jira_bulk_edit_issues, but the singular focus is clear.

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 implies usage for updating single issue fields but does not explicitly state when to use this tool versus alternatives like jira_bulk_edit_issues. It provides cautionary guidance about correct field IDs and value shapes, but no explicit when-to-use/when-not-to-use criteria.

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