Move Inventory Between Locations

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

Annotations already declare this is a non-readOnly, non-idempotent, open-world, non-destructive mutation. The description adds meaningful behavior beyond that: it is a single transactional call that atomically decrements origin and increments destination, and both locations must already stock the variant. It does not cover auth needs, rate limits, or failure behavior, so not a 5.

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 front-loaded: the first sentence states the action and atomicity, the second states the prerequisite, and the third gives parameter guidance. Each sentence carries a distinct piece of information, and there is no filler.

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 9-parameter mutation tool with no output schema, the description covers the core behavior, prerequisite, and key ledger-state semantics. Annotations already carry the safety/idempotency profile, so the remaining gaps around sku alternates and reason/referenceDocumentUri usage are tolerable, though not fully complete.

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 67%, so the description needs to add value, and it does for ledger-state parameters: it explains pairing origin/destination states and recommends 'available' for most transfers. However, it calls that pair 'quantityName' while the schema fields are fromName and toName, and it does not clarify sku-vs-inventoryItemId, reason, or referenceDocumentUri. The added semantics are useful but imperfect.

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?

States a specific verb and resource: moving stock of one variant from one location to another. It adds the atomic behavior ('origin is decremented and the destination incremented together') and references shopify_set_variant_locations as a prerequisite, which helps distinguish this from a location-activation tool. The purpose is unambiguous without opening the schema.

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?

Provides clear usage context: both locations must already stock the variant, activate with shopify_set_variant_locations first, and for most stock transfers leave ledger states as 'available'. It does not explicitly contrast this tool with sibling inventory-mutating tools such as shopify_adjust_inventory or shopify_set_inventory, so it falls short of full when/when-not guidance.

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