wafeq_items_update

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

Annotations already cover readOnlyHint, destructiveHint, and idempotentHint. The description adds no behavioral context beyond restating 'WRITE' and 'updates data'. It does not disclose full-update semantics such as omitted fields being reset, required prerequisites, or effect on existing related units of measure.

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 repeats the same information three times: the emoji line, 'Update item', and 'Endpoint for updating an existing item'. While short, the redundancy wastes tokens and does not add value beyond the first phrase.

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 complex nested body with many optional fields and a partial_update sibling, the description is far too thin. It does not explain full vs. partial semantics, the required 'name' field, or the behavior of omitted fields. No output schema exists, so the description should carry more weight.

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?

With 67% schema description coverage and a confusing body description ('Shared validation and save logic for item_units_of_measure...'), the tool description does not compensate. The endpoint path implies id means the item ID, but the body parameter's meaning and structure are not clarified beyond the 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 clearly identifies the operation as updating an existing item, including the HTTP method and resource path (PUT /items/{id}/). It does not explicitly distinguish from the sibling tool wafeq_items_partial_update, but the core purpose is 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?

No guidance is provided about when to use this full update versus wafeq_items_partial_update or wafeq_items_create. The description only restates that it updates an existing item, leaving the agent to infer selection criteria from the tool name and endpoint.

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