shopify_create_webhook_subscription

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

Annotations already carry the base profile (readOnlyHint=false, idempotentHint=true, destructiveHint=true), and the description adds useful context through its args: effect is 'claimed read or write effect; Spring verifies it', approval_ref is used 'when resuming a write', and idempotency_key is a 'stable business-action identity'. This hints at an approval-gated write flow. It does not contradict the annotations, though it doesn't explain the end-to-end approval behavior or what happens on duplicate subscriptions.

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 purpose is front-loaded in two crisp sentences before a tidy per-parameter Args block. No filler or repetition exists, and the Args block earns its space because the schema itself carries zero descriptions. Slightly long overall, but every line contributes information the agent needs.

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?

An output schema exists, so return-value documentation isn't needed. The description covers what the tool does, the key business parameters, and hints at the write-approval mechanism. Gaps remain: the required-vs-optional discrepancy between description and schema isn't reconciled, the approval flow (when approval_ref is actually needed) is only implied, and there's no guidance on duplicate or overlapping subscriptions.

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 0%, placing the full documentation burden on the description, and it fully compensates: all 9 parameters receive prose beyond their names. Especially strong are idempotency_key ('Stable business-action identity'), effect ('Spring verifies it'), and approval_ref ('when resuming a write'), which convey semantics the bare schema cannot. The description also meaningfully marks topic and callback_url as required even though the schema lists zero required parameters.

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 and resource ('Subscribe to a Shopify webhook topic... delivered to an HTTPS callback URL') with concrete examples (ORDERS_CREATE, PRODUCTS_UPDATE). The added purpose clause ('Use to sync order/product events back to the platform') clarifies why an agent would invoke it, and the action clearly distinguishes it from sibling tools like shopify_list_webhook_subscriptions and shopify_delete_webhook_subscription.

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 a clear use context ('sync order/product events back to the platform'), so an agent can infer when this tool is relevant. However, it names no alternatives, gives no when-not-to-use guidance, and doesn't mention preconditions like checking existing subscriptions (shopify_list_webhook_subscriptions) before creating a duplicate.

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