设置商品状态

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

Annotations already declare readOnly=false, idempotent=true, destructive=false. The description goes beyond them by warning that setting ACTIVE does not publish the product, which is a non-obvious behavioral trait. This is useful context an agent would otherwise miss from the schema and annotations alone.

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?

A single, front-loaded sentence that wastes no words. It states the operation, lists all valid statuses, and includes the most important caveat in one breath.

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 simple two-parameter, non-destructive, idempotent status setter, the description carries the main operational caveat (ACTIVE ≠ published) and the sibling list supplies adjacent tools. It does not explain response/return behavior, but no output schema exists and the operation is simple enough that this is not a critical gap.

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 0%, but the schema itself has a clear enum for status and a GID pattern for id. The description adds the meaningful distinction that ACTIVE is not a publication state, yet it gives no additional guidance for the id parameter or for the implications of the other statuses.

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 a specific action ('把商品设为') on a specific resource ('商品'), enumerates the four allowed statuses, and adds the clarifying caveat that ACTIVE is not the same as published. This makes the tool's purpose unmistakable and separates it from publication-related siblings.

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 caveat 'ACTIVE 不等于已发布' implies this tool should not be used for publication workflows, but it never explicitly says to use shopify_publish_product/shopify_unpublish_product for that. The guidance is therefore implied rather than stated, which leaves routing to an inference.

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