Stop product sales across channels

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the agent knows this is a mutating operation. The description adds the 'Preview' option, suggesting a non-destructive dry-run mode, which provides some behavioral context. However, it doesn't disclose what exactly gets destroyed, approvals required, or external side effects, so it adds limited value beyond annotations.

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, concise sentence with no redundant words. It is front-loaded with the action ('Preview or stop') and resource ('product'), making it easy to parse. While it is brief, it is well-structured and to the point, though it misses details that might have made it even more useful.

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 the complex nested schema with 7+ parameters, safety mechanisms (idempotency key, approval token, expected external IDs), and an output schema, the description is far too sparse. It fails to explain the preview/execute workflow, multi-channel behavior, approval requirements, or any safety considerations. The description covers only the basic action, leaving the agent without essential operational context.

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 0%, and the description does not compensate by explaining any parameters. It only mentions 'every selected channel' which relates to the 'channels' parameter, but leaves sku, confirm, dry_run, approval_token, idempotency_key, and expected_external_ids undefined. The schema has minimal descriptions beyond field names, so the agent gets no semantic guidance for these critical parameters.

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 states the tool's function: to preview or stop a product on selected channels. The verb 'stop' and resource 'product' distinguish it from sibling tools like product_publish or product_resume, though it doesn't explicitly name them. The 'preview' aspect adds a mode, which is slightly ambiguous but still conveys the primary intent.

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?

The description offers no guidance on when to use this tool versus alternatives. It implies usage for stopping product sales, but does not mention when not to use it, prerequisites, or contrast with sibling tools like product_delete or product_resume. There is no explicit context for selecting this tool over others.

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