add_product

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

With no annotations provided, the description carries the full behavioral burden and does so well: '免费(仅建条目)' discloses that this only creates a database entry, not images or videos, and the anchoring explanation warns about video drift/hallucination if the product library is not built. It does not mention idempotency, error handling, or what happens on duplicate names, which prevents a higher score.

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 description is dense and front-loaded: it leads with the must-do flag, immediately states the action, then gives the rationale, the recommended next tool, and the cost/side-effect in a few short clauses. Every sentence earns its place and there is no redundant filler.

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 4-parameter create operation with no output schema and no annotations, the description is quite complete: it explains why the tool exists, when it is required, what it creates, the consequence of omitting it, and the downstream follow-up tool. The main gap is that it never states what the tool returns (e.g., a product ID) or that drama_id must already exist, which an agent might need for later steps.

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 50%, but the description maps several parameters by mentioning '名称/卖点/图', which corresponds to name, description, and image_url. However, the required drama_id parameter is never explicitly explained beyond the vague '广告项目' framing, so the description only partially compensates for the missing schema documentation.

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 the exact action and resource: '往商品库加一个商品' (add a product to the product library) and enumerates the payload fields: name, selling point, image. It also positions this as the ad-product-creation step ('广告项目必做', '是广告的主体'), which distinguishes it from related sibling tools like create_prop or generate_product_sheet.

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 clearly marks when this tool is required ('★广告项目必做') and explains the failure mode if skipped ('不建产品库镜头里的产品会漂移/瞎编'), so an agent can determine when to invoke it. It also chains the next step ('建完用 generate_product_sheet 出设定图'), but it does not explicitly list exclusions or alternatives such as 'use create_prop for props', so it stops short of a full when-not specification.

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