xhs_search_products

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

Annotations already mark this as read-only and open-world, so no contradiction exists. Beyond that, the description adds important behavioral constraints around page_token handling: the full next_page_token must be passed back unchanged, with explicit prohibitions against truncation, abbreviation, masking, or replacing content with ellipsis. This is valuable behavioral context for the agent.

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 front-loaded with the core purpose and usage condition before moving to token-handling warnings. It is somewhat repetitive with the schema's page_token constraints, but it remains readable and each sentence earns its place in guiding tool selection and correct invocation.

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?

The tool is simple with only two parameters, one of which is optional, and an output schema is present. The description covers when to use it, when to prefer alternatives, and the critical pagination behavior, so an agent has everything needed to call it correctly.

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%, and the schema already thoroughly documents both keyword and page_token, including the exact-copy requirement and what must not be passed. The description essentially repeats this rather than adding new parameter meaning, so the baseline 3 is appropriate.

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 opens with a specific verb and resource ('搜索小红书商品' – search Xiaohongshu products) and immediately states the primary use case: finding products by search term. It distinguishes itself from siblings by explicitly routing sku_id cases to product detail/review tools and link/share-text cases to xhs_get_product_detail_by_url.

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 gives explicit when-to-use guidance: use when the user needs to find products by search word. It also names alternatives for complete sku_id and for product links/share text, and it explains pagination usage. This leaves little ambiguity about tool selection.

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