Search Files

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

The annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds valuable behavioral context beyond annotations: it specifies recursive searching, glob-style pattern requirements, path relativity to working directory, and the constraint of searching only within allowed directories. It doesn't mention rate limits or performance characteristics, but provides sufficient operational context given the annotations.

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 efficiently structured with four sentences that each serve distinct purposes: stating the core functionality, explaining pattern syntax, providing usage context, and stating constraints. There's no redundant information, and the most critical information (what the tool does) comes first, followed by implementation details and limitations.

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 the tool's moderate complexity (3 parameters, recursive searching), the description provides good context about behavior and constraints. The existence of an output schema means the description doesn't need to explain return values. However, with 0% schema description coverage and three parameters, the description could better explain all parameters' semantics to be fully complete for agent understanding.

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?

With 0% schema description coverage, the description must compensate for the lack of parameter documentation in the schema. It explains the 'pattern' parameter thoroughly with glob-style examples and clarifies that patterns match paths relative to the working directory. However, it doesn't explain the 'path' parameter's purpose or the 'excludePatterns' parameter at all, leaving some semantic gaps despite good coverage of the pattern parameter.

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 the tool's purpose with specific verbs ('recursively search for files and directories matching a pattern') and resources ('files and directories'), distinguishing it from siblings like list_directory (which lists without pattern matching) or get_file_info (which retrieves metadata for known files). It explicitly mentions the recursive nature and pattern-based matching, which differentiates it from simpler listing tools.

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 provides explicit guidance on when to use this tool ('Great for finding files when you don't know their exact location') and when not to use it ('Only searches within allowed directories'), with clear alternatives implied by sibling tools like list_directory for known locations or get_file_info for specific files. The pattern examples help users understand appropriate use cases versus other tools.

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