Skip to main content
Glama
Sign In

Agenterm

by net.agenterm
OverviewDiscussionsAdmin

session_read

Read-onlyIdempotent

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.

Input Schema

NameRequiredDescriptionDefault
cursorNoOutput byte offset, initially 0; subsequent reads accept the previous next_cursor.
wait_msNoWait up to this many milliseconds for output
max_bytesNoMaximum 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_idYesSession identifier
client_tokenYesTarget client connection token, required with management access (including stdio and no-password mode). Device-scoped bearer access implicitly selects its own token.

Output Schema

NameRequiredDescriptionDefault
doneYesTrue when a terminal result is available or the device connection closed. False means no terminal result is available yet.
errorNoOptional execution or connection error. A disconnect does not prove the remote process completed successfully.
outputYesCombined terminal output from the requested cursor; may contain echoed input.
canceledNoTrue only when the target reported cancellation; a disconnect alone does not confirm cancellation.
has_moreYesWhether more retained output remains after next_cursor. May be true even when done=true; continue reading to drain output.
exit_codeNoReported process exit code: 0 means success; -1 means execution failed, was interrupted, or the device disconnected before a normal exit report.
timed_outNoTrue if the target reported that the process execution timeout elapsed.
truncatedYesTrue if output exceeded the 1 MiB retention limit. Commands discard excess captured output; sessions discard older buffered bytes.
session_idYesSession identifier used by session_read and session_control.
next_cursorYesByte offset immediately after the returned output. Pass it as cursor for the next session_read, including when done=true and has_more=true.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • addedInput schema / properties / max_bytes
      Added 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"
+  ]
+}
    • addedOutput schema / properties / has_more
      Added value: +{
+  "description": "Whether more retained output remains after next_cursor. May be true even when done=true; continue reading to drain output.",
+  "type": "boolean"
+}
    • changedOutput schema / properties / next_cursor / description
      Previous 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."
    • changedOutput schema / properties / session_id / description
      Previous value: -"Session identifier used by session_read, session_write and session_stop."New value: +"Session identifier used by session_read and session_control."
    • changedOutput schema / required
      Previous value: -[
-  "session_id",
-  "output",
-  "next_cursor",
-  "truncated",
-  "done"
-]New value: +[
+  "session_id",
+  "output",
+  "next_cursor",
+  "truncated",
+  "has_more",
+  "done"
+]
  2. Changed5 schema fields changed
    • changedInput schema / properties / client_token / description
      Previous value: -"Target client connection token (required when authenticated with the management key)"New value: +"Target client connection token, required with management access (including stdio and no-password mode). Device-scoped bearer access implicitly selects its own token."
    • changedInput schema / properties / cursor / description
      Previous value: -"Byte cursor, initially 0"New value: +"Output byte offset, initially 0; subsequent reads accept the previous next_cursor."
    • changedOutput schema / additionalProperties
      Previous value: -trueNew value: +false
    • addedOutput schema / properties
      Added 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"
+  }
+}
    • addedOutput schema / required
      Added value: +[
+  "session_id",
+  "output",
+  "next_cursor",
+  "truncated",
+  "done"
+]
  3. First observed

TDQS

A4.3/5.0
Behavior5/5

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.

Conciseness4/5

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.

Completeness5/5

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

An output schema exists, so return 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.

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 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.

Purpose4/5

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.

Usage Guidelines4/5

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.

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

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources