Skip to main content
Glama

Execute Command

execute_command

Run commands on an SSH host through a persistent session; long-running tasks switch to async tracking, and sudo or network-device enable mode can be handled automatically.

Instructions

Execute a command on an SSH host using a persistent session.

Starts synchronously and waits for completion. If the command doesn't complete within the timeout, it automatically transitions to async mode and returns a command ID for tracking.

The host parameter can be either a hostname/IP or an SSH config alias. If an SSH config alias is provided, configuration will be read from ~/.ssh/config.

For network devices (routers, switches), use enable_password to automatically enter privileged/enable mode before executing commands.

For Unix/Linux hosts requiring sudo, use sudo_password to automatically handle the sudo password prompt. The command will be automatically prefixed with 'sudo' if not already present.

Advanced Features:

  • Automatic timeout handling with async transition

  • Interactive command support with input capability

  • Command interruption (Ctrl+C) for stuck processes

  • Session persistence across multiple commands

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "host": "<host>",
      "command": "<command>"
    },
    "name": "execute_command"
  }
}

Input Schema

NameRequiredDescriptionDefault
hostYesHostname, IP address, or SSH config alias (e.g., "myserver")
portNoSSH port (optional, will use SSH config or default 22)
commandYesCommand to execute
timeoutNoTimeout in seconds for command execution (default: 30)
passwordNoPassword (optional)
usernameNoSSH username (optional, will use SSH config or current user)
key_filenameNoPath to SSH key file (optional, will use SSH config)
sudo_passwordNoPassword for sudo commands on Unix/Linux hosts (optional)
enable_commandNoCommand to enter enable mode (default: "enable")enable
enable_passwordNoEnable mode password for network devices (optional)

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.2+p1

TDQS

A3.8/5.0
Behavior4/5

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 mostly rises to it: it discloses the synchronous start, the automatic transition to async mode on timeout, the returned command ID for tracking, session persistence across calls, automatic 'sudo' prefixing, and interactive/interrupt capabilities. What it doesn't disclose is what a successful synchronous call returns (no output schema exists) or that arbitrary command execution is inherently high-impact and should be treated as destructive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well front-loaded: the core contract (sync start, async fallback, command ID) appears in the first two paragraphs, with parameter-specific notes and a feature list after. The 'Advanced Features' list partly repeats the timeout/async and interactive points already stated, costing some redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter, mutation-capable tool with no annotations and no output schema, the description covers the important ground: auth options, alias resolution, privilege escalation paths, timeout behavior, and session state. The notable remaining gap is the shape of a synchronous return value, which nothing else in the definition supplies.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining behaviors the schema cannot: that 'host' accepts an SSH config alias read from ~/.ssh/config, and that sudo_password causes the command to be automatically prefixed with 'sudo' if absent, plus enable_password triggering privileged mode. These are non-obvious side effects, not restatements of field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource+transport ("Execute a command on an SSH host using a persistent session"), which is far more informative than the title alone. It doesn't explicitly name a sibling (e.g. execute_command_async) as the alternative, so an agent must infer the boundary from the described sync-to-async transition.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives conditional usage for two parameters: "For network devices (routers, switches), use enable_password..." and "For Unix/Linux hosts requiring sudo, use sudo_password". However, there is no explicit when-to-use-this-vs-execute_command_async or vs read_file/write_file guidance, so the choice between the sync entry point and its async sibling is left implicit.

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