Adjust quantity or add special instructions for a cart line using its cart-line ID, keeping its selected options. To change options, remove and re-add the item.
Set quantity and optionally instructions for a cart-line ID (not menu-item ID). Keeps its selected options. To change options, remove and re-add.
| Name | Required | Description | Default |
|---|---|---|---|
| cart_id | Yes | ||
| quantity | Yes | ||
| cart_item_id | Yes | ||
| special_instructions | No |
Changes observed during successful MCP inspections.
v0.1.1Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=false, destructive=false, idempotent=false, openWorld=true. Beyond that, the description adds real behavioral context: this is a partial update that preserves existing options, and option changes require a remove/re-add cycle. That is genuinely useful semantics not derivable from the annotations.
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?
Three terse sentences with zero waste; the set-quantity action and the ID disambiguation are front-loaded, followed by the option-preservation rule and the workaround. Every sentence earns its place.
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 mutation tool with no output schema and 0% schema description coverage, the description covers the non-obvious behavior (options preserved, change via remove/re-add) that an agent would otherwise guess wrong on. It leaves cart_id purpose and error behavior unstated, but those are minor.
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 0%, so the description must carry parameter meaning. It clarifies quantity (the primary set value) and special_instructions ('optionally instructions') and pins down cart_item_id as a cart-line ID rather than a menu-item ID, but says nothing about cart_id or the quantity bounds (1-99) beyond what the schema constrains.
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 (Set/update) and resource (quantity plus optional instructions on a cart-line), and crucially disambiguates cart-line ID from menu-item ID. It implicitly separates itself from remove_cart_item and add_cart_item via the options-change guidance, but never names a sibling explicitly.
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?
Clear context: use this to change quantity/instructions while preserving selected options, and the description tells the agent to remove and re-add to change options. Includes an explicit when-not path, though the sibling tools it implies (remove_cart_item/add_cart_item) are not named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.