Skip to main content
Glama

run_command

Run a one-off shell command to completion, returning separated stdout/stderr and the true exit code so you can branch on success or failure; report errors only if execution is impossible.

Instructions

执行会自行结束的一次性命令(多条命令/多文件操作请改用 run_batch 一次并行打包;持续盯实时输出且不关心退出码的命令如 tail -f 请改用 observe_stream 直接启动并流式读取;需后台起停服务、等就绪标记并核实进程退出码的任务请改用 spawn_and_observe)。退出码如实返回(非零不是异常——是数据,供条件分支);只有无法执行(超时/中断/连接死)才报错。stdout 与 stderr 分离返回。

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
layerNo目标层名(缺省=默认层——最近 push_ssh/push_into 的层)
commandYesshell 命令
timeout_msNo超时毫秒(缺省 120000)

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.3/5.0
Behavior4/5

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

No annotations are supplied, so the description carries the full burden, and it does substantial work: non-zero exit codes are returned as data rather than raised as errors, errors occur only on timeout/interrupt/connection loss, and stdout/stderr are separated. Remaining gaps are about session state (cwd, env persistence, layer isolation across calls) which are not addressed.

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?

Front-loaded with the core action, then a dense routing parenthetical, then exit-code and stream semantics. Every clause carries information, though the parenthetical packs three alternative tools into one long sentence and would be easier to scan as separate items.

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 command-execution tool with no annotations and no output schema, the description covers the critical unknowns: dispatch routing, exit-code semantics, failure conditions, and output shape. It stops short of describing execution context (working directory, environment, whether the layer persists state between calls), which matters for a shell runner.

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 layer, command, and timeout_ms are already documented in the schema. The description adds a timeout/impossibility failure semantic but no additional meaning for the layer or timeout parameters themselves. Baseline 3 applies when the schema does the heavy lifting.

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?

Names a specific verb+resource (run a one-shot command that self-terminates) and immediately bounds the scope against three named siblings. An agent can distinguish run_command from run_batch, observe_stream, and spawn_and_observe without opening any schema.

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

Usage Guidelines5/5

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

Provides explicit when-to-use alternatives with the selecting condition for each: multi-command/multi-file → run_batch, continuous output like tail -f with no exit-code interest → observe_stream, background service start/stop with readiness markers and exit-code verification → spawn_and_observe. Nothing is left to inference.

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