ssh_grep

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

No annotations are provided, so the description carries the full disclosure burden. It mentions the output format (file:line:match) which is useful, but fails to disclose that this is a network-executed command on a remote host, that it may be slow or incur SSH latency, that recursive search could be expensive on large trees, or what happens on connection failure or no matches. The fallback behavior detail is helpful but insufficient for an unannotated remote-execution 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?

The description is a tight two-sentence structure that front-loads the core purpose and gives concrete output format. It's efficient with no filler. Could potentially add a sentence on usage/limitations, but what's present is well-organized.

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 9-parameter remote search tool with no annotations and no output schema, the description is minimal. It covers the core search behavior and output format, but lacks guidance on remote operation costs, recursion behavior on large trees, error handling, connection prerequisites (SSH keys configured, per target param), and interaction with the max_results default (no default stated). The tool is moderately complex and would benefit from more operational context.

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 high (~89%), with 8 of 9 parameters documented in the schema with descriptions (only 'pattern' lacks a description). The tool description adds the output format context but does not add parameter-level semantics beyond what the schema provides. Baseline 3 is appropriate given the high schema coverage.

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?

Description states a specific verb+resource: 'Search remote text files recursively with ripgrep, falling back to grep.' It distinguishes from siblings like ssh_read_file (which reads a single file) by specifying recursion and search semantics. However, it doesn't explicitly differentiate from ssh_exec (which could also run grep remotely), though the dedicated purpose is reasonably clear.

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 usage context (searching remote files) but provides no explicit when-to-use vs alternatives, no exclusions, and no guidance on when grep would be used for local searching or when to prefer ssh_read_file. The fallback-to-grep note gives some implementation context but not selection guidance.

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