A powerful search tool built on regular expressions.

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

With no annotations at all, the description carries the full burden and delivers richly: default output mode, the 250-entry head_limit default, exact-vs-fast scan semantics and their effect on count exactness, and encoding-grouped searching for non-ASCII patterns. It also tells the agent to check structuredContent fields scanComplete, truncationReason, and outputTruncated when a search is resource-limited, which is the kind of behavioral nuance annotations would otherwise need to provide.

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?

Well-structured: purpose and the key directive are front-loaded, followed by organized bullets. It is on the longer side (~330 words), and the capability-list bullet partially restates what the schema already enumerates, but nearly every sentence carries actionable information for the agent.

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 complex 16-parameter tool with no annotations and no output schema, the description covers purpose, defaults, pagination, truncation diagnostics, and encoding edge cases exceptionally thoroughly. The remaining gap is the precise return shape of content mode and zero-match/error behavior, which an output schema would normally carry.

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 100%, so every parameter is already documented in the input schema. The description adds genuine selection-level value beyond the schema by tying output_mode choices to use cases and explaining scan_mode's validity constraint and how head_limit/offset interact with the default limit, though some details (like -n defaulting to true) do duplicate schema text.

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?

States 'A powerful search tool for file contents' — a specific verb (search) and resource (file contents). The directive 'ALWAYS use Grep for search tasks' clearly differentiates it from sibling tools Read, Edit, and Write, which cover file access and modification rather than searching.

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 commands 'ALWAYS use Grep for search tasks. NEVER invoke grep or rg as a Bash command,' giving a clear when-to-use rule and a prohibition. It also provides selection guidance for output_mode ('Use output_mode=files_with_matches when you only need file paths') and for scan_mode ('fast is opt-in and only valid for files_with_matches'), leaving little to inference.

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