Remote terminal access for MCP agents: create connection invitations, run commands, and manage interactive sessions on authorized macOS, Linux, and Windows computers. Open source, with one-command client onboarding.
Scored across 7 tools
Each tool maps to a distinct piece of the remote-execution workflow (provisioning, device listing, one-shot exec, session start/control/read/list), and the descriptions explicitly disambiguate execute_command from session_start and session_control. The main residual overlap is session_control bundling input/interrupt/eof/stop behind an action parameter, which an agent could still pick with the wrong action.
All names are snake_case and readable, but the convention splits: create_client/execute_command/list_clients use verb_noun while session_control/session_list/session_read/session_start use noun_verb. It is a minor, predictable deviation rather than a chaotic mix.
Seven tools is well-scoped for a remote shell/device orchestration server: one tool per lifecycle stage with no obviously redundant entries. Nothing feels padded or missing at the count level.
The core lifecycle (invite a device, list devices, run one-shot commands, start/read/control/list sessions) is covered end to end. Gaps include no way to revoke or delete a client token, and no file transfer/upload capability, which limits some remote-agent workflows.
Create a private client connection token and an invitation. timeout_seconds sets the invitation lifetime in seconds (default 300, or 5 minutes). Returns connection commands and display_text for the target user. After generating the connection instructions, you MUST present them to the user and call list_clients with the returned client_token and wait_ms=60000 to check whether a device connects, with a 60-second timeout. Report whether a device connected or the wait timed out. multi_device controls simultaneous connections and invitation reuse.
| Name | Required | Description | Default |
|---|---|---|---|
| multi_device | No | True permits multiple simultaneous devices and reuses the invitation until expiry. False allows one device and a single-use invitation. | |
| timeout_seconds | No | Invitation lifetime in seconds, as a positive integer. Default 300 (5 minutes). Expiry prevents invitation redemption; it does not disconnect devices that have already connected. |
| Name | Required | Description |
|---|---|---|
| expires_at | Yes | Invitation expiry deadline as a UTC RFC 3339 timestamp. |
| invitation | Yes | Private invitation credential for target-client authorization; expires at expires_at. |
| client_token | Yes | Private credential for this target group. Pass as client_token with management access (including stdio and no-password mode) or as the MCP bearer token for device-scoped access. |
| display_text | Yes | User-facing connection instructions containing credentials and commands for both platforms. |
| multi_device | Yes | True permits multiple simultaneous devices and reuses the invitation until expiry. False allows one device and a single-use invitation. |
| macos_linux_command | Yes | macOS/Linux connection command containing private invitation access. |
| windows_powershell_command | Yes | Windows connection command containing private invitation access. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the write/non-idempotent/non-destructive profile, but the description adds real behavioral detail beyond them: expiry prevents invitation redemption yet does not disconnect already-connected devices, and multi_device governs simultaneous connections plus invitation reuse. It also mandates a follow-up verification call and reporting obligation. It stops short of stating permission or auth requirements for creating a private token.
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?
Purpose and return values are front-loaded, followed by the required post-call workflow, which is the highest-value information. The trailing sentence on multi_device is appended after the workflow instructions rather than grouped with the timeout sentence, a minor ordering flaw in an otherwise tight description.
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?
With an output schema present, return values need not be explained, yet the description still signals the shape (connection commands, display_text). Combined with the mandated verification loop and timeout semantics, an agent has enough to invoke and follow through. Only the permission/auth context for minting a private token is unaddressed.
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 coverage is 100%, and the description's parameter remarks (default 300 seconds; multi_device controls simultaneous connections and invitation reuse) largely restate the schema text. Baseline 3 applies since the schema already carries the precise semantics, including the maximum/minimum bounds the description omits.
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?
States a specific verb and resource ('Create a private client connection token and an invitation') and immediately names what is returned ('connection commands and display_text for the target user'). This clearly separates it from the session_* and execute_command siblings, which operate on existing sessions rather than provisioning a new client.
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?
Gives an explicit, ordered workflow: present the connection instructions to the user, then call list_clients with the returned client_token and wait_ms=60000, then report whether a device connected or the wait timed out. It names the alternative tool and the exact arguments to pass, 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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. |
| 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. |
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.
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.
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.
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.
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.
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.
List online devices belonging to the token, with their identifiers and metadata. After create_client generates connection instructions, you MUST call this tool with the returned client_token and wait_ms=60000 to check whether a device connects, with a 60-second timeout. A positive wait_ms waits while no device is online; any online device completes the wait immediately. An empty array means no device was online when the call returned; after the 60-second wait, report that the connection check timed out. Waiting calls also include status: waiting or connected. Invalid, expired or revoked tokens cannot be used for further waits.
| Name | Required | Description | Default |
|---|---|---|---|
| wait_ms | No | Maximum connection wait in milliseconds while no device is online, 0–60000. After generating connection instructions, you MUST set this to 60000 (60-second timeout). 0 returns a snapshot immediately. | |
| 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. |
| Name | Required | Description |
|---|---|---|
| status | No | Connection wait status: waiting or connected. |
| clients | Yes | Online devices owned by this token; an empty array means none are currently online. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses important behavior: a positive wait_ms blocks while no device is online, any online device completes the wait immediately, an empty array means no device was online when the call returned, and waiting calls include status values of waiting or connected. It also states that invalid, expired, or revoked tokens cannot be used for further waits, adding useful operational constraints.
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 reasonably front-loaded, beginning with the tool's purpose before moving into the mandatory workflow and wait semantics. It is slightly dense and repeats the 60-second/wait_ms=60000 detail already covered in the schema, but nearly every sentence adds operational guidance.
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?
Given the output schema, the description need not explain return values. It covers the purpose, the mandatory follow-up workflow, wait behavior, timeout meaning, empty-array interpretation, waiting statuses, and token constraints. An agent has enough information to call this tool correctly in context.
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 100%, so the baseline is 3. The description adds meaningful semantics for wait_ms: it explains positive waiting behavior, the required 60000 value after create_client, and that an empty array reflects no online device at return time. It does not add much beyond the schema for client_token, but the added wait semantics justify a score above baseline.
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 states a specific verb and resource: 'List online devices belonging to the token, with their identifiers and metadata.' It also distinguishes the tool from create_client by describing the follow-up workflow in which this tool is used, so an agent can identify its role without opening the schema.
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?
The description gives clear usage context: after create_client generates connection instructions, the agent MUST call this tool with the returned client_token and wait_ms=60000. It also explains positive wait behavior and the meaning of an empty array. However, it does not explicitly name alternative sibling tools or state when another listing tool would be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Control an existing session with action=input, interrupt, eof or stop; does not create a new shell. Reuse session_id to preserve state while its shell lives. Every result includes action. input requires input text (no automatic newline) and returns accepted: the request was sent, not consumed or completed. Input reaches the program currently reading stdin. interrupt requests SIGINT for the terminal foreground process group on Linux/macOS, without forcibly stopping the whole session; Windows pipes do not support it. eof follows queued input: canonical Linux/macOS terminals receive their configured VEOF character, which may first flush pending input and require another EOF; raw mode or disabled VEOF is an error. Windows EOF permanently closes stdin while keeping output readable. EOF at a shell prompt may exit it. For interrupt/eof check list_clients.client_info.session_controls; delivered=true means the client acknowledged the OS operation within 5 seconds, not that the program stopped. stop cancels the whole session and accepts only optional wait_ms (default 1000, range 0–20000); done/status/canceled confirm the outcome. accepted alone never proves termination. If stop returns done=false, use session_read to check further state and output. Repeated stop does not resend pending cancellation and returns terminal state for an ended session; other actions error on ended sessions. Unknown or unauthorized sessions error. Only input accepts input; only stop accepts wait_ms. Input, interrupt and terminal EOF may repeat side effects; do not blindly retry. Timeout or cancellation can leave delivery uncertain. Use session_read to verify effects and drain output.
| Name | Required | Description | Default |
|---|---|---|---|
| input | No | Required only for action=input; omit for other actions. Text is sent as provided without an added newline; include a newline to submit a shell command or prompt response. | |
| action | Yes | Operation on this session: input sends stdin text (requires input); interrupt signals the foreground task; eof ends input according to platform semantics; stop cancels the entire session (optional wait_ms). | |
| wait_ms | No | Only for action=stop: maximum wait for a terminal result in milliseconds, 0–20000; default 1000. 0 returns a snapshot immediately. Omit for all other actions. | |
| session_id | Yes | Session identifier | |
| 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. |
| Name | Required | Description |
|---|---|---|
| action | Yes | The session_control action this result describes; determines which acknowledgment or terminal fields apply. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes far beyond the annotations (destructive, non-idempotent, open-world) by explaining what 'accepted' means, that input reaches whatever reads stdin, platform-specific SIGINT and EOF behavior, that EOF can exit a shell prompt, that stop's done=false requires session_read follow-up, and that timeout can leave delivery uncertain. It also warns against blind retries, matching the non-idempotent annotation.
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?
Front-loads the action list, but the rest is a dense run-on paragraph mixing platform rules, result semantics, and retry guidance. Almost every sentence carries information, yet the lack of structure makes it harder to scan than a complex tool warrants.
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?
Given the complexity, annotations, 100% schema coverage, and an output schema, the description covers the operational caveats an agent needs: platform-specific behavior, uncertainty around accepted/delivered, retry safety, and ended-session behavior. Nothing critical is omitted.
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 coverage is 100% and the schema already documents input, action, wait_ms, and token semantics. The description still adds value by clarifying cross-action constraints ('Only input accepts input; only stop accepts wait_ms') and by giving behavioral meaning to the enum values (interrupt = SIGINT to foreground process group, eof = VEOF/raw-mode caveats).
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?
States a specific verb and resource ('Control an existing session') and enumerates all four actions. It immediately distinguishes itself from session creation with 'does not create a new shell', which separates it from session_start/create_client.
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?
Explicitly routes verification to session_read ('Use session_read to verify effects and drain output') and names list_clients.client_info.session_controls as the precheck for interrupt/eof. It doesn't explicitly contrast when to choose eof vs stop vs session_start, but the action semantics make the selection largely evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List retained sessions owned by the selected client token, optionally filtered by client_id. Does not require an online device. Returns session_id, device, original command, timestamps, lifecycle status and retained output cursor range, sorted by start time. Use output_start_cursor to read retained output; output_end_cursor skips to the current end. Finished records expire after 30 minutes or may be evicted when new sessions start. No shell state or live working directory is inferred. Only this token's sessions are visible.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. | |
| 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. |
| Name | Required | Description |
|---|---|---|
| sessions | Yes | Retained sessions owned by this client token, optionally filtered by device. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as a safe read-only operation, and the description adds substantial extra context: expiration after 30 minutes, possible eviction when new sessions start, visibility limited to this token, no inferred shell state, and sorted results. These are meaningful behavioral traits beyond the structured annotations.
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 definition is front-loaded with purpose and scope, and most sentences carry useful information. However, it runs long and the final sentence ('Only this token's sessions are visible') largely restates the ownership scope already given in the opening clause.
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?
Despite having an output schema, the description still usefully names return fields, sorting order, cursor semantics, expiration behavior, and visibility scope. For a read-only list tool with complete schema coverage, this is fully sufficient for correct invocation.
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 coverage is 100%, so the schema already documents both parameters thoroughly. The description adds only that client_id is an optional filter; it does not add syntax or constraints beyond what the schema provides, so baseline 3 is appropriate.
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 gives a specific verb and resource ('List retained sessions') plus a precise ownership scope ('owned by the selected client token'). It distinguishes the listing operation from reading retained output by pointing to output_start_cursor/output_end_cursor, so an agent can tell it apart from session_read without opening schemas.
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 clearly states that no online device is required and explains how to use the returned cursor fields to read output or jump to the current end. It does not explicitly contrast itself with session_read or session_control, but the context is clear enough for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read incremental session output and current state, limited by max_bytes (default 16384, maximum 65536; UTF-8 characters are not split). Resume from next_cursor; has_more=true means retained output remains, including when done=true. Continue draining until has_more=false even after the process exits. done and exit_code describe the entire session, not individual commands in a persistent shell. Determine command completion from program output. Empty output with done=false does not confirm command completion. Returns immediately if output or a terminal state is available; otherwise waits up to wait_ms. Dropped output sets truncated=true and reading resumes at the earliest retained byte; pagination alone does not set truncated. A cursor beyond available output or inside a UTF-8 character is an error. Terminal result fields are included only when done=true.
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | Output byte offset, initially 0; subsequent reads accept the previous next_cursor. | |
| wait_ms | No | Wait up to this many milliseconds for output | |
| max_bytes | No | Maximum output bytes per read, 4–65536; default 16384. May return fewer bytes to preserve UTF-8 boundaries. Continue with next_cursor while has_more=true. | |
| session_id | Yes | Session identifier | |
| 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. |
| Name | Required | Description |
|---|---|---|
| done | Yes | True when a terminal result is available or the device connection closed. False means no terminal result is available yet. |
| error | No | Optional execution or connection error. A disconnect does not prove the remote process completed successfully. |
| output | Yes | Combined terminal output from the requested cursor; may contain echoed input. |
| canceled | No | True only when the target reported cancellation; a disconnect alone does not confirm cancellation. |
| has_more | Yes | Whether more retained output remains after next_cursor. May be true even when done=true; continue reading to drain output. |
| exit_code | No | Reported process exit code: 0 means success; -1 means execution failed, was interrupted, or the device disconnected before a normal exit report. |
| timed_out | No | 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. |
| session_id | Yes | Session identifier used by session_read and session_control. |
| next_cursor | Yes | Byte offset immediately after the returned output. Pass it as cursor for the next session_read, including when done=true and has_more=true. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description still discloses non-obvious behavior: UTF-8 characters are never split, max 65536 bytes, truncated=true only on dropped output (not pagination), errors for out-of-range or mid-character cursors, and terminal fields appearing only when done=true. That is exactly the additional context the annotations cannot provide.
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?
Every sentence carries a distinct rule and the read/pagination semantics are front-loaded. The density of a single unbroken paragraph of edge-case clauses makes it harder to scan than a short bulleted form, but there is little true filler.
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?
An output schema exists, so return fields need no explanation; the description instead covers what an agent cannot infer — draining behavior, truncation causes, error conditions, and the distinction between session-level and command-level completion. For a stateful paginated read tool this is essentially complete.
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 coverage is 100%, so the baseline is 3, but the description earns credit by explaining boundary behavior the schema does not: default and maximum max_bytes, that fewer bytes may be returned to preserve UTF-8 boundaries, that a read returns immediately if data or a terminal state is available, otherwise waits up to wait_ms, and that a cursor is a next_cursor from a prior read.
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 opens with a specific verb and resource — "Read incremental session output and current state" — and scopes it by max_bytes and cursor, so an agent knows exactly what this retrieves. It never names a sibling (e.g. session_control or session_list) to contrast against, so sibling differentiation is implied by the read-only incremental scope rather than stated.
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?
Strong operational guidance: continue with next_cursor while has_more=true, drain until has_more=false even after process exit, determine command completion from program output rather than empty reads, and expect an immediate return when output or a terminal state exists. No alternative tool is named for cases where this is the wrong call, which keeps it short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start an interactive or long-running process in a fresh shell on the selected device and return session_id before completion. This does not automatically create a persistent shell: a one-shot command ends its session when it exits. To preserve working directory, variables, functions or an activated environment across commands, explicitly launch a shell that keeps reading stdin (for example, bash -i on Linux/macOS where available), then send subsequent commands through session_control(action=input) using the same session_id. Repeated session_start calls create independent processes. The interpreter is reported by list_clients as client_info.shell; choose a command suitable for the target platform. Linux/macOS use a PTY; Windows uses pipes without terminal emulation. Use session_read for output and session_control(action=stop) for cancellation. Shell state lasts only while that shell is alive; client disconnection terminates sessions and reconnect does not restore them. Each token retains up to six sessions. Finished records may expire after 30 minutes or be evicted when later sessions start.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. |
| Name | Required | Description |
|---|---|---|
| cursor | Yes | Initial output byte cursor, always 0 for a new session. |
| session_id | Yes | Session identifier used by session_read and session_control. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the destructive/openWorld annotations: PTY on Linux/macOS vs pipes without terminal emulation on Windows, client disconnection terminates sessions and reconnect does not restore them, shell state lifetime, a six-session-per-token cap, and 30-minute expiry/eviction. These are non-obvious operational constraints an agent could not infer elsewhere.
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?
Front-loads purpose and the return value, then layers constraints in a logical order. It is dense and long, but nearly every sentence carries distinct behavioral information; a tighter grouping of the lifetime/expiry clauses would help slightly.
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?
For a session-spawning mutation tool with an output schema, the description covers spawning semantics, persistence caveats, platform differences, lifecycle limits, and the follow-up tools. Nothing an agent needs to invoke it correctly is missing.
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 coverage is 100%, so parameters are already documented and the baseline is 3. The description adds platform-selection context ('interpreter is reported by list_clients as client_info.shell; choose a command suitable for the target platform') but says nothing extra about cwd, env, timeout_ms, or client_id semantics.
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?
States a specific verb and resource ('Start an interactive or long-running process in a fresh shell') and immediately clarifies the return (session_id). The 'fresh shell' and one-shot-exit language distinguishes it from execute_command and from session_control.
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?
Explicitly says what it does NOT do (no automatic persistent shell) and gives the exact alternative pattern (launch bash -i, then session_control(action=input) with the same session_id). Also routes output reading to session_read and cancellation to session_control(action=stop), and notes repeated calls create independent processes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
create_client2 fields changedOutput schema / properties / next_actionRemoved value: -{
- "additionalProperties": false,
- "description": "Next step to perform. Invitation creation returns the exact tool call and deadline; other tools return human-readable guidance.",
- "properties": {
- "arguments": {
- "additionalProperties": false,
- "description": "Arguments for the next tool call.",
- "properties": {
- "client_token": {
- "description": "Private credential for this target group. Pass as client_token with management access (including stdio and no-password mode) or as the MCP bearer token for device-scoped access.",
- "type": "string"
- },
- "wait_ms": {
- "description": "Server-side connection wait duration in milliseconds.",
- "type": "integer"
- }
- },
- "required": [
- "client_token",
- "wait_ms"
- ],
- "type": "object"
- },
- "instructions": {
- "description": "Workflow guidance for completing the next action.",
- "type": "string"
- },
- "tool": {
- "description": "Name of the next MCP tool to call.",
- "type": "string"
- },
- "until": {
- "description": "UTC RFC 3339 deadline for following this action.",
- "type": "string"
- }
- },
- "required": [
- "tool",
- "arguments",
- "until",
- "instructions"
- ],
- "type": "object"
-}Output schema / requiredPrevious value: -[
- "client_token",
- "multi_device",
- "invitation",
- "expires_at",
- "next_action",
- "macos_linux_command",
- "windows_powershell_command",
- "display_text"
-]New value: +[
+ "client_token",
+ "multi_device",
+ "invitation",
+ "expires_at",
+ "macos_linux_command",
+ "windows_powershell_command",
+ "display_text"
+]list_clients3 fields changedInput schema / properties / wait_ms / descriptionPrevious value: -"Maximum connection wait in milliseconds while no device is online. 0 returns a snapshot immediately."New value: +"Maximum connection wait in milliseconds while no device is online, 0–60000. After generating connection instructions, you MUST set this to 60000 (60-second timeout). 0 returns a snapshot immediately."Input schema / properties / wait_ms / maximumPrevious value: -20000New value: +60000Output schema / properties / next_actionRemoved value: -{
- "description": "Next step to perform. Invitation creation returns the exact tool call and deadline; other tools return human-readable guidance.",
- "type": "string"
-}session_control1 field changedOutput schema / oneOfPrevious value: -[
- {
- "additionalProperties": false,
- "properties": {
- "accepted": {
- "description": "Whether the action was sent to the device connection; this does not confirm it was consumed or completed.",
- "type": "boolean"
- },
- "action": {
- "description": "The session_control action this result describes; determines which acknowledgment or terminal fields apply.",
- "enum": [
- "input"
- ],
- "type": "string"
- }
- },
- "required": [
- "accepted",
- "action"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "action": {
- "description": "The session_control action this result describes; determines which acknowledgment or terminal fields apply.",
- "enum": [
- "interrupt"
- ],
- "type": "string"
- },
- "delivered": {
- "description": "True only after the client confirms it performed the requested signal or EOF operation. Does not guarantee the program consumed it, stopped or exited.",
- "type": "boolean"
- }
- },
- "required": [
- "delivered",
- "action"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "action": {
- "description": "The session_control action this result describes; determines which acknowledgment or terminal fields apply.",
- "enum": [
- "eof"
- ],
- "type": "string"
- },
- "delivered": {
- "description": "True only after the client confirms it performed the requested signal or EOF operation. Does not guarantee the program consumed it, stopped or exited.",
- "type": "boolean"
- }
- },
- "required": [
- "delivered",
- "action"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "accepted": {
- "description": "True if a cancellation request was sent or is pending. False for a session already ended before this call. This alone never confirms termination.",
- "type": "boolean"
- },
- "action": {
- "description": "The session_control action this result describes; determines which acknowledgment or terminal fields apply.",
- "enum": [
- "stop"
- ],
- "type": "string"
- },
- "already_done": {
- "description": "True if the session was already ended when this stop call began; no new cancellation request is sent.",
- "type": "boolean"
- },
- "canceled": {
- "description": "True only when the target reported cancellation; a disconnect alone does not confirm cancellation.",
- "type": [
- "null",
- "boolean"
- ]
- },
- "done": {
- "description": "True when a terminal result is available or the device connection closed; status and canceled identify the outcome.",
- "type": "boolean"
- },
- "error": {
- "description": "Optional execution or connection error. A disconnect does not prove the remote process completed successfully.",
- "type": "string"
- },
- "exit_code": {
- "description": "Reported process exit code: 0 means success; -1 means execution failed, was interrupted, or the device disconnected before a normal exit report.",
- "type": [
- "null",
- "integer"
- ]
- },
- "next_action": {
- "description": "Next step to perform. Invitation creation returns the exact tool call and deadline; other tools return human-readable guidance.",
- "type": "string"
- },
- "session_id": {
- "description": "Session identifier used by session_read and session_control.",
- "type": "string"
- },
- "status": {
- "description": "stopping: cancellation pending. stopped: terminal cancellation confirmed. finished: ended for another reason, including disconnection.",
- "enum": [
- "stopping",
- "stopped",
- "finished"
- ],
- "type": "string"
- },
- "timed_out": {
- "description": "True if the target reported that the process execution timeout elapsed.",
- "type": [
- "null",
- "boolean"
- ]
- }
- },
- "required": [
- "session_id",
- "accepted",
- "done",
- "status",
- "already_done",
- "action"
- ],
- "type": "object"
- }
-]New value: +[
+ {
+ "additionalProperties": false,
+ "properties": {
+ "accepted": {
+ "description": "Whether the action was sent to the device connection; this does not confirm it was consumed or completed.",
+ "type": "boolean"
+ },
+ "action": {
+ "description": "The session_control action this result describes; determines which acknowledgment or terminal fields apply.",
+ "enum": [
+ "input"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "accepted",
+ "action"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "action": {
+ "description": "The session_control action this result describes; determines which acknowledgment or terminal fields apply.",
+ "enum": [
+ "interrupt"
+ ],
+ "type": "string"
+ },
+ "delivered": {
+ "description": "True only after the client confirms it performed the requested signal or EOF operation. Does not guarantee the program consumed it, stopped or exited.",
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "delivered",
+ "action"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "action": {
+ "description": "The session_control action this result describes; determines which acknowledgment or terminal fields apply.",
+ "enum": [
+ "eof"
+ ],
+ "type": "string"
+ },
+ "delivered": {
+ "description": "True only after the client confirms it performed the requested signal or EOF operation. Does not guarantee the program consumed it, stopped or exited.",
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "delivered",
+ "action"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "accepted": {
+ "description": "True if a cancellation request was sent or is pending. False for a session already ended before this call. This alone never confirms termination.",
+ "type": "boolean"
+ },
+ "action": {
+ "description": "The session_control action this result describes; determines which acknowledgment or terminal fields apply.",
+ "enum": [
+ "stop"
+ ],
+ "type": "string"
+ },
+ "already_done": {
+ "description": "True if the session was already ended when this stop call began; no new cancellation request is sent.",
+ "type": "boolean"
+ },
+ "canceled": {
+ "description": "True only when the target reported cancellation; a disconnect alone does not confirm cancellation.",
+ "type": [
+ "null",
+ "boolean"
+ ]
+ },
+ "done": {
+ "description": "True when a terminal result is available or the device connection closed; status and canceled identify the outcome.",
+ "type": "boolean"
+ },
+ "error": {
+ "description": "Optional execution or connection error. A disconnect does not prove the remote process completed successfully.",
+ "type": "string"
+ },
+ "exit_code": {
+ "description": "Reported process exit code: 0 means success; -1 means execution failed, was interrupted, or the device disconnected before a normal exit report.",
+ "type": [
+ "null",
+ "integer"
+ ]
+ },
+ "session_id": {
+ "description": "Session identifier used by session_read and session_control.",
+ "type": "string"
+ },
+ "status": {
+ "description": "stopping: cancellation pending. stopped: terminal cancellation confirmed. finished: ended for another reason, including disconnection.",
+ "enum": [
+ "stopping",
+ "stopped",
+ "finished"
+ ],
+ "type": "string"
+ },
+ "timed_out": {
+ "description": "True if the target reported that the process execution timeout elapsed.",
+ "type": [
+ "null",
+ "boolean"
+ ]
+ }
+ },
+ "required": [
+ "session_id",
+ "accepted",
+ "done",
+ "status",
+ "already_done",
+ "action"
+ ],
+ "type": "object"
+ }
+]create_client1 field changedInput schema / properties / timeout_secondsAdded value: +{
+ "default": 300,
+ "description": "Invitation lifetime in seconds, as a positive integer. Default 300 (5 minutes). Expiry prevents invitation redemption; it does not disconnect devices that have already connected.",
+ "maximum": 9223372036,
+ "minimum": 1,
+ "type": "integer"
+}list_clients2 fields changedOutput schema / properties / clients / items / properties / client_info / properties / session_controlsAdded value: +{
+ "description": "Supported acknowledged session operations: interrupt and/or eof. An empty list means these operations are unavailable; update older clients if needed.",
+ "items": {
+ "type": "string"
+ },
+ "type": [
+ "null",
+ "array"
+ ]
+}Output schema / properties / clients / items / properties / client_info / requiredPrevious value: -[
- "hostname",
- "platform",
- "arch",
- "shell",
- "default_cwd",
- "client_version"
-]New value: +[
+ "hostname",
+ "platform",
+ "arch",
+ "shell",
+ "default_cwd",
+ "client_version",
+ "session_controls"
+]session_controlsession_listsession_read5 fields changedInput schema / properties / max_bytesAdded value: +{
+ "default": 16384,
+ "description": "Maximum output bytes per read, 4–65536; default 16384. May return fewer bytes to preserve UTF-8 boundaries. Continue with next_cursor while has_more=true.",
+ "maximum": 65536,
+ "minimum": 4,
+ "type": [
+ "null",
+ "integer"
+ ]
+}Output schema / properties / has_moreAdded value: +{
+ "description": "Whether more retained output remains after next_cursor. May be true even when done=true; continue reading to drain output.",
+ "type": "boolean"
+}Output schema / properties / next_cursor / descriptionPrevious value: -"Output byte offset to pass as cursor on the next session_read."New value: +"Byte offset immediately after the returned output. Pass it as cursor for the next session_read, including when done=true and has_more=true."Output schema / properties / session_id / descriptionPrevious value: -"Session identifier used by session_read, session_write and session_stop."New value: +"Session identifier used by session_read and session_control."Output schema / requiredPrevious value: -[
- "session_id",
- "output",
- "next_cursor",
- "truncated",
- "done"
-]New value: +[
+ "session_id",
+ "output",
+ "next_cursor",
+ "truncated",
+ "has_more",
+ "done"
+]session_start1 field changedOutput schema / properties / session_id / descriptionPrevious value: -"Session identifier used by session_read, session_write and session_stop."New value: +"Session identifier used by session_read and session_control."session_stopsession_writecreate_client4 fields changedInput schema / properties / multi_device / descriptionAdded value: +"True permits multiple simultaneous devices and reuses the invitation until expiry. False allows one device and a single-use invitation."Output schema / additionalPropertiesPrevious value: -trueNew value: +falseOutput schema / propertiesAdded value: +{
+ "client_token": {
+ "description": "Private credential for this target group. Pass as client_token with management access (including stdio and no-password mode) or as the MCP bearer token for device-scoped access.",
+ "type": "string"
+ },
+ "display_text": {
+ "description": "User-facing connection instructions containing credentials and commands for both platforms.",
+ "type": "string"
+ },
+ "expires_at": {
+ "description": "Invitation expiry deadline as a UTC RFC 3339 timestamp.",
+ "type": "string"
+ },
+ "invitation": {
+ "description": "Private invitation credential for target-client authorization; expires at expires_at.",
+ "type": "string"
+ },
+ "macos_linux_command": {
+ "description": "macOS/Linux connection command containing private invitation access.",
+ "type": "string"
+ },
+ "multi_device": {
+ "description": "True permits multiple simultaneous devices and reuses the invitation until expiry. False allows one device and a single-use invitation.",
+ "type": "boolean"
+ },
+ "next_action": {
+ "additionalProperties": false,
+ "description": "Next step to perform. Invitation creation returns the exact tool call and deadline; other tools return human-readable guidance.",
+ "properties": {
+ "arguments": {
+ "additionalProperties": false,
+ "description": "Arguments for the next tool call.",
+ "properties": {
+ "client_token": {
+ "description": "Private credential for this target group. Pass as client_token with management access (including stdio and no-password mode) or as the MCP bearer token for device-scoped access.",
+ "type": "string"
+ },
+ "wait_ms": {
+ "description": "Server-side connection wait duration in milliseconds.",
+ "type": "integer"
+ }
+ },
+ "required": [
+ "client_token",
+ "wait_ms"
+ ],
+ "type": "object"
+ },
+ "instructions": {
+ "description": "Workflow guidance for completing the next action.",
+ "type": "string"
+ },
+ "tool": {
+ "description": "Name of the next MCP tool to call.",
+ "type": "string"
+ },
+ "until": {
+ "description": "UTC RFC 3339 deadline for following this action.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "tool",
+ "arguments",
+ "until",
+ "instructions"
+ ],
+ "type": "object"
+ },
+ "windows_powershell_command": {
+ "description": "Windows connection command containing private invitation access.",
+ "type": "string"
+ }
+}Output schema / requiredAdded value: +[
+ "client_token",
+ "multi_device",
+ "invitation",
+ "expires_at",
+ "next_action",
+ "macos_linux_command",
+ "windows_powershell_command",
+ "display_text"
+]execute_command11 fields changedInput schema / properties / client_token / descriptionPrevious 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."Input schema / properties / command / descriptionPrevious value: -"Shell command"New value: +"Shell command to execute on the target device."Input schema / properties / cwd / descriptionPrevious 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."Input schema / properties / timeout_ms / descriptionPrevious 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."Output schema / properties / canceled / descriptionAdded value: +"True only when the target reported cancellation; a disconnect alone does not confirm cancellation."Output schema / properties / error / descriptionAdded value: +"Optional execution or connection error. A disconnect does not prove the remote process completed successfully."Output schema / properties / exit_code / descriptionAdded value: +"Reported process exit code: 0 means success; -1 means execution failed, was interrupted, or the device disconnected before a normal exit report."Output schema / properties / stderr / descriptionAdded value: +"Captured standard error, sharing a 1 MiB combined limit with stdout."Output schema / properties / stdout / descriptionAdded value: +"Captured standard output, sharing a 1 MiB combined limit with stderr."Output schema / properties / timed_out / descriptionAdded value: +"True if the target reported that the process execution timeout elapsed."Output schema / properties / truncated / descriptionAdded value: +"True if output exceeded the 1 MiB retention limit. Commands discard excess captured output; sessions discard older buffered bytes."list_clients5 fields changedInput schema / properties / client_token / descriptionPrevious 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."Input schema / properties / wait_ms / descriptionPrevious value: -"Wait up to this many milliseconds while no device is online (0-20000, default 0). After creating an invitation, use 20000 and repeat empty results until connection, invitation expiry, or user cancellation."New value: +"Maximum connection wait in milliseconds while no device is online. 0 returns a snapshot immediately."Output schema / additionalPropertiesPrevious value: -trueNew value: +falseOutput schema / propertiesAdded value: +{
+ "clients": {
+ "description": "Online devices owned by this token; an empty array means none are currently online.",
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "client_id": {
+ "description": "Six-character device identifier. Required to select a device for multi-device tokens.",
+ "type": "string"
+ },
+ "client_info": {
+ "additionalProperties": false,
+ "description": "Device-reported environment metadata. Empty fields mean unknown or not reported.",
+ "properties": {
+ "arch": {
+ "description": "Client process architecture, such as amd64 or arm64.",
+ "type": "string"
+ },
+ "client_version": {
+ "description": "Client application version reported during the connection handshake.",
+ "type": "string"
+ },
+ "default_cwd": {
+ "description": "Client working directory at connection time, inherited by commands when cwd is omitted.",
+ "type": "string"
+ },
+ "hostname": {
+ "description": "Device-reported hostname for display only, not authentication.",
+ "type": "string"
+ },
+ "platform": {
+ "description": "Device-reported operating system.",
+ "type": "string"
+ },
+ "shell": {
+ "description": "Device-reported command interpreter path used by execute_command and session_start. Empty means unknown or not reported.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "hostname",
+ "platform",
+ "arch",
+ "shell",
+ "default_cwd",
+ "client_version"
+ ],
+ "type": "object"
+ },
+ "connected_at": {
+ "description": "UTC connection time in RFC 3339 format.",
+ "type": "string"
+ },
+ "status": {
+ "description": "Device connection display status: Connected, with the latest server-client heartbeat RTT when measured, e.g. Connected · 203ms.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "status",
+ "client_id",
+ "client_info",
+ "connected_at"
+ ],
+ "type": "object"
+ },
+ "type": [
+ "null",
+ "array"
+ ]
+ },
+ "next_action": {
+ "description": "Next step to perform. Invitation creation returns the exact tool call and deadline; other tools return human-readable guidance.",
+ "type": "string"
+ },
+ "status": {
+ "description": "Connection wait status: waiting or connected.",
+ "type": "string"
+ }
+}Output schema / requiredAdded value: +[
+ "clients"
+]session_read5 fields changedInput schema / properties / client_token / descriptionPrevious 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."Input schema / properties / cursor / descriptionPrevious value: -"Byte cursor, initially 0"New value: +"Output byte offset, initially 0; subsequent reads accept the previous next_cursor."Output schema / additionalPropertiesPrevious value: -trueNew value: +falseOutput schema / propertiesAdded value: +{
+ "canceled": {
+ "description": "True only when the target reported cancellation; a disconnect alone does not confirm cancellation.",
+ "type": [
+ "null",
+ "boolean"
+ ]
+ },
+ "done": {
+ "description": "True when a terminal result is available or the device connection closed. False means no terminal result is available yet.",
+ "type": "boolean"
+ },
+ "error": {
+ "description": "Optional execution or connection error. A disconnect does not prove the remote process completed successfully.",
+ "type": "string"
+ },
+ "exit_code": {
+ "description": "Reported process exit code: 0 means success; -1 means execution failed, was interrupted, or the device disconnected before a normal exit report.",
+ "type": [
+ "null",
+ "integer"
+ ]
+ },
+ "next_cursor": {
+ "description": "Output byte offset to pass as cursor on the next session_read.",
+ "type": "integer"
+ },
+ "output": {
+ "description": "Combined terminal output from the requested cursor; may contain echoed input.",
+ "type": "string"
+ },
+ "session_id": {
+ "description": "Session identifier used by session_read, session_write and session_stop.",
+ "type": "string"
+ },
+ "timed_out": {
+ "description": "True if the target reported that the process execution timeout elapsed.",
+ "type": [
+ "null",
+ "boolean"
+ ]
+ },
+ "truncated": {
+ "description": "True if output exceeded the 1 MiB retention limit. Commands discard excess captured output; sessions discard older buffered bytes.",
+ "type": "boolean"
+ }
+}Output schema / requiredAdded value: +[
+ "session_id",
+ "output",
+ "next_cursor",
+ "truncated",
+ "done"
+]session_start7 fields changedInput schema / properties / client_token / descriptionPrevious 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."Input schema / properties / command / descriptionPrevious value: -"Shell command"New value: +"Shell command to execute on the target device."Input schema / properties / cwd / descriptionPrevious 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."Input schema / properties / timeout_ms / descriptionPrevious 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."Output schema / additionalPropertiesPrevious value: -trueNew value: +falseOutput schema / propertiesAdded value: +{
+ "cursor": {
+ "description": "Initial output byte cursor, always 0 for a new session.",
+ "type": "integer"
+ },
+ "session_id": {
+ "description": "Session identifier used by session_read, session_write and session_stop.",
+ "type": "string"
+ }
+}Output schema / requiredAdded value: +[
+ "session_id",
+ "cursor"
+]session_stop5 fields changedInput schema / properties / client_token / descriptionPrevious 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."Input schema / properties / wait_msAdded value: +{
+ "default": 1000,
+ "description": "Maximum wait for a terminal state after requesting cancellation, in milliseconds. 0 returns a snapshot immediately.",
+ "maximum": 20000,
+ "minimum": 0,
+ "type": "integer"
+}Output schema / additionalPropertiesPrevious value: -trueNew value: +falseOutput schema / propertiesAdded value: +{
+ "accepted": {
+ "description": "True if a cancellation request was sent or is pending. False for a session already ended before this call. This alone never confirms termination.",
+ "type": "boolean"
+ },
+ "already_done": {
+ "description": "True if the session was already ended when this stop call began; no new cancellation request is sent.",
+ "type": "boolean"
+ },
+ "canceled": {
+ "description": "True only when the target reported cancellation; a disconnect alone does not confirm cancellation.",
+ "type": [
+ "null",
+ "boolean"
+ ]
+ },
+ "done": {
+ "description": "True when a terminal result is available or the device connection closed; status and canceled identify the outcome.",
+ "type": "boolean"
+ },
+ "error": {
+ "description": "Optional execution or connection error. A disconnect does not prove the remote process completed successfully.",
+ "type": "string"
+ },
+ "exit_code": {
+ "description": "Reported process exit code: 0 means success; -1 means execution failed, was interrupted, or the device disconnected before a normal exit report.",
+ "type": [
+ "null",
+ "integer"
+ ]
+ },
+ "next_action": {
+ "description": "Next step to perform. Invitation creation returns the exact tool call and deadline; other tools return human-readable guidance.",
+ "type": "string"
+ },
+ "session_id": {
+ "description": "Session identifier used by session_read, session_write and session_stop.",
+ "type": "string"
+ },
+ "status": {
+ "description": "stopping: cancellation pending. stopped: terminal cancellation confirmed. finished: ended for another reason, including disconnection.",
+ "enum": [
+ "stopping",
+ "stopped",
+ "finished"
+ ],
+ "type": "string"
+ },
+ "timed_out": {
+ "description": "True if the target reported that the process execution timeout elapsed.",
+ "type": [
+ "null",
+ "boolean"
+ ]
+ }
+}Output schema / requiredAdded value: +[
+ "session_id",
+ "accepted",
+ "done",
+ "status",
+ "already_done"
+]session_write5 fields changedInput schema / properties / client_token / descriptionPrevious 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."Input schema / properties / input / descriptionPrevious value: -"Input bytes as text, e.g. yes\\n"New value: +"Text to send to the session stdin."Output schema / additionalPropertiesPrevious value: -trueNew value: +falseOutput schema / propertiesAdded value: +{
+ "accepted": {
+ "description": "Whether the action was sent to the device connection; this does not confirm it was consumed or completed.",
+ "type": "boolean"
+ }
+}Output schema / requiredAdded value: +[
+ "accepted"
+]create_clientexecute_commandlist_clientssession_readsession_startsession_stopsession_write
Add one secure layer between your agents and this server.