shopify_set_inventory

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

Annotations already declare the tool destructive and non-idempotent. The description adds the compare-and-set protection behavior, explaining that the write is conditional and prevents stale overwrites, plus the necessity of a preceding read. This is meaningful behavioral context beyond the annotations. No contradiction exists.

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 exactly two sentences with no filler. The first sentence states the action and mechanism; the second delivers the key precondition. Every word serves a purpose, and the critical safety instruction is front-and-center.

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 description covers the core workflow—read first, then perform a compare-and-set write—and is appropriate for the main path. However, with 8 parameters, no output schema, and a destructive annotation, it leaves gaps such as what a successful set returns, how a compare conflict is reported, and the purpose of optional reason. The confirm requirement is only in the schema, not reinforced in the description.

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 13%, with only confirm having a description. The description's mention of compare-and-set and 'read first' provides some meaning for compareQuantity and quantity, but it leaves store, reason, inventoryItemId, locationId, and confirm's role largely unexplained in the description. The schema constraints give limits but not semantic intent, so the description does not sufficiently compensate.

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 clear action ('Set available inventory') with a specific resource and adds the compare-and-set mechanism, which distinguishes it from sibling read/compare tools like shopify_get_inventory_levels and shopify_compare_inventory. However, it doesn't explicitly tie back to the sibling set of tools or elaborate on the exact scope of 'available inventory.'

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?

'Read inventory first' is a direct, explicit precondition that tells the agent to obtain the current quantity before setting. It also implies the value for compareQuantity should come from that prior read, which is a valuable usage guideline. It doesn't explicitly mention alternatives or when not to use this tool, but the context of a guarded write is well conveyed.

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