Agenterm

execute_command

Destructive

Run a non-interactive command in a fresh shell on the selected device and wait for its result. Working directory changes, shell variables, functions and environment activation do not carry over to later calls. Use cwd and env for this process, or session_start with a persistent shell and session_control(action=input) to preserve shell state across commands. The interpreter is reported by list_clients as client_info.shell. A nonzero exit, timeout, cancellation or execution failure sets isError. Captured output discards bytes beyond its retention limit. Canceling the MCP request sends a best-effort cancellation request; commands are not automatically retried.

Input Schema

Name	Required	Description
`cwd`	No	Working directory for this process on the target device.
`env`	No	Environment overrides for this command, merged with the client environment. Values must be strings.
`command`	Yes	Shell command to execute on the target device.
`client_id`	No	Six lowercase letters or digits from list_clients. Required for multi-device tokens, even when only one device is online; optional for single-device tokens.
`timeout_ms`	No	Process execution timeout in milliseconds. 0 disables the timeout.
`client_token`	Yes	Target client connection token, required with management access (including stdio and no-password mode). Device-scoped bearer access implicitly selects its own token.

Output Schema

Name	Required	Description
`error`	No	Optional execution or connection error. A disconnect does not prove the remote process completed successfully.
`stderr`	Yes	Captured standard error, sharing a 1 MiB combined limit with stdout.
`stdout`	Yes	Captured standard output, sharing a 1 MiB combined limit with stderr.
`canceled`	Yes	True only when the target reported cancellation; a disconnect alone does not confirm cancellation.
`exit_code`	Yes	Reported process exit code: 0 means success; -1 means execution failed, was interrupted, or the device disconnected before a normal exit report.
`timed_out`	Yes	True if the target reported that the process execution timeout elapsed.
`truncated`	Yes	True if output exceeded the 1 MiB retention limit. Commands discard excess captured output; sessions discard older buffered bytes.

Schema Changelog

Changes observed during successful MCP inspections.

Changed11 schema fields changedNov 2, 2026

changedInput schema / properties / client_token / description

Previous value: -"Target client connection token (required when authenticated with the management key)"New value: +"Target client connection token, required with management access (including stdio and no-password mode). Device-scoped bearer access implicitly selects its own token."

changedInput schema / properties / command / description

Previous value: -"Shell command"New value: +"Shell command to execute on the target device."

changedInput schema / properties / cwd / description

Previous value: -"Working directory on the target device. Each command starts a fresh shell; use cwd for subsequent commands instead of relying on a previous cd."New value: +"Working directory for this process on the target device."

changedInput schema / properties / timeout_ms / description

Previous value: -"Execution timeout in milliseconds, up to 86400000 (24 hours). 0 disables the timeout. Default: 60000 for execute_command, 0 for session_start."New value: +"Process execution timeout in milliseconds. 0 disables the timeout."

addedOutput schema / properties / canceled / description

Added value: +"True only when the target reported cancellation; a disconnect alone does not confirm cancellation."

addedOutput schema / properties / error / description

Added value: +"Optional execution or connection error. A disconnect does not prove the remote process completed successfully."

addedOutput schema / properties / exit_code / description

Added value: +"Reported process exit code: 0 means success; -1 means execution failed, was interrupted, or the device disconnected before a normal exit report."

addedOutput schema / properties / stderr / description

Added value: +"Captured standard error, sharing a 1 MiB combined limit with stdout."

addedOutput schema / properties / stdout / description

Added value: +"Captured standard output, sharing a 1 MiB combined limit with stderr."

addedOutput schema / properties / timed_out / description

Added value: +"True if the target reported that the process execution timeout elapsed."

addedOutput schema / properties / truncated / description

Added value: +"True if output exceeded the 1 MiB retention limit. Commands discard excess captured output; sessions discard older buffered bytes."

First observedNov 1, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already declare destructive/openWorld/non-idempotent, and the description goes well beyond them: state does not carry over, isError is set on nonzero exit/timeout/cancellation/failure, output is truncated at a retention limit, cancellation is best-effort, and commands are never auto-retried. These are exactly the operational facts an agent needs before firing arbitrary shell commands.

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-loads the core action in the first sentence and then adds only operational caveats. Six sentences is dense but nearly every one carries a distinct constraint; the retention-limit and cancellation sentences are the least essential but still relevant to correct invocation.

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

Completeness5/5

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

An output schema exists, so return values need no prose, and the description still covers state isolation, error signaling, truncation, and cancellation behavior. Nothing material is missing for a destructive, open-world execution tool.

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 cwd, env, timeout_ms, client_id and client_token are already documented. The description adds the useful scoping point that cwd/env apply only to this process, and points to list_clients/client_info.shell for the interpreter, but gives no extra detail on timeout or token semantics beyond the schema. Baseline 3 is appropriate.

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?

States a specific verb and resource ('Run a non-interactive command') plus the two defining traits of the call: fresh shell and synchronous wait for result. That framing immediately separates it from session_start and session_control, which are named in the next sentence.

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?

Gives an explicit routing rule: use cwd/env for this single process, or session_start plus session_control(action=input) when shell state must persist across commands. It names the alternatives and the condition that selects each, leaving nothing to inference.

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

All Agenterm tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?