shopify_create_discount

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

Annotations already flag this as non-read-only, non-idempotent, and destructive, so the safety profile is covered. The description adds the audience and start-date scoping, which is mildly useful, but it does not disclose the confirm/authorization flow, the irreversible storefront impact implied by destructiveHint, or that it creates new resources without modifying existing ones.

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 single sentence is lean and front-loaded with the action, earning its place. However, for a 15-parameter tool with a confirm gate, this brevity shades into under-specification rather than efficient conciseness; an 'appropriately sized' description would need a few more sentences to cover the required confirmation and targeting options.

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?

The tool has high complexity (15 params, 6 required, confirm-gated, destructive annotation, no output schema), and the description explains none of this. An agent can guess the happy path but not how to satisfy the confirm parameter, whether productIds and collectionId are mutually exclusive, or what the side effects are. This is a significant completeness gap for a creation tool.

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 description coverage is only 7% (only 'confirm' has schema documentation), placing the full burden on the description. The description names percentage, start date, and customer audience, mapping to percentage, startsAt, and customerEligibility/customerSegments, but 12 other parameters—including productIds, collectionId, usageLimit, and minimumPurchaseAmount—receive zero semantic context from either source.

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 states a specific verb ('Create'), a specific resource type ('percentage discount'), and two distinguishing constraints ('explicit start date and customer audience'). It clearly differentiates from the product/collection creation siblings, though it does not name any alternative and leaves open whether other discount types exist.

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?

There is no guidance on when to use this tool versus alternatives. Siblings like shopify_graphql_mutation or shopify_bulk_update_product_status could conceivably overlap, and the description never states that this is the canonical way to create a discount, nor what conditions favor it over GraphQL.

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