hybrid_search

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

No annotations exist, so the description carries full burden—and it delivers: it discloses server-side embedding via ollama, jieba segmentation for BM25, RRF fusion, rerank latency and silent fallback to RRF order when the reranker is unavailable, and the requirement to provide at least one of query/embedding. These behavioral details go well beyond the schema and give the agent a solid model of the tool's execution.

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-organized: a two-sentence overview of the algorithm and use case, then a structured Args block. Every sentence conveys essential information—no filler or repetition. The length is justified by the complexity of a hybrid retrieval tool with optional reranking.

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?

Given the tool's complexity (dual retrieval branches, fusion, optional reranking) and the absence of annotations and output schema, the description provides robust coverage: algorithm, default behavior, server-side processing, latency implications, fallback semantics, and parameter constraints. The only omission is the exact return shape, but for a search tool this is acceptable and the description is otherwise complete.

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?

With 0% schema description coverage, the description fully compensates by explaining every parameter: the dual role of query, the advanced/optional nature of embedding, the restriction semantics of user_id/agent_id/type, the limit's range and default, and the rerank flag's latency and fallback. This is complete, actionable parameter 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 opens with a precise definition: 'Hybrid search: BM25 full-text + vector similarity, fused with Reciprocal Rank Fusion.' It then identifies the tool as the 'Best default choice for "find memories about X"', clearly distinguishing it from siblings like semantic_search or search_memories by combining exact keyword and semantic matching.

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 tool is explicitly positioned as the 'best default choice' for memory retrieval, with an example of when hybrid search shines (different wording like '显卡' vs 'GPU'). It explains when to provide query vs embedding and mentions the optional rerank behavior, but does not explicitly name sibling alternatives or state when not to use this tool, making the guidance clear but not exhaustive.

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