Update product (offer) lifecycle state

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

The description asserts 'Idempotent: no-op if the product is already in the requested state,' but the annotations declare idempotentHint=false. This is a direct contradiction on a behavioral trait an agent uses to decide whether retries are safe. The description also frames the operation as a benign visibility toggle while annotations mark it destructiveHint=true, further muddying the risk profile.

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 tight sentences with no filler; each sentence carries a distinct fact (rate limit, transition scope, archive exclusion, flag preservation, idempotency). The rate-limit caveat is placed first, which is slightly odd for front-loading but not wasteful.

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 mutation tool with no output schema and a nested payload/payload_file body, the description covers rate limits, the reachable state set, the excluded ARCHIVED state, flag preservation, and retry behavior. The nested body alternatives are documented in the schema. The one gap is that the idempotency claim is wrong, which undermines completeness on the retry-safety question.

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 100%, so product_id, state, account, confirm, payload, and payload_file are all documented in the schema itself, including the enum semantics of state. The description's only added parameter-adjacent value is the availability-flag preservation note, which is already duplicated in the state property description. Baseline 3 applies when the schema carries the load.

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?

States a specific verb+resource ('Transitions the product between PUBLIC and HIDDEN') and explicitly bounds the scope by naming what is NOT reachable here ('ARCHIVED is not reachable here'), which separates it from the sibling archive_product. An agent can distinguish this from toggle_product_availability and archive_product without opening any 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?

Gives explicit routing: use DELETE /products/{productId} to archive, use PUT /products/{productId}/availability to flip the sold-out flag, and this tool only moves between PUBLIC and HIDDEN. Both the when-to-use and when-not-to-use conditions are stated, along with the sibling operation for each excluded case.

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