regex_search

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states read-only nature, no side effects/auth/rate limits, default caps (500 files, 10 hits per file), truncation reporting, scoping semantics, and that invalid regex throws. This is comprehensive for a read-only tool.

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 dense sentences cover purpose, performance, safety, caps, truncation, scoping, and error behavior. No fluff; every clause adds value. Front-loaded with purpose, then operational details.

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 no output schema and no annotations, the description provides sufficient operational context: what it returns (per-file hits with line numbers), important caps and truncation flags, scope semantics, and error conditions. The agent can correctly invoke and interpret results.

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 coverage is 80% (4 of 5 parameters have descriptions; case_insensitive has no description). The description adds little beyond the schema—it restates project_id semantics which the schema already covers. It doesn't add information about case_insensitive or the exact format of pattern beyond what the schema says. Baseline 3 for high schema coverage is appropriate.

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 clearly states what the tool does: 'Match a JS regex against the body of every file in scope... and return per-file hits with line numbers.' It uses a specific verb (match) and resource (files in scope). It also distinguishes itself from the FTS `search` sibling by naming it directly and positioning regex_search as a fallback for cases FTS misses.

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?

Explicit when-to-use guidance is provided: 'use only when FTS misses substrings, URLs, or code identifiers.' It also explains the performance tradeoff ('Slower than FTS search') and clarifies scoping behavior for project_id, which helps the agent choose scopes correctly. No exclusions are needed beyond this.

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