Skip to main content
Glama

run_command

Run a shell command non-interactively on a session's host and get its exit status, stdout and stderr. Use for non-interactive commands only; use send_input for interactive programs.

Instructions

Run a shell command on the session's host and get its exit status, stdout and stderr. It runs non-interactively, beside the terminal (not typed into it); the person sees it in the session's tab. Don't run commands that wait for input; use send_input for interactive programs.

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": {
      "command": "<command>"
    },
    "name": "run_command"
  }
}

Input Schema

NameRequiredDescriptionDefault
hostNoThe host, when you don't name a session.
commandYesA shell command. It runs in a fresh shell in the home directory: `cd` does not carry over to the next command.
session_idNoThe session to run it in (its host). Or give `host` and a session of yours there is used, or opened.
timeout_secsNoGive up after this many seconds (default 60, at most 3600).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4/5.0
Behavior3/5

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

With no annotations, the description carries the full burden, and it does disclose meaningful behavior: non-interactive execution, that it runs beside the terminal rather than being typed into it, that the person sees output in the session's tab, and what the response contains. It does not address permissions or access requirements, whether commands can mutate or destroy host state, or any approval/sandboxing model, which are the highest-stakes facts for a 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.

Conciseness5/5

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

Three short sentences, front-loaded with the action and the return values, then the non-interactive constraint, then the alternative. Every sentence carries information an agent needs and nothing is repeated from the schema.

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 four-parameter execution tool with no annotations and no output schema, the description covers what it does, how it behaves, what it returns, and when not to use it. The one substantive hole is the absence of any permission, safety, or blast-radius context for arbitrary shell execution.

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

Parameters3/5

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

Schema description coverage is 100%, so host, session_id, timeout_secs, and the fresh-shell semantics of command are all documented in the schema itself. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

Purpose5/5

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

"Run a shell command on the session's host" names a specific verb and resource, and the same sentence states the return payload (exit status, stdout, stderr). The follow-up clause distinguishes it from send_input, so an agent can route between the two without opening either schema.

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

Usage Guidelines4/5

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

Gives an explicit exclusion ("Don't run commands that wait for input") plus the named alternative (send_input for interactive programs), which is exactly the boundary an agent is most likely to get wrong. It stops short of covering other execution paths such as run_snippet, but the guidance it does give is clear and actionable.

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