Create variant

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

No annotations are provided, so the description carries the full burden. It states the action 'create' and a prerequisite ('existing product'), but it doesn't disclose permissions, reversibility, or response behavior. The pointer to get_operation_schema is a mitigating factor but doesn't compensate for missing behavioral detail.

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?

Two sentences, front-loaded with the core purpose, and each sentence earns its place. The second sentence directs users to get_operation_schema, which is useful and concise.

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 creation tool with an open nested object and no output schema, the description effectively points to get_operation_schema for the exact request shape and specifies required fields. It could mention response details, but the pointer makes it reasonably complete for invocation.

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?

The single parameter 'variant' is described in the schema as matching CreateVariantRequest with required name/product_id, and the description repeats this and hints at pricing/stocks/media. Since schema coverage is 100%, the description adds little beyond the schema, but the hint about optional fields is a small value-add.

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 'Create a new variant (sellable item) under an existing product,' using a specific verb and resource, and distinguishes it from sibling tools like create_product and update_variant by specifying 'under an existing product.' It also notes required fields, adding further clarity.

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 conveys the context: it's for creating a variant linked to an existing product, and it advises calling get_operation_schema for the exact request shape. However, it doesn't explicitly contrast with alternatives like update_variant or variant_action, so some inference is required.

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