Agenterm

Overview Schema Source Related Servers Discussions Admin

session_stop

DestructiveIdempotent

Request termination of a terminal session started via session_start, optionally waiting for a result. Use it to stop running work and then poll session_read for final output.

Instructions

Request termination of a terminal session created by session_start. Requires its session_id and, with management access (including stdio and no-password mode), its owning client_token; it cannot stop a session owned by another token. Stopping can interrupt writes and lose unsaved work, and cannot undo completed side effects. wait_ms defaults to 1000 and can be 0-20000: 0 returns immediately after sending the request, otherwise wait up to that many milliseconds for a terminal result. accepted=true means a stop request was sent or is already pending, not that termination is confirmed. status=stopping and done=false require polling session_read until done=true; use its output/cursor to collect final output. status=stopped requires a terminal canceled=true report. status=finished means the session ended for another reason; inspect canceled, timed_out, exit_code and error, especially on disconnect. Repeating a stop is safe: an already-ended session returns already_done=true and accepted=false without sending another request. Unknown or unauthorized session IDs are errors. Use session_read to observe progress and session_write for input; stopping does not revoke the device token or disconnect other sessions.

Input Schema

Name	Required	Description
`wait_ms`	No	How long to wait for a terminal result after requesting cancellation (0-20000 ms, default 1000). 0 returns a status snapshot immediately; stopping requires subsequent session_read polling.
`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.

Output Schema

Name	Required	Description
`done`	Yes	True once this session has a terminal result or its device connection closed. Check status, canceled and error to distinguish confirmed cancellation from other endings.
`error`	No	Optional execution or connection error. A disconnect does not prove the remote process completed successfully.
`status`	Yes	stopping: request pending; poll session_read. stopped: terminal cancellation confirmed. finished: ended for another reason; inspect terminal fields and error.
`accepted`	Yes	True if a cancellation request was sent or is pending. False for a session already ended before this call. This alone never confirms termination.
`canceled`	No	True only when the target reported cancellation; a disconnect alone does not confirm cancellation.
`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.
`session_id`	Yes	Identifier of the owned session; retain it for subsequent read, write and stop calls.
`next_action`	No	Next step to perform. Invitation creation returns the exact tool call and deadline; other tools return human-readable guidance.
`already_done`	Yes	True if the session was already ended when this stop call began; no new cancellation request is sent.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv0.3.1-stdio.2Nov 1, 2026

changedInput schema / properties / client_token / description

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

addedInput schema / properties / wait_ms

Added value: +{
+  "default": 1000,
+  "description": "How long to wait for a terminal result after requesting cancellation (0-20000 ms, default 1000). 0 returns a status snapshot immediately; stopping requires subsequent session_read polling.",
+  "maximum": 20000,
+  "minimum": 0,
+  "type": "integer"
+}

changedOutput schema / additionalProperties
```
Previous value: -trueNew value: +false
```

addedOutput schema / properties

Added 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 once this session has a terminal result or its device connection closed. Check status, canceled and error to distinguish confirmed cancellation from other endings.",
+    "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": "Identifier of the owned session; retain it for subsequent read, write and stop calls.",
+    "type": "string"
+  },
+  "status": {
+    "description": "stopping: request pending; poll session_read. stopped: terminal cancellation confirmed. finished: ended for another reason; inspect terminal fields and error.",
+    "enum": [
+      "stopping",
+      "stopped",
+      "finished"
+    ],
+    "type": "string"
+  },
+  "timed_out": {
+    "description": "True if the target reported that the process execution timeout elapsed.",
+    "type": [
+      "null",
+      "boolean"
+    ]
+  }
+}

addedOutput schema / required

Added value: +[
+  "session_id",
+  "accepted",
+  "done",
+  "status",
+  "already_done"
+]

First observedv0.3.1-stdio.1Nov 1, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Although annotations already flag destructive/idempotent/non-readOnly, the description adds substantial context they cannot convey: stopping can interrupt writes and lose unsaved work, side effects are irreversible, accepted=true only means a request was sent or pending, and status=stopping/done=false requires polling. It also spells out the already_done=true/accepted=false repeat-call behavior, which directly explains the idempotentHint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

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

Front-loaded with purpose, then requirements, risks, wait_ms behavior, and status semantics in a logical order. It is dense but long, and the wait_ms explanation partially duplicates the schema property description, costing a bit of efficiency.

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

Completeness5/5

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

For a destructive, open-world mutation tool this covers everything an agent needs: preconditions, side-effect risk, timeout behavior, the meaning of each status/accepted combination, and the required follow-up call. Even though an output schema exists, the description adds interpretive value about status transitions rather than restating field shapes.

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

Parameters4/5

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 goes further by explaining the ownership rule for client_token ('cannot stop a session owned by another token') and the wait_ms trade-off between 0 and a blocking wait. These are semantic consequences not derivable from the schema's type/range constraints.

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

Purpose5/5

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

Opens with a specific verb+resource ('Request termination of a terminal session') and ties it to the sibling that creates such sessions (session_start). It also implicitly separates itself from session_read and session_write by stating their roles at the end, so an agent can place it precisely among the six siblings.

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

Usage Guidelines5/5

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

Explicitly states when it applies (session created by session_start, owned by the calling token), when it will fail (unknown/unauthorized IDs, sessions owned by another token), and how to retry ('Repeating a stop is safe'). It routes the agent to session_read for polling and session_write for input, and clarifies it does not revoke tokens or disconnect other sessions.

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

Deploy Server