Skip to main content
Glama

follow

Wait, up to a set timeout, for a background job to report new output or reach a terminal state, returning early on whichever occurs first. Use it to block until a job has something new to show.

Instructions

Wait, bounded, for a background job started by run to have something new to report: new output on the selected stream(s), the job reaching a terminal state (exited/killed/failed), or this call's own bound elapsing - whichever happens first. A timeout is a normal, non-error result, never a hang: it means nothing happened within the bound, nothing more. status, output, and tail remain the complete way to check a job's state and output, whether or not follow is ever called - before this call, after it, or instead of it. cursor, if given, only counts output strictly newer than that seq; omit it to wait for output past whatever already exists on the selected stream(s) at the moment of this call - never for output that already existed before this call started, so a bare call never trivially returns on old backlog. stream picks which stream(s) count toward a return: "stdout", "stderr", or "both" (the default) - this selection scopes the underlying subscription itself, not just what the response later shows, so an arrival on a stream you did not select can never end this call early. Output arrival means a newly materialized line on the selected stream; a buffered fragment without a terminator does not wake the call on its own, but becomes a partial event when the selected stream finalizes; terminal state can still settle the call. timeout_ms bounds how long this one call may wait before returning on its own: omitted, it defaults to 45000ms, a value safe to rely on for any caller; an explicit value above the hard ceiling of 3600000ms (one hour) is silently clamped down to it rather than rejected, since that ceiling only bounds this one call's own subscription lifetime and has no other significance. Asking for longer than the default only pays off with a caller whose own setup actually lets one tool call stay outstanding that long - this tool has no way to see that, and claims nothing about it either way. A caller whose own execution context cannot leave a tool call outstanding for the requested duration - a subagent or background-task turn reclaimed or torn down before this call would return - never gets this tool's benefit, the same as any other call that context cannot hold open that long; that is simply how a tool call behaves there, not something this tool detects or works around. If the calling request is cancelled before this call would otherwise settle, everything it holds open (its subscriptions and its timer) is torn down immediately rather than left to run to its own natural bound. This server also caps how many follow calls may be outstanding (subscribed and waiting) at once, across every connection it serves, at 128; a call made once that cap is already reached is REJECTED outright with a tool error - never queued, never silently delayed - so a caller hitting it should back off and retry shortly, or use status/output/tail instead. That cap is enforced process-wide, not per connection or per client, since this server tracks no connection/client identity today - one connection exhausting it can still deny follow to every other connection, though never silently or without bound.

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": "follow"
  }
}

Input Schema

NameRequiredDescriptionDefault
cursorNoOnly counts output strictly newer than this seq toward a return. Omit to wait for output past whatever is already present on the selected stream(s) at call time (the job's current head seq for the selected stream(s), computed fresh at call time) - never 0, so a bare call never trivially returns on backlog that already existed. Must be a non-negative integer if provided.
job_idYesThe job id returned by a prior run call.
streamNoWhich stream(s) count toward a return. Defaults to "both". This selection scopes the SUBSCRIPTION itself, not just the response - an arrival on a stream you did not select never ends this call early.
timeout_msNoHow long, in milliseconds, this call may wait before returning on its own. Omitted, defaults to 45000ms, safe to rely on for any caller. An explicit value above the hard ceiling of 3600000ms (one hour) is silently clamped down to it rather than rejected. Asking for longer than the default only pays off with a caller whose own setup actually lets one tool call stay outstanding that long - this tool has no way to see that.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior4/5

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

With no annotations, the description carries the whole burden and does so well: timeout is a normal non-error result, default 45000ms, silent clamping above 3600000ms, immediate teardown of subscriptions and timer on cancellation, and a process-wide cap of 128 concurrent followers that is rejected outright rather than queued. The one gap is the shape of the response payload (fields returned on a win vs. a timeout), which matters because there is no output schema; the description only hints at a "partial event".

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 and the first trigger conditions are front-loaded, but the single paragraph runs long and includes hedging that earns little for an agent: repeated disclaimers about caller execution contexts, 'claims nothing about it either way', and restating the ceiling's lack of significance. The content is useful but would be sharper as shorter, separated points.

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

Completeness4/5

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

For a blocking-wait tool with four params, no annotations, and no output schema, this covers almost everything an agent needs: timing bounds, default, clamping, cancellation semantics, concurrency limits with fallback, and stream scoping. Only the response payload structure is left unspecified.

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

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the schema text is nearly verbatim identical to the description's cursor, stream, and timeout_ms explanations, so the description adds almost no meaning beyond structured data. It does reinforce that stream scopes the subscription rather than the response, but that point is already in the schema.

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?

The opening line states a specific verb and resource: wait, bounded, for a background job started by run to produce something new (output, terminal state, or bound elapsing). The trigger conditions are enumerated so an agent can distinguish this blocking wait from the polling siblings status/output/tail without opening any schema.

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?

It explicitly states that status, output, and tail remain the complete way to check a job, before, after, or instead of this call, and repeats that fallback for callers hitting the 128-call cap. Both the when-to-use (waiting for new events) and the when-not-to-use (just check state) are covered.

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