Prepare Cart Change

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

Beyond the annotations it discloses that no cart mutation occurs, that a host approval gate follows, and that store text must be treated as untrusted display data — meaningful context for a tool in a prepare/approve/write flow. The only weakness is a mild tension with readOnlyHint=false: the description emphasizes 'without changing the store's cart', so an agent could reasonably infer a pure read, and the description never clarifies whether a pending operation record is created.

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?

Six short lines: purpose first, then one line per action, then display/trust/approval rules. No sentence is redundant, and the front-loading means an agent grasps the non-mutating nature before reading the branching rules.

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?

An output schema exists, so return-shape explanation is correctly omitted, and annotations already cover the safety profile. What remains — action routing, id provenance, quantity semantics, display obligations, untrusted-data handling, and the approval handoff — is all present, making the definition self-sufficient for correct invocation.

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 carries the whole burden and does it: it defines which fields belong to each action, where each id comes from (offer_id/product_id from get_product, cart_item_id from read_cart), and the critical semantic that quantity is the desired final value, not a delta. Format limits (patterns, max 999) are the only things left unsaid, and those are already encoded in the schema.

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 opening sentence names a specific verb and resource ('Prepare a ... review plan') and immediately constrains scope ('without changing the store's cart'), which is exactly what separates it from the write siblings add_to_cart/update_cart_item/remove_from_cart. An agent can distinguish it from every sibling without opening a 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?

It routes per action: add needs product_id + offer_id from get_product and defers to update when the item is already in the cart; update needs cart_item_id from read_cart plus a final quantity; remove takes cart_item_id only, and zero quantity is explicitly rejected as a removal. It also states the downstream condition ('the host must approve the matching write tool'), so both when-to-use and when-to-hand-off are explicit.

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