item_publish

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

With no annotations, the description carries the full burden. It usefully discloses two behaviors an agent could not infer: category auto-detection and default-address use, plus the yuan price unit. However, it says nothing about permissions/auth, irreversibility of publishing, failure modes (e.g., duplicate titles), or what happens to category_json/location_json params when auto-detection is claimed.

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 single line is front-loaded and free of waste, with the two automatic behaviors and the price unit packed in compactly. For an 11-parameter mutation tool, however, this brevity crosses into under-specification rather than disciplined conciseness.

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?

An output schema exists, so return values needn't be described. But for a mutation tool with 11 parameters, 0% schema coverage, and no annotations, the description leaves most of the calling contract (non-required params, delivery enum semantics, json field formats) undocumented.

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% across 11 parameters, so the description must compensate and largely fails. It clarifies the price unit (yuan) and implies category/location are optional due to auto-detection, but leaves images, delivery enum, post_price, original_price, can_self_pickup, and the *_json fields entirely unexplained.

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 gives a clear verb+resource (publish an item) and adds meaningful scope: category is auto-detected and the default address is used. This is readily distinguishable from siblings like item_delete, item_get, and item_list by verb alone, though it never names them explicitly.

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 explicit when-to-use or when-not-to-use guidance. The agent can infer that this creates a new listing, but nothing tells it how this relates to category_recommend or location_default, which the description implies are handled internally, nor any prerequisite or precondition.

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