source_search

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

No annotations are provided, so the description carries the behavioral disclosure burden. It does explain the default search directory, the optional explicit file list, and how the regex flag changes matching behavior. It omits the default ignore_case=true and max_matches=200, and it does not describe the result format, so the disclosure is only partial.

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 front-loaded with a clear one-line purpose and then lists arguments in a compact, scannable format. Every line adds useful semantics, and there is no filler or repetition of schema titles. The structure is efficient and readable.

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 core invocation is covered: pattern is required, and path, files, and regex are explained. But the description leaves gaps around case-insensitive behavior, the match limit, and what the tool returns, which are meaningful because there is no output schema or annotations to fill them. It is adequate but not complete.

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 schema properties have no descriptions, so the args block provides essential meaning for pattern, path, files, and regex. It clarifies that path falls back to default_project_dir or cwd and that files are relative to path. However, ignore_case and max_matches are absent from the description, though their defaults appear in the 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 opens with a specific verb and resource: "Search source files in the project directory." This clearly distinguishes source_search from sibling tools like source_read and source_edit, which operate on a specific file rather than searching content. The pattern argument reinforces that this is a content-search tool.

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 when the tool should be used: when an agent needs to find text or regex matches inside source files. However, it never explicitly names alternatives or states when not to use it. The sibling list makes the choice inferable, but the description itself leaves the routing guidance implicit.

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