shopify_create_product

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

Annotations already declare the destructive, non-read-only nature, so the description adds no new safety signal. It does add useful behavioral context: the default status is DRAFT, and collection membership is intentionally not handled. However, it does not disclose side effects, confirmation requirements, or response behavior beyond what the schema's confirm parameter hints at.

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 three short sentences with no filler. The core action is front-loaded, the default behavior is stated next, and the scope boundary regarding collections is noted last. Every sentence earns its place.

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, 13-parameter creation tool with no output schema, the description covers the main creation scope and an important default, but it remains terse. It omits return behavior, constraints around option-variant combinations, and what happens after creation, so it is adequate but not complete.

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?

With only 8% schema description coverage, the description carries more weight. It adds group-level meaning for options, variants, and images, and clarifies that the default status is DRAFT. However, it leaves most of the 13 parameters semantically underdocumented, such as price, vendor, tags, productType, and descriptionHtml, so it only partially compensates for the sparse schema.

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 uses a specific verb-resource pair ('Create a product') and explicitly enumerates the subresources it handles: options, variants, and images. It also previews the draft default and clearly separates collection membership from this tool's scope, distinguishing it from siblings like shopify_update_product or shopify_add_to_collection.

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 verb 'Create' and the statement that collection membership is a separate step imply when to use this tool, but no sibling tools are explicitly named and there is no explicit when-to-use/when-not-to-use guidance. The agent is left to infer that updates should go to shopify_update_product.

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