product_update

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

Annotations already declare idempotentHint=true and destructiveHint=false. The description adds critical behavioral context: asset_ids are translated to a specific envelope, sending variants alone wipes all variants, overlapping attributes and translations cause rejection, and validation catches unknown keys before round-trip errors. It also mentions reversibility.

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 dense but well-structured with bullet points and clear sections for each argument shape. Every sentence adds value, though it is somewhat long. The front-loaded purpose and shape list help readability.

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 mutation tool with nested objects and multiple modes, the description covers most scenarios (side effects, validation, legacy support). It does not describe the output or return value, which is a minor gap given no output schema. Overall, it is fairly complete for an agent to use 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 coverage is 67%, but the description compensates by explaining the three argument shapes, listing allowed keys for each, warning about variants/asset_ids behavior, and clarifying the 'force' parameter. The site and product_id parameters are not elaborated, but the schema already provides basic descriptions.

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 starts with 'Update a product', clearly stating the verb and resource. It details three distinct argument shapes (attributes, translations, fields) and enumerates updatable fields, distinguishing it from sibling tools like product_create or product_delete.

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?

Provides extensive guidance: which argument shapes to use, their combinability, constraints (e.g., asset_ids translation, variants wipes with warnings, no overlapping translations and attributes), and prerequisites like checking price mode via ecommerce_settings_get. However, it does not explicitly state when not to use this tool versus alternatives.

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