Update the quantity of an item in a shopping cart, including setting it to 0 to remove the item.
Update the quantity of an item in the shopping cart (0 to remove)
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Component slug ('shopId:itemId') | |
| quantity | Yes | New quantity (0 to remove item) |
Changes observed during successful MCP inspections.
v1.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry behavior. It does disclose a genuine behavioral trait — that quantity 0 removes the item — which is useful. However, it omits permissions/auth needs, whether an absent item is created or errors, and what the response looks like for a mutation tool.
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?
A single short sentence with zero waste, front-loading the action and scope and tucking the key edge case (0 = remove) into a parenthetical.
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 simple two-parameter tool with full schema coverage and no output schema, the description is nearly complete. Minor gaps remain around cart/session prerequisites and error behavior, but nothing an agent needs in order to call it correctly is missing.
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%, so both parameters (slug format 'shopId:itemId', quantity minimum 0) are already fully documented. The description's '0 to remove' restates what the quantity schema already says, adding no meaning beyond structured data, so the baseline 3 applies.
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 ('Update the quantity of an item in the shopping cart'), which is clear on its own. It does not explicitly distinguish itself from sibling cart_remove_item or cart_add_item, though the '(0 to remove)' note partially signals the overlap.
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?
Usage is implied: use this to change quantity, and set 0 to remove. There is no explicit guidance on when to prefer cart_remove_item over setting quantity to 0, nor prerequisites such as a valid cart session or whether the item must already exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.