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

This is where the definition earns its keep. Annotations only say readOnlyHint=false, destructiveHint=false and idempotentHint=false; the description goes further by disclosing that the call mutates nothing on its own, that it returns a preview plus a confirmation link, and that only the merchant can finalize it. That tells the agent the two-phase flow and that it must surface the link rather than assume the edit landed.

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?

Four short sentences, no waste, and the most decision-relevant fact (this call changes nothing yet) is stated up front. The unit convention and the confirmation constraint each appear exactly once.

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 ten-parameter mutation with no output schema, the description supplies the critical missing piece: what the call actually returns and who completes the write. Field-level behavior is well covered in the schema, so remaining gaps (error handling, what happens on an invalid handle) are minor.

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 70%, and the per-field descriptions already carry the destructive nuances (tags and collections REPLACE, downloads KEEP-then-remove, status enum effects). The description adds one useful unit convention, money in integer minor units, though no price parameter appears in this schema. Baseline 3 is appropriate given the schema does most of the work.

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?

"Change a product" gives a specific verb plus resource, and the description immediately clarifies the surprising part: the call stages rather than applies a change. It does not distinguish this from siblings like products_set_status or products_bulk_price_edit, so an agent must infer the boundary from those names alone.

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?

Usage is implied rather than stated: the wording 'change a product' implies an existing product, and 'Only the merchant, on that page, can make it happen' implies the agent's role ends at proposing the change. There is no explicit guidance on when to prefer products_set_status, products_add_download, or products_bulk_price_edit instead.

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