search_docs

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

With no annotations and no output schema, the description carries the full burden and does disclose the return payload (best-matching sections with file path, line range, heading breadcrumb, snippet). It does not cover ranking behavior, index staleness, or what happens on an empty/degenerate query, which are the remaining behavioral gaps.

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 tight sentences with zero filler: purpose and return shape first, then the usage preference and query syntax. Nothing is repeated from the schema and no sentence could be dropped without losing information.

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 simple two-parameter search tool with no annotations and no output schema, the description covers what it does, what it returns, how to phrase the query, and why to prefer it over alternatives. Nothing an agent needs to invoke it correctly is missing.

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 already 100%, so the baseline is 3. The description adds genuine value beyond the schema by specifying query formulation rules (3-6 distinctive keywords rather than a full sentence, double quotes for exact phrase matching), which meaningfully change how the query parameter should be populated.

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?

States a specific verb+resource ('Full-text search over the local documentation knowledge base') and even enumerates the shape of the result (path, line range, breadcrumb, snippet). It implicitly separates itself from list_docs and reindex_docs by being a matching/retrieval operation, but never names those siblings to disambiguate explicitly.

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?

Gives clear context for use ('Prefer this over grepping or reading whole files') plus concrete query-construction advice (3-6 distinctive keywords, quote phrases for exact match). It stops short of stating when NOT to use it or when to reach for list_docs instead, so no exclusions are provided.

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