Skip to main content
Glama
worker-mcp
by noosxe

List workers

list_workers
Read-onlyIdempotent

Lists live workers with IDs, status, current runs, and pending approvals to help you find a worker or lost run ID. Use resumable to locate saved conversations that spawn_worker can continue.

Instructions

List the live workers: id, name, provider, workspace, status, current run, the number of approvals waiting and the latest runs. Use it to find a worker or a run id you lost. Closed and crashed workers are not listed, but their runs can be read with get_run for a while. With resumable: true it also lists saved conversations that spawn_worker({ resumeFrom }) could continue, newest first, bounded by limit (default 10): id to pass, name, workspace, last activity, last run, cut-off call count, context size in tokens, and why one cannot be resumed (live elsewhere, damaged, over the context limit). What comes from the saved conversation sits under untrustedSession. server.bootId and server.startedAt identify this server process: if they changed since you last looked, the server restarted and every id you hold (w_, r_, a_) is gone.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_workers"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoWith resumable: at most this many (default 10, max 50).
resumableNoList saved conversations that spawn_worker({ resumeFrom }) could continue (from earlier server processes too), newest first, instead of the live workers.

Output Schema

NameRequiredDescriptionDefault
serverYesWhich server process answered. If it differs from what you saw earlier, the server restarted: every worker, run and approval id you hold is gone, and work that was in progress is lost. Check the workspace before redoing anything.
workersYes
resumableNoWith resumable: true: saved conversations, newest first.
auditDegradedYesTrue when the audit log file could not be written; decisions are still made.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changedv0.7.0
    • addedInput schema / properties / limit
      Added value: +{
      +  "description": "With resumable: at most this many (default 10, max 50).",
      +  "maximum": 50,
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • addedInput schema / properties / resumable
      Added value: +{
      +  "description": "List saved conversations that spawn_worker({ resumeFrom }) could continue (from earlier server processes too), newest first, instead of the live workers.",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / resumable
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "With resumable: true: saved conversations, newest first.",
      +  "properties": {
      +    "items": {
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "cwd": {
      +            "type": "string"
      +          },
      +          "lastActiveAt": {
      +            "type": "string"
      +          },
      +          "lastRun": {
      +            "additionalProperties": false,
      +            "description": "The conversation's newest run, from its record.",
      +            "properties": {
      +              "runId": {
      +                "type": "string"
      +              },
      +              "state": {
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "runId",
      +              "state"
      +            ],
      +            "type": "object"
      +          },
      +          "lineage": {
      +            "description": "The conversation's id (its first worker id).",
      +            "type": "string"
      +          },
      +          "model": {
      +            "type": "string"
      +          },
      +          "name": {
      +            "type": "string"
      +          },
      +          "notResumable": {
      +            "description": "Why it cannot be resumed: live here or in another server, damaged, over the context limit, workspace gone.",
      +            "type": "string"
      +          },
      +          "provider": {
      +            "type": "string"
      +          },
      +          "resumable": {
      +            "type": "boolean"
      +          },
      +          "untrustedSession": {
      +            "additionalProperties": false,
      +            "description": "Read from the saved conversation: the worker's own output, so untrusted.",
      +            "properties": {
      +              "contextEstimate": {
      +                "enum": [
      +                  "usage",
      +                  "bytes"
      +                ],
      +                "type": "string"
      +              },
      +              "contextTokens": {
      +                "description": "Estimated tokens a resume would replay.",
      +                "type": "number"
      +              },
      +              "cutOffCalls": {
      +                "description": "Tool calls without a result since the last finished run. Absent when the file was too large to read for the list.",
      +                "type": "number"
      +              },
      +              "cutOffTools": {
      +                "items": {
      +                  "type": "string"
      +                },
      +                "type": "array"
      +              },
      +              "sessionBytes": {
      +                "type": "number"
      +              }
      +            },
      +            "required": [
      +              "sessionBytes",
      +              "contextTokens",
      +              "contextEstimate"
      +            ],
      +            "type": "object"
      +          },
      +          "workerId": {
      +            "description": "Pass as resumeFrom.",
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "workerId",
      +          "lineage",
      +          "provider",
      +          "cwd",
      +          "lastActiveAt",
      +          "resumable"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "shown": {
      +      "type": "number"
      +    },
      +    "total": {
      +      "description": "How many conversations are saved.",
      +      "type": "number"
      +    }
      +  },
      +  "required": [
      +    "total",
      +    "shown",
      +    "items"
      +  ],
      +  "type": "object"
      +}
    • addedOutput schema / properties / server
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Which server process answered. If it differs from what you saw earlier, the server restarted: every worker, run and approval id you hold is gone, and work that was in progress is lost. Check the workspace before redoing anything.",
      +  "properties": {
      +    "bootId": {
      +      "description": "Random id of this server process; it changes on every start.",
      +      "type": "string"
      +    },
      +    "startedAt": {
      +      "description": "When this server process started (ISO 8601).",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "bootId",
      +    "startedAt"
      +  ],
      +  "type": "object"
      +}
    • changedOutput schema / properties / workers / items / properties / recentRuns / items / properties / state / enum
      Previous value: -[
      -  "starting",
      -  "running",
      -  "awaiting_approval",
      -  "completed",
      -  "failed",
      -  "cancelled",
      -  "timed_out"
      -]New value: +[
      +  "starting",
      +  "running",
      +  "awaiting_approval",
      +  "completed",
      +  "failed",
      +  "cancelled",
      +  "timed_out",
      +  "interrupted"
      +]
    • addedOutput schema / properties / workers / items / properties / resumedFrom
      Added value: +{
      +  "description": "The worker id this worker continues (spawn_worker with resumeFrom).",
      +  "type": "string"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "workers",
      -  "auditDegraded"
      -]New value: +[
      +  "server",
      +  "workers",
      +  "auditDegraded"
      +]
  2. Addedv0.6.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already establish read-only, idempotent, closed-world semantics, and the description adds substantial context on top: liveness filtering, time-limited retention of runs for closed workers, default/max limit, newest-first ordering, reasons a conversation cannot be resumed, that saved-conversation data arrives under untrustedSession, and that server.bootId/startedAt changes invalidate every previously held id.

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?

Purpose and usage come first, then the resumable variant, then the restart caveat, so an agent can stop reading early. It is dense and somewhat long, with a field inventory that partly duplicates the output schema and a limit default restated from the schema, which costs a point.

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?

Covers everything an agent needs to call this correctly despite only two optional parameters: mode selection, limits, ordering, excluded records, the retention window for get_run, and the id-invalidation rule after a server restart. Redundant field listings are harmless given an output schema exists.

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; the description nonetheless adds real meaning by spelling out that limit only applies in resumable mode (default 10), that resumable includes conversations from earlier server processes, and what the ordering and returned record set look like. Some of that is return-value detail rather than parameter semantics, keeping it just below the top.

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 and resource ('List the live workers') and immediately enumerates the returned fields (id, name, provider, workspace, status, current run, approvals waiting). It also carves out the distinct resumable-conversation mode so the agent can tell the two behaviors apart without opening the 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?

Gives explicit when-to-use guidance ('Use it to find a worker or a run id you lost') and explicitly routes the excluded cases elsewhere: closed/crashed workers are not listed but their runs are readable via get_run. It also names the consuming sibling for resumable output (spawn_worker({ resumeFrom })), so the agent knows the downstream action.

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