Skip to main content
Glama

Workspace and job state

jobs
Destructive

Inspect, monitor, and control MacroStress workspace tasks: check state and status, read logs, cancel runs, or wait server-side for long-running work to finish.

Instructions

Workspace and task state. Actions: state, status, log, cancel, wait.

wait polls the job server-side, so one call replaces the loop of status and log calls an agent would otherwise run while a long job works; it returns the record status returns, and running says whether to call it again.

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": {
      "action": "<action>"
    },
    "name": "jobs"
  }
}

Input Schema

NameRequiredDescriptionDefault
idNoThe job id that status, log, cancel and wait read: the id a starting tool returned.
tailNoHow many lines of the log to return, counted from the end; the whole log when 0.
actionYesWhat to do with the workspace or one job: state, status, log, cancel or wait. wait holds the call until the job ends or timeout_sec passes; cancel stops the job's process tree and frees its resource.
timeout_secNoHow long wait holds the call, in seconds. The job's record comes back when the time is out; call wait again to keep waiting.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv1.0.2
    • addedInput schema / properties / action / description
      Added value: +"What to do with the workspace or one job: state, status, log, cancel or wait. wait holds the call until the job ends or timeout_sec passes; cancel stops the job's process tree and frees its resource."
    • addedInput schema / properties / id / description
      Added value: +"The job id that status, log, cancel and wait read: the id a starting tool returned."
    • addedInput schema / properties / tail / description
      Added value: +"How many lines of the log to return, counted from the end; the whole log when 0."
    • addedInput schema / properties / timeout_sec
      Added value: +{
      +  "default": 30,
      +  "description": "How long wait holds the call, in seconds. The job's record comes back when the time is out; call wait again to keep waiting.",
      +  "maximum": 120,
      +  "minimum": 0,
      +  "type": "number"
      +}
  2. First observedv0.1.0

TDQS

A3.5/5.0
Behavior3/5

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

The description adds real behavior beyond the annotations by explaining that wait polls server-side, that it returns the same record as status, and that the 'running' field signals whether to call again. However, for a multi-action tool whose annotations collapse to destructiveHint=true for all five actions, the description never disambiguates which actions are pure reads (state, status, log) versus the one that is destructive (cancel stops the process tree). That distinction is the single most safety-relevant fact an agent needs and it is absent.

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 the action list, then a focused paragraph on the one non-obvious action. Every sentence carries information and there is no filler. The only imbalance is that roughly two-thirds of the text is devoted to one of five actions while the destructive one gets a single word.

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?

An output schema exists and the annotations carry the safety profile, so the description need not explain return values in full. It covers the highest-friction action (wait) thoroughly and lists all actions. It falls short only on the mixed read/destructive profile of a multi-action tool and on any context for the 'state' action, which is the least self-explanatory.

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%, so the schema already documents id, tail, action, and timeout_sec with good detail, establishing a baseline of 3. The description reinforces the wait/timeout loop and the return-record identity but adds no parameter meaning beyond what the schema states (e.g., no guidance on sensible tail values or timeout_sec tradeoffs).

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 names the resource ('workspace and task state') and enumerates the five concrete actions (state, status, log, cancel, wait), so an agent knows what capability set it is invoking. It is not a tautology of the title, though 'Workspace and task state' is close to the title 'Workspace and job state'. No sibling tool (guide, series, corpus, run, etc.) competes for this purpose, so explicit differentiation is not needed.

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

Usage Guidelines3/5

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

One action gets genuinely strong guidance: 'wait' is contrasted with 'the loop of status and log calls an agent would otherwise run', naming both the alternative and the condition that selects wait. The other four actions (state, status, log, cancel) receive no when-to-use or when-not-to-use guidance in the description, leaving the agent to infer routing from schema text alone.

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