product_duplicate

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

Annotations indicate readOnlyHint=false and destructiveHint=false, consistent with creating a new product. The description discloses that the new product inherits status='draft' and returns full payload with new_id and new title. No contradiction with 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 two sentences: the first states the action and endpoint, the second provides workflow guidance and return value. It is concise and well-structured without any wasted words.

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?

While the description covers the action, return value, and workflow, it lacks explanation of input parameters. With no output schema, it partially covers output but is incomplete for a tool with two undocumented parameters.

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 0%, but the description does not explain the two parameters (site and product_id). It only names the endpoint, which implies product_id but gives no details about their meaning or required format.

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 explicitly states 'Duplicate a product' and provides the HTTP endpoint. It distinguishes from siblings like product_create and product_update by specifying that the duplicate inherits status='draft' and suggests chaining with product_update.

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 advises using product_update after editing to make the duplicate public, which implies when to use and provides an alternative workflow. However, it does not explicitly state when not to use compared to product_create or other tools.

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