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

The annotations only say readOnlyHint=false, destructiveHint=false, idempotentHint=false; the description goes well beyond that by disclosing the two-phase semantics — the call mutates nothing, returns a preview plus a confirmation link, and requires the merchant to act on that page. That human-in-the-loop detail is exactly the kind of behavior an agent cannot get from structured fields. Minor tension: "Calling this changes nothing" reads as read-only while readOnlyHint=false, though this is conservatively safe rather than misleading.

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 purpose is correctly front-loaded and the preview/confirmation sentence is dense with value. However, the second sentence about money in minor units is entirely off-topic for a tool with no price parameter and consumes roughly a quarter of the description, which is wasted and potentially confusing space.

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 2-parameter tool with a nested filter, full schema descriptions and annotations present, the description covers the one non-obvious thing: that this returns a preview and a confirmation link rather than applying the change. There is no output schema, and the description does give the gist of the return value, though it could say whether previews expire or how the confirmation link is delivered.

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 filter (with its requirement of at least one of productIds/collectionId/tag/vendor) and status (with enum meanings) are already fully documented in the schema — baseline 3. The description adds nothing about these parameters, and its only parameter-adjacent sentence, "Money is integer minor units (cents)," refers to a monetary parameter that does not exist on this tool, so it is noise rather than added meaning.

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 pair and resource ("Publish or unpublish products"), which an agent can immediately map to a product-status mutation. It does not name any sibling (products_edit, products_bulk_price_edit, gift_cards_set_status), and the binary "publish/unpublish" framing is slightly narrower than the actual three-state enum (active/draft/archived).

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?

Usage is implied rather than stated: the description makes clear this is the first step of a merchant-confirmed flow, which tells the agent when the call is appropriate. It never names an alternative tool or an exclusion condition (e.g., when to prefer products_edit or a bulk price edit), so the agent must infer routing.

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