shopify_update_collection

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

Annotations include readOnlyHint=false, destructiveHint=true, idempotentHint=true. The description mentions 'effect: Claimed read or write effect; Spring verifies it.' but is otherwise silent on behavioral details. Even though annotations flag destructive=true, the description doesn't explain what can be destroyed (e.g., replacing a description, potentially removing products?) or any irreversible consequences. With annotations present, the bar is lower, but the description adds very little contextual behavior beyond what annotations already provide. There's no contradiction though.

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 reasonably concise, one line of purpose followed by a terse args list. It front-loads the core purpose effectively. However, the args list mixes field explanations with field semantics; some explanations are obvious from the schema (title, description_html) and add little, while some are terse. Every line earns its place, but a few could provide more useful semantics.

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 tool with 10 params, 100% schema coverage, and no required parameters, the description identifies the core operations. But it doesn't guide the agent on required vs optional fields (the schema says all have defaults and none required—risky for an update operation where at least one field should change). It doesn't mention what 'destructive' means here, or whether this operation supports removing products or only adding. Given an existing output schema, not explaining return values is fine. The overall picture is adequate but with notable gaps around semantics of effect/approval_ref/idempotency_key.

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%, so the description carries the burden for parameter meaning. The description does list each parameter with its args style, including clarifying notes like 'Collection ID (numeric or GID)', 'Product IDs (numeric or GIDs) to add to the collection', 'HTML allowed' for description_html, and 'Stable business-action identity' for idempotency_key. This adds meaning beyond the bare schema property names. The coverage is incomplete—several parameters (effect with 'Spring verifies it', approval_ref 'when resuming a write') are cryptically explained. The description adds meaning but is quite telegraphic.

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 a specific verb+resource: 'Update a Shopify collection's title/description and/or add products to it.' It distinguishes from sibling tools like shopify_create_collection and shopify_list_collections by naming the specific update operations. However, it doesn't explicitly differentiate itself from other Shopify update tools like shopify_update_menu or shopify_update_page, though the resource 'collection' makes the distinction fairly evident.

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 implies usage through its parameter list—use this when you need to modify title, description, or products of an existing Shopify collection. It doesn't explicitly state when not to use alternatives, such as when needing to create a collection or update other Shopify resources. There's no explicit guidance on when to use shopify_create_collection vs this tool, leaving some inference required.

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