update_price

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

With no annotations, the description carries the full behavioral burden. It does disclose that the update is processed via an async feed and explains the non-obvious rule that clearing a sale price requires sending nulls rather than omitting salePrice. However, it does not describe overwrite semantics, side effects, permission requirements, or how the async result is returned.

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 two dense sentences with no filler. The async feed nature and item structure are front-loaded, and the sale-price clearing rule is a critical operational detail that earns its place.

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 description gives enough to construct a valid-looking payload, which is significant given the schema is so thin. But because this is an async mutation with no output schema and no annotations, it leaves gaps around feed response semantics, status checking, field requirements, and error behavior.

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 0% and the schema only says products is an array of generic objects, so the description must compensate. It does by providing the full item shape including sellerSku, id, category, nested price/salePrice objects, and businessClients. It adds substantial meaning but leaves field types and requiredness implicit.

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 the verb and resource ('Update price') and adds that it is an async feed, making the core operation clear. It is specific about what is updated and gives the item structure, but it does not explicitly differentiate from siblings like update_products or update_stock, so it stops short of a 5.

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?

There is no guidance on when to use this tool versus alternatives such as update_products, update_stock, or create_products. The only usage hint is the sale-price clearing rule, which is more about parameter behavior than about selecting the right tool.

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