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

Annotations already declare the mutation, destructive, and idempotent profile, so the description's added value is the partial-update semantics and the customer-visible consequence of price edits plus the user-confirmation requirement. These are real behavioral facts beyond the structured fields, though nothing is said about failure modes or what an update returns.

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?

Three short clauses, front-loaded with the action, then the partial-update rule, then the highest-risk caveat (price). No filler or restated title text.

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 10-parameter mutation with no output schema, the description covers the essentials an agent needs: partial-update behavior, itemId provenance, and the price-confirmation caution. Remaining operational details (workspaceId default, idempotency retry) are adequately handled in the schema.

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 every parameter already carries its own documentation (including the idempotencyKey retry protocol). The description only reinforces itemId's origin and price formatting/impact, which is marginal added meaning over 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?

States a specific verb (Change) and resource (catalogue item) and pins the itemId source to list_catalog, so it is clearly the edit counterpart to create_catalog_item/delete_catalog_item. It does not, however, distinguish itself from the nearby update_store_product sibling, which an agent must resolve on its own.

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?

"Only the fields you pass change" tells the agent this is a partial-update tool and that omitted fields must not be cleared, and the instruction to confirm price changes with the user is a concrete usage rule. No explicit when-not-to-use or alternative-tool routing is given.

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