shopify_list_webhook_subscriptions

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

Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it describes the return format, restricts the result to 'active' subscriptions, and flags that 'effect' must be set to 'read' and is verified by the system. This goes beyond what annotations alone communicate, though it doesn't disclose pagination or rate-limit behavior.

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 main purpose is front-loaded in a single concise sentence, and the Args section is compact and scannable. Each parameter description earns its place given the lack of schema descriptions. A small deduction is warranted because a few arg descriptions feel like inherited boilerplate rather than tailored guidance (notably approval_ref's 'when resuming a write' on a read-only tool).

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?

Given the rich annotations, an output schema, and 6 mostly-optional parameters, the description is fairly complete. It states the return shape, scopes to active subscriptions, explains all parameters, and highlights the required 'read' effect. Missing items are minor: no explicit guidance on which project identifier (project_id vs project_ref) to prefer, and no pagination or limit details, but the output schema and annotations mitigate these gaps.

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 0% schema description coverage, the description's Args block carries the full burden of parameter explanation. It provides non-tautological descriptions for all six parameters, including 'Authenticated Project UUID', 'Project-bound connector account alias', and the critical constraint that effect 'must be read'. Some descriptions are generic or boilerplate (e.g., 'Stable business-action identity', 'when resuming a write' on a read-only tool), which prevents a perfect score, but it largely compensates for the empty schema descriptions.

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: 'List the shop's active webhook subscriptions', and even gives the expected return shape ([{id, topic, callback_url}]). The term 'active' adds useful scoping beyond the tool name, and the operation is clearly differentiated from sibling tools like shopify_create_webhook_subscription 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 usage is implied by 'List the shop's active webhook subscriptions' — an agent can infer this is for read-only inspection of configured webhooks. However, there is no explicit guidance on when to choose this over alternatives, no exclusions, and no mention of when not to use it, so the guidance remains implicit rather than direct.

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