Create or update variant

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description reveals partial-update semantics: variant fields can be changed without rewriting the item. It does not disclose response/return behavior, but with annotations covering safety and idempotency this is a manageable gap.

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?

Two sentences, front-loaded with the verb and resource, with no filler. The price-change use case earns its place as the most important practical guidance.

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 12-parameter upsert tool with no output schema, this is too spare. It explains the high-level create/update behavior but leaves the relationship among cost, purchase_cost, default_price, stores[].price, and option values unexplained, so an agent is likely to misuse parameters.

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 description coverage is only 17%; the description compensates minimally by explaining that variant_id selects an update and that price changes are the target use case. The other 10 parameters (sku, stores, options, pricing types, costs) get no semantic guidance.

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 names a specific verb and resource: create or update a variant on an existing item. It also differentiates from related upsert tools by noting that price changes can be done without rewriting the whole item.

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 a clear use case: use this to change a price without rewriting the whole item, which implicitly points to loyverse_upsert_item as the alternative. It lacks explicit when-not-to-use or exclusion conditions, so it stops short of a 5.

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