set_cart_quantity

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

No annotations are provided, so the description fully carries the behavioral burden. It discloses that Ozon reports no outcome, so the cart is read back, and explains the meaning of 'ok=false' with 'detail'. It also discloses the gating by writes_enabled and the edge case of out-of-stock or base SKU without size.

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?

The description is dense but efficient; every sentence serves a purpose. It front-loads the core purpose, then explains the unified behavior, response semantics, and workflow caveats without redundancy.

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?

Given the output schema exists, the description doesn't need to explain return structure, but it goes further to explain the ok=false semantics and the gating condition. It also covers the apparel edge case and the distinction from order selection, making it complete for correct invocation.

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 coverage is 100%, with clear descriptions for both sku and quantity. The description reinforces the quantity=0 removal behavior but does not add substantial parameter-specific meaning beyond the schema. The variant SKU note is already in the schema, so the description adds no extra parameter insight.

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 states a specific action ('Set how many of a product are in the cart') and clarifies that adding, changing, and removing are all handled by this single call. It distinguishes itself from siblings like get_cart (view) and select_cart_items (select for order) by defining its unique role in the cart workflow.

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?

It explicitly says when to use it (to modify cart quantity), and clarifies the relationship with select_cart_items by noting that being in the cart is not being in the order and that select_cart_items should be called before checkout. It also guides on using the variant SKU for apparel, pointing to product_details() as the source.

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