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
The session_* family is cleanly separated by lifecycle role (start / control / read / list), and create_client vs list_clients is unambiguous. The only real overlap is execute_command vs session_start, since both launch work on a device; the descriptions do distinguish one-shot vs interactive/long-running, so an agent can choose, but it takes careful reading.
Two different conventions coexist: verb_noun for the client/command tools (create_client, list_clients, execute_command) and noun_verb for the session tools (session_start, session_read, session_list, session_control). Each family is internally consistent and readable, but the set as a whole mixes orderings.
Seven tools is well-scoped for a remote-agent server: invitation, device discovery, one-shot execution, and a four-tool session lifecycle. No tool appears redundant and nothing feels missing from the count itself.
Session coverage is strong (start, input/interrupt/eof/stop, read, list) and the invite/connect flow is present. The main gap is client token lifecycle: tokens can be created and listed but never revoked or deleted, and there is no single-client detail lookup, which forces workarounds for cleanup and credential hygiene.
Create a private client connection token and an invitation. timeout_seconds sets the invitation lifetime in seconds (default 300, or 5 minutes). Returns a fixed English plain-text template in both text content and structuredContent.display_text; structuredContent also retains the credentials and platform commands. You MUST first present the complete display_text in the language used to communicate with the user. Translate only headings and explanatory prose; when communicating in English, present it verbatim. Preserve all sections, their order, line breaks and plain-text format. Keep commands, URLs, connection tokens, validity numbers and expiry timestamps unchanged. Do not summarize, omit content, or add Markdown formatting such as bold, code fences, tables or links. Then 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 | Fixed English plain-text connection template, identical to the tool's text content. Translate only headings and explanatory prose into the user's conversation language. Preserve all sections, order and line breaks; keep commands, URLs, tokens, validity numbers and expiry timestamps unchanged. Do not omit content or add Markdown formatting. |
| 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?
Beyond the annotations (which only say it is a non-destructive, non-idempotent, closed-world write), the description discloses the return shape (fixed English plain-text template in both text content and structuredContent.display_text, with credentials and platform commands retained) and a mandatory presentation protocol. It also explains timeout semantics: expiry blocks redemption but does not disconnect already-connected devices.
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 mandatory formatting protocol is worth including, but the text is long and partially redundant: the plain-text/structuredContent return is stated, then re-explained across several sentences (preserve sections, no Markdown, do not summarize). The timeout default of 300 is also repeated from the schema, adding bulk without new information.
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 2-param mutation tool with an output schema and full annotation coverage, the description covers the return shape, the required agent behavior, and the follow-up verification step. It says nothing about failure modes (e.g., token creation errors) or permission requirements, which is the main remaining gap.
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 both parameters are already fully documented in the schema. The description's notes on timeout_seconds (default 300) and multi_device (simultaneous connections and invitation reuse) essentially restate the schema rather than adding new semantics, so the baseline of 3 applies.
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 first sentence gives a specific verb and resource: creating a private client connection token plus an invitation. That is clearly distinct from session_start/execute_command-style siblings, though the description never explicitly contrasts itself with them; the only sibling it names is list_clients as a follow-up step.
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 prescribes a concrete workflow: present display_text first, then call list_clients with client_token and wait_ms=60000, then report connected vs timed out. There is no explicit statement of when not to use this tool or which sibling to pick for a different goal, so it falls short of full when/when-not/alternatives coverage.
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_client1 field changedOutput schema / properties / display_text / descriptionPrevious value: -"User-facing connection instructions containing credentials and commands for both platforms."New value: +"Fixed English plain-text connection template, identical to the tool's text content. Translate only headings and explanatory prose into the user's conversation language. Preserve all sections, order and line breaks; keep commands, URLs, tokens, validity numbers and expiry timestamps unchanged. Do not omit content or add Markdown formatting."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.