search_docs

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

With no annotations, the description carries the full burden, and it delivers: it discloses scope, version-sensitive behavior (only current versions unless product/version passed), and the meaning of sufficient_evidence. It could add a bit more about limits (e.g., rate, token cost, or that it is a read-only search), but the disclosed behaviors are genuinely important and not obvious from the schema.

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?

Four sentences, tightly packed, front-loading the core purpose before caveats. Every sentence adds actionable value: what it searches, when to use it, how to handle versions, and how to interpret the evidence flag. No filler or repetition.

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 description is complete for an agent facing a documentation-search task: it states scope, expected behavior, version handling, evidence interpretation, and a sibling fallback. The output schema exists, so return values need no elaboration. This is a well-rounded definition that would let an agent call the tool correctly in nearly all scenarios.

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 schema fully documents all six parameters, including examples and defaults. The description adds context for product and version (version sensitivity) and references list_products for values, but it does not materially enrich the meaning of query, top_k, response_format, or include_superseded beyond what the schema provides.

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 states a specific verb ('Search'), a concrete resource (Neutrinos product documentation with corpus counts), and a clear output ('ranked, citable passages'). It positions itself as 'the entry point for any question about Neutrinos products,' distinguishing it from siblings like fetch_document and list_products.

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?

It explicitly frames when to use the tool ('any question about Neutrinos products'), gives conditional guidance (pass product/version when version is known), and points to a sibling (call list_products first if unsure). It also tells the agent what to do with the result (check sufficient_evidence), leaving no ambiguity about when to apply this search.

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