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

With no annotations present, the description carries the full burden and does so well: it discloses the mode-dependent ranking behavior (BM25 default, cosine in embeddings mode), the fallback to lexical when provider calls fail, the exact return shape, and that an index block reports mode and index staleness. This tells the agent what will happen at invocation time beyond what any schema field could convey.

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?

Three sentences, each earning its place: the first front-loads the core purpose, the second explains behavioral nuances, the third documents the return format (which substitutes for a missing output schema). No filler or repetition of schema content.

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 moderate complexity (nested filter object, no annotations, no output schema), the description covers the essential gaps: it specifies the return structure since there is no output schema and explains fallback/staleness behavior. Minor omissions—explicit result ordering by score, pagination semantics beyond k, and error behavior—keep it from a 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 description coverage is 100%, so the baseline of 3 applies even without parameter info in the description. The description adds no parameter-specific meaning beyond the schema; the only connection is that embeddings mode is set via host.docs.index_config, which orients behavior rather than any parameter. The schema adequately handles the parameter burden.

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?

Opens with a specific verb-resource pair ('Ranked passage search over this tenant's document store') and the qualifier 'passage' differentiates it from sibling retrievers like host.docs.get, host.docs.list, and host.catalog.search. The ranking detail (BM25 vs cosine) further pins down what this tool uniquely does.

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 domain context (tenant document store) and hints that the ranking mode is configured via host.docs.index_config, which is a useful pointer to an interacting sibling. However, it never explicitly says when to choose this over alternatives, nor does it state exclusions such as 'use host.docs.get for a single document' or 'use host.docs.list for metadata.' Selection guidance is implied, not stated.

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