update_work_item

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

With no annotations provided, the description carries full responsibility. It discloses critical behavioral details: the requirement to nest all updatable fields in updateWorkItemFields, the 30-second expiry of OSS temporary signed URLs when embedding images, and the restriction on modifying controlled system fields (fieldId 101587/101586). These go beyond standard expectations and are clearly communicated with a warning symbol.

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 paragraphs and bullet-like points. Every sentence serves a purpose: the main action, parameter nesting rule, image insertion workflow, and controlled field warning. It avoids redundant phrasing and is appropriately sized for the tool's complexity.

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 complex nested object and many fields, the description is thoroughly complete. It covers all relevant scenarios: standard updates, special image handling, and prohibited field modifications with alternative tool references. No output schema exists, but the description does not need to explain return values; it addresses all potential user questions and pitfalls.

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 already provides descriptions for all parameters, but the description adds significant meaning: it explains the mandatory grouping of update fields, the formatType implications for description formatting, and the exact field IDs that cannot be updated via customFieldValues. This enriches the schema information and helps avoid common mistakes.

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 'Update a work item' with the category [Project Management], listing the specific fields that can be updated (subject, description, formatType, status, etc.). It distinguishes itself from sibling tools like create_work_item and update_effort_record by specifying its scope and explicitly pointing to alternative tools for controlled fields.

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 when-to-use guidance: it is for updating work items, and it explicitly says NOT to use it for controlled fields (actual/estimated effort) and directs to create_effort_record/update_effort_record and create_estimated_effort/update_estimated_effort instead. It also includes a detailed workflow for inserting images via create_workitem_attachment, making usage conditions very clear.

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