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

Annotations already provide readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is partially covered. The description adds useful behavioral context: it only returns 在架需求 (active/listed needs) and aligns with the feed's visibility policy, and it states the return format as 完整需求卡（含作者 canOffer）, which is valuable since there is no output schema. It also reveals the hybrid retrieval mechanism (keyword + embedding with RRF fusion). This goes beyond the annotations without contradicting them, though it stops short of describing possible side effects, which the readOnlyHint=false leaves slightly ambiguous.

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 organized into three clearly labeled sections (何时用, 机制, 组合链), each earning its place: the first gives usage context, the second explains behavior, the third provides a downstream workflow. It front-loads the most decision-relevant information (when to use) and avoids filler. Despite using Chinese labels, every sentence carries operational value, making it concise and well-structured.

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 two-parameter search tool with no output schema, the description covers the essentials: when to use, the matching behavior, the visibility filter, and the return shape (full need cards with author canOffer). It also sketches the surrounding tool chain, which helps an agent plan multi-step workflows. It doesn't enumerate every field of the return card, but given the simple input schema and the explicit 'full need card' note, this is adequate. A slightly richer note on sorting/pagination behavior (beyond limit) would push it to 5.

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 the baseline is 3. The description adds meaning beyond the raw schema by explaining that q is matched against 标题/详情关键词 + need_embedding 向量, giving agents a clearer mental model of how queries are interpreted. It also mentions that only active needs are returned, which refines what limit controls (pagination over active results). This is a meaningful add-on to the schema descriptions rather than a restatement.

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 the exact use case: 定向找「有没有人在找 X」 (targeted search for whether anyone is looking for X), naming concrete examples like 「有没有人想找设计合作」. It explicitly contrasts with the sibling list_needs_feed, saying it is 更适合带明确关键词的检索, which distinguishes it from the recommendation feed sibling. That is a specific verb + resource + clear sibling differentiation.

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 explicitly defines when to use this tool (when the user has a specific keyword intent) and names the alternative list_needs_feed for recommendation-style browsing. It also provides a 【组合链】 showing the follow-up flow (get_need → contact_need → send_message), which gives clear operational context for when this tool leads into other tools. This is explicit when/when-not guidance with alternatives.

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