search_code

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

With no annotations, the description carries the full burden of behavioral disclosure. It provides useful context on parameter behavior (hybrid mode, rerank trade-offs) and even discloses that rerank is slower and requires the '[embeddings] extra'. It does not, however, mention any side effects, permissions, or limitations beyond those parameter-specific notes.

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 efficiently structured as a docstring with a one-sentence purpose followed by a concise Args section. Every sentence earns its place, explaining each parameter without redundancy or fluff, making it easy for an agent to parse quickly.

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 presence of an output schema, the description appropriately focuses on input parameters and behavioral specifics like speed/dependency. It covers the core functionality and parameter semantics well, but it lacks explicit prerequisites (e.g., 'repo must be indexed first') or typical error scenarios, leaving a small gap in contextual completeness.

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?

Despite 0% schema description coverage, the description compensates fully by explaining every parameter: query (natural-language or keyword), k (number of results), hybrid (dense vs dense+BM25 fusion), and rerank (wide pool reordering with cross-encoder, with precision/speed trade-off and dependency). This adds significant meaning beyond the bare schema.

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 uses a specific verb ('Search') with a defined resource ('the indexed codebase') and a clear outcome ('return the top matching definitions'). This clearly distinguishes it from sibling tools like index_repo (indexing), status (status checks), get_context (retrieval), and impact_radius (analysis).

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 implies usage when you need to search code, but it does not explicitly state when to use this tool versus alternatives like get_context or impact_radius. There are no exclusions or alternative tool references, so it falls short of providing clear usage guidance.

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