Create or update price list

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

Annotations already declare mutation, idempotency and non-destructiveness, so the bar is lower, and the description still adds real behavioral context: that title is required only on create, that remove_variants drops variants from the list, that 'sale' vs 'override' changes displayed pricing semantics, and that plain dates use the reporting timezone. It stops short of describing auth requirements, partial-failure behavior, or what a successful call returns.

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?

Four tightly packed clauses with no filler, front-loaded with the create-vs-update discriminator and then the sub-operation semantics. Every sentence carries information an agent needs to call the tool correctly.

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 10-parameter mutation tool with no output schema and only 60% schema description coverage, the description covers the operation mode, the two array operations, type semantics and date handling. Gaps remain on customer_group_ids scoping, status behavior on update, and error/partial-apply behavior, so it is strong but not exhaustive.

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?

With 10 parameters at 60% schema coverage, the description compensates by explaining the conditional role of price_list_id and title, the semantics of set_prices and remove_variants, and the sale/override meaning of 'type' plus the timezone convention for plain dates. It leaves customer_group_ids, status, description and starts_at/ends_at removal semantics to the schema, so it does not fully close the coverage gap.

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 the exact verb+resource and disambiguates the dual mode with a concrete rule: 'Without price_list_id creates a price list (title required); with price_list_id updates it.' It also enumerates the sub-operations (set_prices, remove_variants) so an agent can separate this from siblings like set_variant_price or list_price_lists without reading the schema.

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 gives clear context for choosing create vs update and for choosing set_prices vs remove_variants within the call. It never names an alternative sibling (e.g. set_variant_price for changing a single variant's price, or list_price_lists/delete_price_list), so routing to competing tools is left to inference.

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