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

Adds real behavior beyond the annotations: the returned cart_access_token must be retained for get_cart/update_cart, sign-in/approval/payment are delegated to Shop, and no order is placed. It does not address retry semantics (annotations declare idempotentHint=false, so repeated calls presumably create duplicate carts) or what a failed creation returns — a minor gap given annotations already carry the safety profile.

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?

Five tight sentences, purpose front-loaded, then token retention, then the branching guidance, then the negative guarantee. Every sentence changes what the agent would do; nothing is restated from the title or annotations.

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 non-idempotent mutation tool with no output schema, the description still discloses the key returned artifacts (cart_access_token, agent_checkout) and the handoff flow. What remains thin is the shape of the required `cart` payload, which an agent must infer from the schema alone.

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 coverage is 50% — only `meta` is documented in the schema. The description's "live variants and quantities" loosely maps to line_items[].item.id and quantity, but says nothing about the 1–25 item bounds, the quantity 1–999 range, or the opaque `context`/`signals` nested objects. Baseline 3 fits: some value added, but the coverage gap is not compensated.

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?

Specific verb + resource ("Create a Shopify-owned cart") with the precondition ("after buyer confirmation of live variants and quantities") stated up front. It is clearly separable from create_checkout, which the description names as the alternative path.

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?

Explicitly routes the agent: agent-authorized purchase → returned agent_checkout route in the buyer's Shop MCP connection; otherwise → Commonlands create_checkout for a payment link. Sibling alternatives and their selection conditions are both named, plus the negative case ("places no order").

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