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

Even though annotations already include readOnlyHint=false, openWorldHint=true, idempotentHint=true, the description goes beyond them by detailing the hybrid retrieval mechanism (keyword + vector, RRF fusion, LLM query expansion/reranking, auto-degradation) and the 'mode' field. This is rich behavioral context that annotations alone do not provide. No contradiction with annotations.

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 well-structured with clear headings (when to use, only products, mechanism, pitfall), front-loading the critical usage guidance. Every section earns its place; nothing is redundant or tangential. Despite being longer than average, it is efficiently organized for agent scanning.

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 search tool with two parameters and no output schema, the description covers usage, alternatives, mechanism, and common pitfalls. It states the return fields (slug/tagline/creator) and even warns against meta queries. The agent has everything needed to invoke it correctly without ambiguity.

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 coverage is 100%, so both q and limit are already documented. The description adds no new parameter-specific semantics; it only restates that queries are natural language or keywords (already in schema). Given the high schema coverage, the baseline of 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 explicitly states what the tool does: return product cards when the user is searching for products/works in natural language, including slug, tagline, and creator. It clearly distinguishes from sibling tools search_people and search_needs by specifying exactly what entity type each handles, leaving no ambiguity.

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 '【何时用】' section gives concrete trigger examples (e.g., 'Is there a financial tool for indie devs?'), and the '【只管产品】' section explicitly states when to use alternatives: search_people for people, search_needs for needs. The pitfall warning about meta questions further clarifies what not to do. This is exemplary routing guidance.

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