wit_update

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

With no annotations, the description itself must disclose behavioral traits. It does label the operation as a write requiring confirmation ('Escrita: write + confirm') and notes batch capability, but it does not describe what confirm does, whether updates merge or replace existing fields/tags, or how expectedRev affects writes.

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 short and front-loaded with the main operation; there is no filler. The second fragment 'Escrita: write + confirm' is cryptic and mixed-language, so the structure is efficient but slightly unclear.

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 8 parameters, nested objects, batch behavior, and no output schema or annotations, this description is underspecified. An agent lacks enough information to safely construct a call, especially around confirm semantics, id/ids selection, and tag/field update behavior.

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 only 38%, so the description needs to compensate. It names the updated entities (fields, state, tags) and hints that confirm is part of the write, but it leaves key semantics unexplained: singular id vs ids, nested tags add/remove behavior, and what confirm=true/false actually does.

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 states a clear action ('Atualiza') and a specific resource ('campos, estado e tags de um ou mais work items'), so an agent knows what the tool changes and that it supports single or batch targets. It does not explicitly contrast with sibling mutators like wit_link or wit_create, so it stops short of full sibling differentiation.

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 guidance is given for when to prefer this tool over wit_query, wit_create, wit_link, or other siblings. The only contextual hint, 'Escrita: write + confirm', alludes to confirmation but does not state conditions or alternatives.

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