search_in_project

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

With no annotations, the description carries the behavioral burden. It discloses the default compact output format, total matches, file count, top 10 hottest files, code detail behavior, and grouped/sorted output mode. It does not mention performance characteristics, but the disclosed default and mode behaviors are substantial and meaningful.

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 three tight sentences with no filler. The most important fact (search scope) comes first, followed by defaults and mode-specific usage. Every clause earns its place and front-loads the default behavior before the optional modes.

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 search tool with six parameters and no output schema, the description covers the essential return behavior (compact summary, code detail, grouped files) and calls out the key mode switch. Parameter-level details like max_results, context_lines, and exclude_pattern are already fully documented in the schema, so nothing critical is left unexplained.

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 is 3. The description adds value beyond the schema by explaining the compact summary output, the top-files behavior, and how max_files=-1 changes the output into a grep-like grouped listing. This is real semantic enrichment rather than repetition.

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 clear verb and resource: 'Search across all project files.' It also specifies the output modes ('1-line compact output', 'code detail', grouped/sorted file list), which distinguishes this from sibling tools like search_in_file and search_symbol by emphasizing project-wide scope.

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 explicit instructions for when to use each mode: max_files=N for code detail, and max_files=-1 with file_pattern as a grep replacement. It does not explicitly contrast with sibling tools or state when not to use them, but the 'across all project files' scope and grep-replacement framing provide clear contextual usage guidance.

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