search_products

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

With no annotations, the description carries the full behavioral burden. It discloses the result shape and the sort/range semantics, but says nothing about authentication requirements, rate limits, total result caps, or whether pagination beyond page_size is possible. Useful context, but incomplete for a 6-param search tool with zero annotation coverage.

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?

Purpose is front-loaded in the first clause, followed by a compact Args list with no filler sentences. The only minor redundancy is restating return fields that the output schema already defines, but it is one short parenthetical and does not bloat the definition.

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 paginated search with an output schema present, the description covers the searchable dimensions and result semantics adequately, so return values need not be explained further. It falls short of 5 only because cross-platform behavioral differences (e.g., whether commission data exists on every platform) are left unstated.

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%, so the description must carry all parameter meaning and it does: platform enumerated as taobao/jd/pdd, keyword noted as Chinese-friendly, page documented as 1-based, page_size bounded 1-50, has_coupon explained, and six sort modes spelled out including the meaning of commission and sales. This fully compensates for the bare schema.

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 and resource ('按关键词搜索商品') and enumerates the unified return fields (price, coupon price, commission rate, sales, shop, link), so the agent immediately knows what the tool produces. It does not, however, distinguish itself from siblings like get_product or shopping_status, which an agent must infer from names alone.

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 Args block gives implicit operational guidance (has_coupon to restrict to coupon items, sort values to shape results), which helps an agent steer the call. There is no explicit statement of when to use this tool versus get_product for a single item, nor any exclusion or prerequisite, so usage remains implied rather than declared.

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