Создать товар

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

Beyond the annotations, the description discloses substantial behavioral traits: products are not published to any sales channel, ACTIVE status does not mean published, DRAFT marks a draft, failures come as userErrors with HTTP 200, and the default variant is included in the response. None of this contradicts the 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 dense but every sentence adds critical operational knowledge. It front-loads the core behavior and then systematically covers publication, status, pricing, limitations, idempotency, and error handling with no 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?

For a create operation with no output schema, the description covers all essential context: what is returned, how to proceed with pricing, how to publish, what is not created, duplicate behavior, and the unusual HTTP 200 error pattern. An agent has enough information to invoke the tool correctly and handle next steps.

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 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema, especially around status: ACTIVE is default but still unpublished, and DRAFT additionally marks the product as a draft. It also clarifies that the price is not set through this call but via a subsequent update_variant call.

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 creates a product and returns it with the default Shopify-created variant. It also explicitly separates this tool from related operations by noting it does not publish, set prices, or create variants/images/inventory, which distinguishes it from siblings like update_variant and graphql_request.

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 gives explicit when-not-to-use and alternative guidance: publishing must be done via graphql_request, pricing via update_variant, and variants/images/stock are not handled here. It also warns that repeated calls create duplicate products, which is critical usage context.

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