set_product_tiers

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

With no annotations provided, the description carries the full behavioral burden, and it delivers substantial detail: how tiers affect the product and variants without their own breaks, how line price steps down to the highest reached break, that cart and order both use that price, that prices are minor units, and that an empty array removes breaks. It does not mention permissions, reversibility, or error behavior, but it discloses the most consequential side effects of calling the 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?

The description is compact and front-loaded, starting with exactly what the tool does, then clarifying scope, pricing behavior, and deletion semantics. Every sentence adds necessary information, and there is no filler or repetition of schema content beyond what is useful for decision-making.

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 semantic complexity of volume tiers, inheritance across variants, price stepping, and clearing behavior, the description covers the essential operation well. It lacks an explicit note about required parameters or success/error responses, and there is no output schema to convey return values, but the core calling decision is fully supported.

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 input schema has 100% coverage: recordId and tiers both have descriptions, and tiers includes constraints like minQty >= 2, max 10 items, price in minor units, and ordering semantics. The description does add some context about inheritance and line-price stepping, but that is behavioral rather than parameter-level; it does not materially improve on what the schema already documents for the two parameters. Baseline 3 is appropriate.

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 verb and resource: it 'Set[s] the record-level volume price breaks on a product (B2B quantity discounts).' It clearly distinguishes this tool from variant-level pricing by explaining that a variant's own breaks are set with the variants payload, not here. The empty-array removal behavior is also explicitly stated, leaving no ambiguity about what the tool accomplishes.

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 gives explicit usage context: use this for record-level product breaks, which apply to the product and any variant without its own breaks. It also states a when-not and alternative: variant-specific breaks belong in the variant's definition, so 'set those with the variants payload.' This is clear routing relative to alternatives, even though no sibling tool directly duplicates this function.

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