Search a file for a basic regex pattern on a SLURM cluster. Streams matches line by line, so you can safely inspect huge files and view surrounding context.
grep a file for a pattern (basic regex). Streams, so safe for huge files.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path on the cluster | |
| pattern | Yes | ||
| context_lines | No |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds genuinely new traits: streaming execution and the regex flavor supported for the pattern. It omits what the output looks like and any match-count or pagination behavior, which matters because no output schema exists.
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?
Two tightly packed clauses with no filler, and the core verb/resource is front-loaded ahead of the performance hint. Nothing in the text is redundant.
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?
Annotations cover the safety profile and the description covers scope and streaming, but with no output schema the agent still cannot tell whether results are raw matching lines, line-numbered, or truncated. The unexplained context_lines parameter is a second gap for a tool this simple to fully specify.
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 only 33%, so the description must carry weight. It clarifies that "pattern" is basic regex, but the whole context_lines parameter (with its default of 3) is never explained in either the description or the schema, leaving the agent to guess whether it means surrounding lines.
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 specific verb (grep) and resource (a file) with the matching mechanism (pattern, basic regex), which immediately separates it from content-reading siblings like hpc_read_file and hpc_head_file. An agent can identify the operation without opening the schema.
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?
"Streams, so safe for huge files" gives a concrete condition that routes the agent here rather than to hpc_read_file or hpc_head_file. It does not name those alternatives explicitly or state when-not to use it, so it falls short of full explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.