search

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

With no annotations, the description carries the behavioral burden. It discloses meaningful runtime behavior: per-stage scores are included for transparency, reranking is conditional on a configured cross-encoder, and an empty result has a specific meaning. This goes well beyond a bare description, though it does not address rate limits or auth.

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 four sentences with no filler. The core purpose is front-loaded, followed by mode semantics, rerank behavior, and output interpretation. Every sentence adds value.

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 has an output schema, so return-value details do not need to be repeated. The description covers the key calling nuances: mode options, rerank behavior, per-stage scores, and empty-result semantics. A minor gap is that the collection parameter's role is not elaborated, but the schema title and default make it reasonably clear.

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 0%, so the description must compensate. It does for the two most complex parameters: it explains what each mode means (hybrid = BM25 + semantic, dense = semantic only, bm25 = keyword only) and what rerank does. query, top_k, and collection are left to their schema titles and defaults, which are fairly self-explanatory.

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 a collection and return the most relevant chunks') and clearly defines the output as chunks with sources. This distinguishes it from siblings like ingest_documents, answer, list_collections, and evaluate_retrieval without needing to reference them.

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 clear context for when this tool is appropriate: retrieving relevant chunks with sources. It also provides practical interpretation guidance, such as treating an empty list as 'not in the documents.' It does not explicitly name alternatives or state when not to use it, so it stops short of a full 5.

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