Run shell commands on a configured remote SSH host to perform tasks such as checking services, inspecting containers, or reading files when no dedicated tool fits.
Run a shell command on a host, same as ssh <host> '<cmd>'; write cmd without the outer quotes. Prefer a dedicated tool when one fits. Hosts:
| Name | Required | Description | Default |
|---|---|---|---|
| cmd | Yes | ||
| host | Yes | ||
| timeout | No | Seconds, default 60 | |
| max_chars | No | Per-stream output cap, default 8000 |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full behavioral disclosure burden. It says this is equivalent to SSH and explains command quoting, but it does not disclose permissions, destructive potential, side effects, authentication requirements, or output behavior for an arbitrary remote shell 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 short and front-loads the key invocation model, which is good. However, the trailing incomplete fragment 'Hosts: ' is a structural defect that wastes space and leaves promised host information missing.
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?
This is a high-risk arbitrary command execution tool with no annotations and no output schema, so the description should be more complete. It omits safety implications, host list details, permissions context, and output behavior, leaving the agent without enough information to invoke it confidently in a multi-tool environment.
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 50%, so the description needs to compensate for the undocumented `host` and `cmd` parameters. It partially does so by mapping them to the SSH analogy and specifying that `cmd` should be written without outer quotes, but the host enumeration is truncated at 'Hosts: ' and `timeout`/`max_chars` are left entirely to the schema.
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 uses a specific verb and resource: 'Run a shell command on a host,' and clarifies the execution model with the `ssh <host> '<cmd>'` analogy. It hints at sibling alternatives with 'Prefer a dedicated tool when one fits,' but does not name any sibling tool, so differentiation is only partial.
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?
It gives a minimal usage rule: prefer a dedicated tool when one fits, implying `exec` is the fallback for arbitrary shell commands. However, it does not name which siblings fit which cases, nor does it state when-not to use this tool beyond that vague preference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.