delete_product

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

Annotations only supply destructiveHint and openWorldHint; the description goes well beyond by disclosing that hard delete cascades to variants and that synced products risk orphan listings unless unsynced first. The ordering prerequisite and cascading side effects are exactly the behavioral context an agent needs for a destructive op.

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?

Dense and front-loaded: the default behavior, the cascade, and the unsync prerequisite are all in the first two sentences. The trailing '[#020483]' tag is unexplained noise that slightly detracts from otherwise tight structure.

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 destructive 3-param tool with no output schema, the description covers side effects, ordering, and sibling routing well. It stops short of stating irreversibility/recovery (e.g. restore_product) or the scope of the undocumented workspace parameter, which are the remaining meaningful gaps.

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 33%, so only archive_only is documented inline ('Default false (hard delete)'); the description reinforces the archive-vs-hard-delete distinction with no schema help. The workspace parameter's scope and any restrictions on product_uuid remain undocumented in either place, so the description only partially compensates for the coverage gap.

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 and resource ('Delete (default) or archive a product') and immediately distinguishes itself from the archive_product and unsync_from_channel siblings. An agent can tell what this tool does without opening the schema.

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?

Gives explicit when/when-not guidance: unsync before hard-deleting a synced product, use unsync_from_channel for one channel and archive_product for all, and clarifies that sync_to_channel cannot unsync. This routes the agent among three siblings by name.

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