Add to cart

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

With no annotations, the description carries the full burden, and it delivers meaningful behavioral insight: per-item failures (out of stock, unknown SKU, configurable products needing options) are collected in user_errors instead of failing the entire call. It also discloses the return shape (updated cart with line items and totals). It does not cover aspects like cart validation or quantity merge semantics, but the disclosed error model is substantial and actionable.

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 dense sentences, front-loaded with the primary action, followed by return value and error-handling behavior. Every sentence contributes essential information with no filler or repetition.

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?

Since there is no output schema, the description explicitly states what is returned (updated cart with line items and totals) and how errors are surfaced (user_errors). It covers the main invocation outcome and the partial-failure behavior. It is slightly light on prerequisites and edge cases, but for a two-parameter guest-cart tool this is a solid, usable description.

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?

The schema has 100% description coverage, with clear explanations for cart_id, items, sku, and quantity. The description adds only an echo of 'by SKU and quantity' and does not supplement parameter meaning beyond the schema. Baseline 3 is appropriate because the schema already documents parameters fully.

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 specific verb and resource: 'Add one or more products (by SKU and quantity) to a guest cart.' It clearly distinguishes this from sibling tools such as view_cart, check_stock, and create_guest_cart. The mention of returning the updated cart with line items and totals further pins down the tool's role.

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 makes the use case clear: adding products to a guest cart. It implies a prerequisite via 'guest cart' plus the schema's reference to create_guest_cart, but it does not explicitly state when to avoid this tool or name alternatives. Still, the context is clear enough for an agent to know this is the relevant action for populating a cart.

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