Preview cart changes

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds real behavioral depth beyond that — per-item action prediction (add/increase/decrease/remove/none), refusal reasons, one product-page read per item capped at 30, and the caveat that prices and stock may change before applying. This is context an agent would otherwise have to infer.

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?

Front-loads the critical constraint ('without changing anything') and the per-item enumeration is dense but informative. The long compound sentences are slightly sprawling, though no clause is pure 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?

An output schema exists, yet the description still usefully previews the response shape and adds the staleness caveat and the 30-item/one-page-per-item cost model. For a read-only preview tool this is close to complete; minor gaps are already covered elsewhere.

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 100% and the nested item schema already documents productId, quantity (zero means remove), and cartItemId. The description only restates the 'products and total wanted, at most 30' semantics, adding little beyond the structured fields — baseline 3.

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 ('check products and the total... before changing the cart, without changing anything') and immediately frames itself as the dry-run counterpart to set_cart_item_quantity, which it names. An agent can distinguish it from mutation siblings like add_cart_item or clear_cart 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?

Clearly positions the tool as a pre-mutation check ('before changing the cart', 'before you apply it') and names set_cart_item_quantity as the action it simulates. It lacks an explicit when-not-to-use statement (e.g., that it shouldn't replace get_cart for a simple read), but the context is unambiguous.

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