update_item

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It only says 'Update an existing item', which implies mutation but does not reveal details about idempotency, partial updates, conflict handling, or side effects. This is insufficient for a write operation.

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 a single sentence with no redundancy. It is front-loaded and easy to parse. However, it may be overly terse given the tool's complexity (3 params, no output schema).

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 three required parameters including a version field and a nested object, and no output schema, the description is underspecified. It fails to explain the purpose of version for optimistic concurrency, the format of the data object, or what the tool returns. The sibling context shows many other tools, but the description does not help the agent choose correctly.

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 100%, so each parameter name and description is already documented. The tool description adds no extra meaning beyond the schema (e.g., does not explain how 'version' is used for conflict detection or what fields 'data' can contain). Baseline 3 is appropriate.

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 uses 'update' as the verb and 'existing item' as the resource, clearly indicating a modification operation. It distinguishes from sibling tools like create_item (creation) and delete_items (deletion), but lacks specificity about what type of item or any scope limitations.

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 on when to use this tool versus alternatives like manage_tags or manage_collections. The description only states the action without any context about prerequisites, when not to use, or trade-offs compared to other update-capable siblings.

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