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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the exact effect of each operation ('add appends items', 'remove drops items by 0-based index', 'set replaces the full item list', 'clear empties the cart'), describes how the customer field merges details, and notes the checkout-in-progress constraint. It does not mention return values, errors, or permission requirements, but it covers the core mutation semantics well.

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 sentences, front-loaded with the core purpose, a terse but complete enumeration of operations, and a final constraint. Every sentence adds information without redundancy or filler. The structure is easy to parse and immediately actionable.

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?

The tool has 5 parameters, nested objects, and no output schema or annotations, which raises the completeness bar. The description covers operation semantics, the customer merge behavior, and the critical checkout-in-progress limitation. It also advises confirming with get_cart, implying the update may not return the updated state itself. However, it omits details about the return value, possible errors, and the exact item format, so it is not fully complete.

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 only 20%, so the description must compensate. It adds meaning beyond the schema by explaining the op enum ('add' appends, 'set' replaces, etc.), clarifying that indices are 0-based, and specifying that customer merges name/email/phone. The items parameter's role is implied through the op descriptions, though cart_id and the exact structure of items are not fully elaborated. This is stronger than the low-coverage baseline.

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 description opens with a clear verb+resource: 'Modify an open cart before checkout.' It then details the four operations (add, remove, set, clear), giving specific meanings for each. This distinctively separates it from sibling tools like update_checkout, which target a different resource.

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?

The description explicitly states when to use the tool ('before checkout') and provides a clear exclusion: 'Cannot modify a cart that already has a checkout in progress.' It also recommends a follow-up step ('Call get_cart afterwards to confirm'), but it does not explicitly name alternative tools for when the cart is not open or checkout needs modification.

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