search_code_enhanced

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 the two-pass search/rerank behavior, result citation fields and sources map, staleness checking cost, response_mode variants, and default output format. This goes well beyond a simple 'search' label.

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 dense but efficiently front-loaded: it opens with the decisive use condition, then packs behavioral and option details into a few sentences with no filler. Every sentence carries actionable 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?

The tool is complex (19 params, response modes, output formats) and the description covers most key behaviors and outputs, especially given an output schema exists. It leans on search_code for parameter definitions and doesn't spell out every parameter, but the essential invocation decisions (when, how, output shape) are addressed.

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?

The description adds real meaning for check_staleness, response_mode, and response_format, and references search_code for the rest. However, with 0% schema description coverage for 19 parameters, most inputs (e.g., top_k, use_hyde, cross_repo, rerank_pool) are left undefined in this tool's definition and only inherited by reference to a sibling.

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 use case ('when search_code results suggest the answer spans multiple structurally-related files') and a specific action ('pull in chunks from those neighbor files in one shot'). It clearly distinguishes itself from the sibling search_code by describing the second-pass Milvus search and neighbor-file filtering.

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?

Explicitly conditions use on search_code results and names the alternative directly. It also provides guidance among response modes, including when to fall back to read_file for 'facet' mode, and notes the performance tradeoff of check_staleness.

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