update_work_item

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

With no annotations, the description carries the full burden of behavioral disclosure. It does offer some useful context: it states the return type ('Updated WorkItem object') and explains the description_stripped behavior (wrapped into HTML, ignored if description_html is set). However, it fails to disclose critical update semantics such as whether unspecified fields are reset or preserved, whether the operation is a partial merge or full replacement, or any permission requirements. The partial transparency earns a middle score.

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 structured with a one-line purpose, a clean Args list, and a Returns line. The list is long (20 parameters) but necessary given the lack of schema descriptions. Every parameter has a brief, to-the-point annotation, and the note about description_stripped is concise. It is not verbose despite its length.

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 tool with 20 parameters, no annotations, and an output schema that likely describes the return value, the description covers all parameter meanings and states the return type. However, it omits key behavioral context such as how partial updates are handled, whether fields are nullable (though schema shows many nullable), and what fields are mutually exclusive (e.g., description_html vs description_stripped). The lack of usage guidance further reduces completeness, making it adequate but not thorough.

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 must compensate, and it does. Each parameter is listed with a concise semantic annotation, including explicit enum values for priority, date format for start_date/target_date, and the nuanced explanation of description_stripped behavior. While some entries are tautological (e.g., 'name: Work item name'), the overall coverage is strong and adds real meaning beyond the bare schema.

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 opens with 'Update a work item by ID,' which is a specific verb+resource statement. It clearly distinguishes this tool from create, delete, and retrieve work item operations, as well as from more specialized updates like update_work_item_comment or update_work_item_property. The required work_item_id parameter makes the scope unambiguous.

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 no guidance on when to use this tool versus alternatives. It does not mention that this is for modifying existing work items, nor does it compare against create_work_item, update_work_item_property, or other related update tools. There are no explicit when-to-use or when-not-to-use instructions, leaving the agent to infer usage from the tool name alone.

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