jira_update_custom_fields

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, openWorldHint=true. The description does not contradict them. It adds some context about routing only through the project/account governed connector authority, and it mentions Spring verifies the claimed effect, which is a behavioral nuance beyond annotations. However, it does not describe what happens to existing values, whether the update is a merge or replace, or what failure/approval conditions apply beyond approval_ref.

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 reasonably sized and uses a bullet list for parameters, which aids scanning. However, the first lines repeat the tool name and platform tool name, which adds little value. The parameter bullet definitions are concise but some are vague. It is not bloated, but it is not tightly front-loaded either.

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 7 parameters, 0% schema coverage, and no explanation of the `arguments` JSON payload, the description leaves critical gaps. There is an output schema, which helps understand return shape, but callers still cannot know how to construct a valid custom-field update, what fields are permitted, or how approval/effect interplay works. For a write tool with destructiveHint=true, this is incomplete.

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 description coverage is 0%, so the description bears full responsibility for parameter meanings. It provides one-line bullet definitions for parameters, but they are largely restatements of parameter names ('project_id: Authenticated Project UUID', 'idempotency_key: Stable business-action identity'). It does not explain the format of the `arguments` JSON string, how to structure custom field updates, or the relationship between effect, approval_ref, and the write path. This is insufficient for correct invocation.

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 identifies the operation as `jira_update_custom_fields` and states it updates custom fields for a Jira connector operation, which is a specific verb + resource. It doesn't fully explain what custom field data is modified or the business result, but the name and the 'connector operation' framing give reasonable purpose clarity. It distinguishes itself somewhat from generic Jira updates by naming the platform tool, though it doesn't explicitly contrast with siblings 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?

No explicit guidance on when to use this tool versus jira_update_issue, jira_bulk_transition, or similar Jira tools. The description mentions routing through a governed connector authority, but that is a constraint, not a usage guideline. There is no when/when-not or alternative-selection logic.

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