Skip to main content
Glama

output

Read a background job's accumulated stdout and stderr with cursor-based pagination, enabling incremental fetching of new events without blocking.

Instructions

Get a background job's accumulated stdout/stderr output, paginated by a monotonic cursor. Pass after_cursor (from a PRIOR CALL WITH THE SAME stream SELECTION's own next_cursor) to fetch only new events since your last read of that same selection - a cursor is scoped to the exact stream value that produced it, and reusing it with a DIFFERENT stream value can skip an already-retained event on the other stream (start from 0/omit after_cursor instead when switching selections). stream selects stdout, stderr, or both (merged in real line-materialization order, default). Once a selected stream has lost some of its own history - either under its own byte/line cap while the job is still running, or because the job finished and its output later became eligible for job-output retention (see GHANTIKA_JOB_RETENTION_MS/GHANTIKA_MAX_RETAINED_JOBS) - the response discloses a bounded "dropped" count for that stream plus "droppedBeforeCursor" (the lowest seq still retained, or the stream's highest-ever-assigned seq - possibly 0 if no line was ever materialized - when nothing survives) - never which specific lines were lost, and never which of the two causes applied. "dropped" is ordinarily a count of complete lines, but it also counts two narrower events the same way: a not-yet-newline-terminated fragment discarded on reclaim, and a chunk arriving for a stream after its job is already reclaimed - neither is a materialized line, but each is real, permanent loss, so both count too rather than leaving the stream falsely indistinguishable from one that never received anything. For stream:"stdout"/"stderr" this is a scalar pair at the top level; for stream:"both" it is a nested object keyed by stream ({stdout?:{...}, stderr?:{...}}), since each stream's own loss is independent. Three distinct signals, never conflate them: "dropped" means this stream lost something forever; "truncated" means this specific call's own response window (from limit, or from that same loss) does not contain everything currently available; "next_cursor" is simply where to resume paging with the SAME stream selection - it carries no information about loss on its own.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "job_id": "<job_id>"
    },
    "name": "output"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoCap the number of events returned in this call (a positive integer). Omit for no cap - next_cursor still lets you page through incrementally either way.
job_idYesThe job id returned by a prior run call.
streamNoWhich stream to read. Defaults to "both" (merged in real line-materialization order - stdout and stderr never collide on seq, so no synthetic interleave is needed).
after_cursorNoOnly return events after this cursor (from a PRIOR CALL WITH THE SAME stream selection's own next_cursor - a cursor is scoped to the exact selection that produced it, and reusing it with a different stream value can skip an already-retained event on the other stream). Omit or 0 to read from the earliest still-retained event, or when switching stream selections. Must be a non-negative integer.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4/5.0
Behavior4/5

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

With no annotations supplied, the description carries the full transparency burden and does so unusually well: it discloses retention-driven loss, the 'dropped'/'droppedBeforeCursor' fields, the distinction between 'dropped' and 'truncated', and that the cause of loss is deliberately not reported. Gaps remain around failure modes (unknown or expired job_id), permissions, and whether the call mutates any read state, but the behavioral disclosure far exceeds the norm for an unannotated read tool.

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

Conciseness3/5

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

The purpose is front-loaded, but the body is a single dense run-on paragraph with heavy emphasis capitalization and repeated cursor-scoping statements that restate the same rule in both the description and the after_cursor schema. Every point is substantive, yet the same content could be delivered in roughly half the length with clearer sentence breaks.

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?

There is no output schema, so the description must carry return-value semantics, and it does: it defines dropped, droppedBeforeCursor, truncated, and next_cursor and warns against conflating them. For a four-parameter read tool with no annotations, an agent has everything needed to page correctly and interpret loss.

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 already 100%, so a baseline of 3 would be defensible, but the description adds genuine meaning beyond the schema: it explains the hazard of reusing a cursor across different stream values, clarifies that 'both' is merged in real materialization order rather than synthetically interleaved, and states the response shape changes between scalar and nested 'dropped' objects depending on stream.

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 opening clause gives a specific verb and resource ('Get a background job's accumulated stdout/stderr output') plus the paging mechanism ('paginated by a monotonic cursor'). It is clear what the tool returns and that it is a historical read rather than a live stream, but it never names or contrasts itself with siblings like tail or follow, so an agent must infer that boundary.

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?

The description is explicit about intra-operation usage: when to pass after_cursor, when to omit it or start from 0 ('when switching stream selections'), and how stream values scope a cursor. What it lacks is tool-selection guidance - it never states when to call this versus tail, follow, or status, which is the main ambiguity left for an agent choosing among six sibling tools.

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

Deploy Server

Other Tools