Skip to main content
Glama
xpluspro

Awaitless

Official
by xpluspro
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

Awaitless

CI PyPI Python

Adaptive durable execution for coding agents.

Run commands through one execution layer. Quick work returns inline; longer or queued work becomes durable across local, SSH, and Slurm. Your workload stays on infrastructure you already own.

Agents submit work. Awaitless owns execution.

Awaitless is the adaptive durable execution layer between coding agents and the compute they use. It gives agents one stable job contract while reusing your local machine, SSH hosts, and Slurm clusters underneath.

简体中文 · Documentation · Benchmarks · PyPI

One job lifecycle across your existing compute

Coding agent → submit work → Awaitless owns the job lifecycle → Local / SSH / Slurm

Durable jobs

Named scarce-resource queues

Completion and recovery

Stable IDs, state, cancellation, bounded logs, and Artifacts survive client disconnects.

Durable FIFO admission prevents too many jobs from entering a named resource at once.

Exit codes and results remain available by Job ID or replayable completion cursor.

Awaitless owns the job lifecycle, not the hardware. It does not discover resources, understand GPU topology, allocate multiple resources, or replace a cluster scheduler. Operators name queues and set fixed concurrency; Slurm continues to handle requests such as --gpus 2 --mem 64G and all physical cluster scheduling.

Awaitless SSH submit, disconnect, resume, and Artifact demo

Related MCP server: mcp-sidecar

Your coding agent should write code, not babysit jobs

An agent can write its own run → sleep → check loop. The harder problem is making job identity, disconnect recovery, queue admission, cancellation, and result delivery reliable across long workloads and changing sessions. Without that execution layer, the agent repeatedly pulls the same growing log back into its context:

ssh gpu 'run_benchmark > job.log 2>&1 &'
ssh gpu 'tail -n 200 job.log'  # again...
ssh gpu 'tail -n 200 job.log'  # and again...

Awaitless turns that lifecycle into one adaptive execution call and one result boundary:

awaitless run --json --host gpu --artifact results.json -- ./run_benchmark
# quick: {"state":"succeeded","delivery":"inline","exit_code":0,...}
# longer: {"job_id":"job_019F...","state":"running","delivery":"detached",...}

awaitless wait job_019F... --json
# {"state":"succeeded","exit_code":0,"parsed_results":{...}}

Detached JSON also includes job_state, wait_state, delivery_state, and a ready-to-copy next_command. A client-side wait timeout is not a workload failure: use awaitless wait --last --json for the most recently detached Job, or use the returned command with its stable Job ID. To inspect benchmark lines without reading a large tail, use awaitless logs <job-id> --grep 'PASS|FAIL|median|CV'.

Every run is durable before launch. Finishing within the inline window looks like an ordinary command result; crossing it only detaches the waiter. Interrupt the waiter, close the MCP client, or start a fresh agent session: the Job keeps running and its stable ID recovers the result.

Queue work before a named resource is free

Create a durable FIFO queue once, then submit every command immediately:

awaitless queue create gpu0 --concurrency 1

awaitless submit --queue gpu0 -- python train_a.py
awaitless submit --queue gpu0 -- python train_b.py
awaitless submit --queue gpu0 -- python train_c.py

The first command runs and the others report queued. Each starts automatically when capacity becomes available. This is durable admission control for a named scarce resource: fixed concurrency and FIFO ordering, with no priority or preemption. Awaitless never kills running work to make room for a later job.

Operators can also bind adaptive runs to a queue globally or per host:

[hosts.gpu]
hostname = "gpu.example.com"
queue = "gpu0"

The Agent can then call run without choosing a queue or probing the GPU first.

This queue does not discover resources, understand GPU topology, dynamically allocate devices, issue leases, or combine requests such as two GPUs plus 64 GB of memory. Use Slurm or another scheduler for those responsibilities; Awaitless provides the Agent-facing job lifecycle around that scheduler.

Consume whichever job finishes next

v0.7 adds completions ... --drain --json for consuming a small parallel set in one call without client-side cursor bookkeeping. Long jobs can emit structured heartbeat updates with wait --progress-interval 30s. Use --capture-log PATH for command-owned logs and --resource gpu=0 or --device 0 for explicit exclusive admission; terminal results freeze bounded logs, diagnostics, timing, environment, and a SHA-256 identified snapshot.

Submit independent work up front, keep every Job ID, then wait at one durable completion boundary:

awaitless completions job_A job_B job_C --json
# {"completions":[...],"next_cursor":"cmp_...","active_job_ids":[...]}

awaitless completions job_A job_B job_C --after cmp_... --json

The first call returns already-finished work immediately or blocks until at least one selected Job completes. Process the batch before advancing to next_cursor; reusing an older cursor safely replays the same completion IDs. If the client disappears, a new session can continue from the saved cursor. Awaitless makes continuation results durably available—it does not run the agent's next reasoning step or require a resident notification service.

The v0.8 evidence suite replaces historical call-count demos with four questions: does an Agent choose the protocol correctly, does a Job survive faults without duplicate launch, does Awaitless keep execution-management state out of the reasoning loop, and does adaptive run preserve low friction for short commands? See the v0.8 evidence plan.

v0.8 evidence status

Release evidence is model- and commit-specific. The checked-in suite does not carry numbers from earlier versions or from a different model. Run the v0.8 benchmarks, inspect every raw record, then publish a dated report with model, config hash, git commit, skipped workloads, and all failures in the denominator. The reviewed v0.8 evidence report includes the complete raw records and analysis summaries rather than a selected score.

Try the recovery story in 30 seconds

Linux, Python 3.10+, and Bash are required. Run the built-in demo without a persistent install:

uvx --from awaitless-runner awaitless demo --json

The demo submits two local jobs, terminates their first completion waiter, then uses new clients to consume both bounded results and JSON Artifacts by cursor.

For regular CLI use:

uv tool install awaitless-runner
awaitless doctor --json

pip install awaitless-runner works too.

Give it to your coding agent

Add one stdio MCP server to your client's configuration (adapt the outer key to your client):

{
  "mcpServers": {
    "awaitless": {
      "command": "uvx",
      "args": ["awaitless-runner"]
    }
  }
}

The preferred run tool returns quick commands inline and automatically gives longer or queued work a durable handle. Tasks-aware clients can still use run_job, while low-level clients retain submit_job and wait_for_job. Retrying an expensive submission with the same client_request_id cannot launch a duplicate job. For parallel work, every client can use wait_for_completions regardless of MCP Tasks support. The normative identity, lifecycle, continuation, completion, Artifact, and compatibility contract is Awaitless Agent Job Protocol.

Codex plugin

This repository is also a Codex plugin. Its manifest bundles the Awaitless agent skill with the stdio MCP server, which Codex launches through uvx. Install the repository from a local Codex marketplace, then start a new Codex task so the skill and MCP tools are loaded together.

The plugin requires uvx on PATH; the first MCP launch downloads awaitless-runner from PyPI if it is not already cached.

For direct CLI use, the whole loop is:

awaitless run --json --name tests -- python -m pytest -q
# If delivery is detached, save the returned job_id, then:
awaitless wait <job-id> --json
# Or recover the most recent detached job:
awaitless wait --last --json

One interface, three places to run

Backend

What Awaitless adds

Local

Durable process-group tracking, cancellation, bounded logs, and transactional named queues.

SSH

The same job contract plus queues coordinated on the target host, with no remote daemon.

Slurm

Real sbatch scheduling plus durable Slurm IDs, queue/accounting state, exit codes, logs, cancellation, and Artifacts.

Use --backend, --host, or configuration defaults to switch targets without changing how the agent submits and collects work.

Why not just use a shell or tmux?

Tool

Best at

What the agent still has to build

Blocking shell call

Quick inspection and interactive work

Lifecycle management once an engineering command runs longer than expected.

Shell polling / nohup

Keeping a basic command alive

IDs, status, exit-code recovery, bounded logs, cancellation, deduplication, and result parsing.

tmux

Humans detaching from interactive shells, REPLs, and TUIs

A reliable non-interactive job protocol and wrapper glue.

Awaitless

Agent-run builds, tests, benchmarks, remote jobs, and cluster work

Only the command and, optionally, the JSON Artifact to return.

Awaitless does not replace interactive terminals or Slurm. It gives coding agents durable fixed-concurrency queues on local/SSH machines and delegates cluster resource scheduling to Slurm.

How it works

flowchart LR
    A["Coding agent"] -->|"run"| B["Awaitless MCP / CLI"]
    B --> C[("SQLite job record")]
    C --> Q["Optional queue admission"]
    Q -->|"capacity available"| D{"Backend"}
    D --> L["Local process"]
    D --> S["SSH host"]
    D --> H["Slurm allocation"]
    L --> I{"Finished inline?"}
    S --> I
    H --> I
    I -->|"yes: result"| A
    I -->|"no: durable handle"| A
    A -. "reconnect with stable ID" .-> C
    C --> E["Durable completion cursor"]
    E -->|"state + exit code + bounded logs + Artifacts"| A

There is no Awaitless daemon, HTTP service, or hosted sandbox. Each invocation opens the same SQLite store; submitted runners and scheduler jobs outlive the stdio server that created them. Full logs remain on disk while only bounded tails enter the agent context.

Documentation

License

MIT

Available Tools

11 tools
cancel_jobA

Cancel a durable job without relying on a client-side process handle.

ParametersJSON Schema
NameRequiredDescriptionDefault
job_idYes
grace_secondsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.6/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden. It discloses that the tool cancels durable jobs, but does not explain cancellation semantics, what happens to the job, the effect of grace_seconds, or potential side effects. This is a significant gap for a mutating operation.

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

Conciseness5/5

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

The description is a single sentence with no filler. It front-loads the action and resource, and every word adds substantive value.

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

Completeness2/5

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

The description is too terse for a mutating tool with an undocumented parameter. It omits grace_seconds semantics and cancellation behavior, which are essential for correct use. The output schema exists but does not compensate for these gaps.

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 0%, so the description must compensate. It clarifies that job_id identifies the durable job, but it completely ignores grace_seconds, leaving that parameter's purpose unexplained. Partial semantic coverage.

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 description clearly states the action (Cancel) and the resource (a durable job), and adds the qualifier 'without relying on a client-side process handle' which distinguishes it from siblings like run_job or get_job_status. It is specific and unambiguous.

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 phrase 'without relying on a client-side process handle' implies when to use this tool—when you need to cancel a durable job by ID rather than a process handle. However, it does not explicitly list alternatives or exclusions, so it falls short of full guidance.

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

create_queueA

Create an immutable named FIFO queue with a fixed concurrency limit.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYes
concurrencyYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.1/5.0
Behavior4/5

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

With no annotations, the description carries the burden and does disclose critical behavioral traits such as immutability (queue cannot be modified after creation), FIFO ordering, and fixed concurrency limit. These are important lifecycle details. However, it omits error handling such as behavior on duplicate names or permission requirements, so not a perfect score.

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

Conciseness5/5

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

The description is a single sentence that is front-loaded with the verb and resource. Every word earns its place, with no wasted or redundant elements.

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

Completeness3/5

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

For a simple creation tool with an output schema and two parameters, the description covers the main purpose but leaves gaps. It does not mention potential failure scenarios (e.g., duplicate name handling) or usage context relative to sibling tools. The lack of annotations increases the need for these details, making it minimally viable but incomplete.

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?

Since schema description coverage is 0%, the description compensates by mapping 'named' to the name parameter and 'fixed concurrency limit' to the concurrency parameter, giving meaning to the integer. It doesn't provide constraints like positive integer, but it clarifies the role of each parameter.

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 description states a specific verb ('Create') and resource ('queue'), and clearly distinguishes it from sibling job tools by highlighting key properties: immutable, named, FIFO, and fixed concurrency limit. This leaves no ambiguity about the tool's purpose.

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?

Usage is implied by the tool name and context, but the description does not explicitly state when to use this tool versus alternatives or provide any exclusions. For example, it doesn't mention that a queue must be created before submitting jobs, nor does it explain when not to use it.

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

get_job_logsA

Inspect bounded stdout and stderr tails for a known failed or stalled job.

Use after a terminal wait reports failure, timeout, stall, or loss and its bounded result needs focused diagnostics. Do not use as a progress stream, do not repeatedly tail a running healthy Job, and do not use it instead of wait_for_job to learn that work completed.

ParametersJSON Schema
NameRequiredDescriptionDefault
tailNo
job_idYes
max_bytesNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.6/5.0
Behavior4/5

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

No annotations are provided, so the description carries the burden. It discloses that the logs are bounded ('bounded stdout and stderr tails'), intended for failed/stalled jobs, and not for progress monitoring. It does not specify what happens if the job is healthy or if logs are empty, but the core behavioral constraints are clear. A score of 4 reflects strong disclosure without full detail.

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

Conciseness5/5

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

The description is two short paragraphs, each sentence adds value. The first sentence defines purpose, the second gives clear usage guidelines and exclusions. No fluff or repetition.

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?

The tool has an output schema (which likely describes the log structure), and the description explains when to use it. It covers the main use case and boundary conditions. It lacks details on parameter semantics (like tail units or max_bytes limits) and edge cases (e.g., job not found), but for a read-only diagnostic tool with an output schema, this is sufficient. A 4 is warranted given the strong usage guidance offsets minor gaps.

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 description coverage is 0% and there are three parameters. The description does not detail parameters, but it introduces the concept of 'bounded' tails and 'stdout/stderr' which hints at the meaning of tail and max_bytes. It does not explicitly map parameters, but the context gives enough for a reasonable inference. Given zero coverage, the description partially compensates, hence a 4.

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 description states a specific verb+resource ('Inspect bounded stdout and stderr tails') and narrows the scope to 'a known failed or stalled job', clearly distinguishing it from sibling tools like get_job_status or wait_for_job. It precisely defines what the tool does and does not do.

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?

The description explicitly states when to use the tool ('after a terminal wait reports failure, timeout, stall, or loss'), what it should not be used for ('do not use as a progress stream, do not repeatedly tail a running healthy Job'), and names the alternative (wait_for_job) for learning completion. This is exemplary usage guidance.

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

get_job_statusA

Get one immediate, non-waiting state snapshot for a known job_id.

Use only when the caller needs current status now. Do not use this to wait for completion or build a polling loop; use wait_for_job for one Job or wait_for_completions for several. This tool never starts or retries work.

ParametersJSON Schema
NameRequiredDescriptionDefault
job_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.4/5.0
Behavior4/5

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

With no annotations, the description carries the full burden of behavioral disclosure. It states the tool is non-waiting and 'never starts or retries work,' which are important behavioral traits beyond what the schema conveys. It could add more about error handling or response format, but output schema covers the latter.

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

Conciseness5/5

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

The description is concise (three sentences), front-loaded with the core purpose, and every sentence adds value: purpose, usage guidance, and behavioral caveat. No redundant or filler content.

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?

For a simple one-parameter status-check tool, the description covers purpose, usage guidance, and behavioral limitations. An output schema exists, so return values need no explanation. The context is complete and effective.

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

Parameters2/5

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

Schema has 0% description coverage, so the description must compensate. It only refers to 'known job_id' without adding format, type, or example context. The schema's 'Job Id' title is minimal, and the description doesn't meaningfully enrich parameter meaning, leaving the agent to infer from the tool name.

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 description clearly states the function: 'Get one immediate, non-waiting state snapshot for a known job_id.' It uses a specific verb ('Get') and resource ('job_id') and distinguishes from siblings like wait_for_job by explicitly framing this as a non-waiting snapshot.

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?

Provides explicit when-to-use and when-not-to-use guidance: 'Use only when the caller needs current status now. Do not use this to wait for completion or build a polling loop; use wait_for_job for one Job or wait_for_completions for several.' This clearly names alternatives and exclusions.

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

list_jobsB

List recent durable jobs, optionally filtered by state or host.

ParametersJSON Schema
NameRequiredDescriptionDefault
hostNo
limitNo
queueNo
stateNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.2/5.0
Behavior2/5

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It adds 'recent' and 'durable' but does not explain what 'recent' means (e.g., time window, default limit) or whether the list is sorted. It also omits the limit default of 50 and the queue filter, which are visible in the schema but not elaborated in the description. This leaves significant behavioral ambiguity.

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

Conciseness5/5

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

The description is a single concise sentence with no wasted words. It front-loads the core purpose and includes the key filtering capability. This is appropriately sized for the tool's simple nature.

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

Completeness3/5

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

The tool has an output schema and only 4 optional, self-explanatory parameters, so the description need not detail return values. However, it fails to mention the queue filter and the limit parameter, and the phrase 'recent' is vague. Given the low complexity, this is a minimally adequate description with clear gaps but not seriously deficient.

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

Parameters2/5

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

Schema description coverage is 0% and the description mentions only two of four parameters (state and host) as filters. It does not mention 'queue' as a filter or explain 'limit' (number of results). While the parameter names are self-explanatory, the description adds minimal value and does not fully compensate for the lack of schema descriptions, especially for queue and limit.

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 description 'List recent durable jobs, optionally filtered by state or host' clearly states the operation (list), the resource (durable jobs), and the filtering capability. This distinguishes it from sibling tools like get_job_status (single job) and get_job_logs, which serve different purposes.

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

Usage Guidelines2/5

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

The description provides no explicit guidance on when to use this tool versus alternatives like get_job_status or list_queues. It only states what the tool does, leaving the agent to infer appropriate usage from the tool name and siblings. Without exclusions or alternative recommendations, this is minimal guidance.

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

list_queuesA

List named queues and their current queued/active job counts.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.9/5.0
Behavior3/5

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

With no annotations, the description carries the full burden of behavioral disclosure. It clearly implies a read-only operation via the verb 'list', but it does not explicitly state that it makes no modifications, nor does it mention any permissions, pagination, or real-time guarantees. It provides the basic function but lacks additional behavioral context beyond what the name itself implies.

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

Conciseness5/5

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

The description is a single, front-loaded sentence that conveys the essential information without redundancy. Every word earns its place, making it highly concise and well-structured.

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?

Given the tool's simplicity (no parameters) and the presence of an output schema (as indicated in context signals), the description sufficiently covers what the agent needs to know. It accurately describes the scope ('named queues') and the specific data returned (queued/active counts), making it complete for a basic list operation.

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?

The tool has zero parameters, and the schema coverage is 100% (vacuously). Per the rubric, 0 params gives a baseline of 4. The description adds no parameter-specific details, but none are needed since no inputs exist.

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 description clearly states the tool's function: 'List named queues and their current queued/active job counts.' This is a specific verb (list) + resource (named queues) + expected output (queued/active counts), which distinguishes it from sibling tools like list_jobs or create_queue.

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

Usage Guidelines2/5

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

There is no guidance on when to use this tool versus alternatives. It does not mention that this is for viewing queue-level status, nor does it suggest using list_jobs or get_job_status for job-level details. The description provides no context to help the agent decide between this and sibling tools.

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

runA

Default tool for starting one non-interactive command of uncertain duration.

Every command is a durable Job from launch. Commands that finish within the inline timeout return their ordinary bounded result. Longer or queued work returns a detached Job handle without cancelling the workload. Omit queue to use an operator-configured default queue for the selected target.

Do not use this tool for explicit fire-and-forget or batch fan-out; use submit_job. Do not use it when an MCP Tasks handle is explicitly required; use run_job. Do not use it to resume an existing job_id; wait for or inspect that job instead. If a detached handle is returned, keep its job_id and call wait_for_job once when the result is needed rather than polling status.

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdNo
envNo
hostNo
nameNo
queueNo
backendNo
commandYes
artifactsNo
resourcesNo
capture_logsNo
slurm_optionsNo
timeout_secondsNo
client_request_idNo
stall_timeout_secondsNo
inline_timeout_secondsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4/5.0
Behavior5/5

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

No annotations are provided, so the description carries the full burden. It discloses key behaviors: every command is a durable Job from launch, inline-timeout commands return a bound result, longer or queued work returns a detached job handle without cancellation, and the queue defaults to an operator-configured value. These details go beyond what the schema or annotations provide and are genuinely valuable.

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?

The description is front-loaded with a crisp purpose sentence, followed by a compact paragraph on execution behavior and a clear list of alternative-tool guidance. Every sentence adds value, and no unnecessary fluff is present. Slightly long given the 15 parameters remain undocumented, but the text itself is efficient.

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

Completeness2/5

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

The description fully addresses the execution model, job lifecycle, and selection logic. However, with a high parameter count and zero schema description coverage, it leaves the user under-specified for most configuration options (e.g., env, host, backend, slurm_options, capture_logs). Completing all required and optional parameters would require external knowledge not provided here.

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

Parameters1/5

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

Schema description coverage is 0% across all 15 parameters, and the description compensates for only two of them (inline_timeout_seconds and queue). Parameters like cwd, env, host, backend, capture_logs, slurm_options, timeout_seconds, and stall_timeout_seconds remain entirely unexplained. The description fails to provide anywhere near enough guidance for a tool with this many settings.

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 description clearly states the tool's verb+resource: 'starting one non-interactive command of uncertain duration.' It distinguishes itself from siblings by explicitly describing when this tool is the default, and contrasts it with submit_job and run_job. This is a specific, non-tautological purpose statement.

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?

The description explicitly says when to use (one non-interactive command, uncertain duration) and when not to use: fire-and-forget/batch fan-out (use submit_job), MCP Tasks handle required (use run_job), resume existing job (wait_for/inspect). It even gives guidance for what to do with a detached handle: keep job_id and call wait_for_job once. This leaves little ambiguity about tool selection.

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

run_jobA

MCP Tasks compatibility entry point for explicitly creating a Task handle.

A client declaring io.modelcontextprotocol/tasks receives a Task handle immediately. Older clients block and receive the ordinary final tool result. The stable client_request_id makes a lost creation response safe to retry.

Do not choose this for ordinary command execution: use run. Do not choose it for generic asynchronous submission or fan-out: use submit_job. Only retry a lost Task creation with the same client_request_id and identical arguments.

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdNo
envNo
hostNo
nameNo
queueNo
backendNo
commandYes
artifactsNo
resourcesNo
capture_logsNo
slurm_optionsNo
timeout_secondsNo
client_request_idYes
stall_timeout_secondsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4/5.0
Behavior4/5

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

With no annotations, the description must disclose behavior. It explains that clients declaring the tasks protocol receive a Task handle immediately, while older clients block and get the ordinary result, and that client_request_id is stable for retries. This adds nontrivial behavioral context, though it does not cover potential side effects like permissions or lifecycle details.

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?

The description is concise and well-structured, with a clear introduction and practical guidance. It is front-loaded with the purpose and then gives usage constraints. No wasted words, but it could be slightly more structured (e.g., bullet points) for readability, though that is minor.

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

Completeness2/5

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

Despite having an output schema, the tool is complex with 14 parameters and zero schema descriptions. The description focuses on compatibility details and retry semantics but leaves out essential context about how the task is created, what the command array represents, how to configure environment, resources, etc. It is incomplete for an agent to confidently invoke the tool with correct arguments.

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

Parameters2/5

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

Schema coverage is 0%, so the description must explain parameters. It only mentions client_request_id (explaining its role in retries) and implicitly references command, but provides no semantics for the other 12 parameters (cwd, env, host, queue, etc.). For a 14-parameter tool, this is inadequate — agents will not know what most parameters mean or how to set them.

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 description explicitly states it is a 'MCP Tasks compatibility entry point for explicitly creating a Task handle', which clearly identifies the verb and resource. It also distinguishes itself from siblings by saying 'Do not choose this for ordinary command execution: use run' and 'Do not choose it for generic asynchronous submission or fan-out: use submit_job', making its purpose clear and unique.

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?

The description provides explicit when-to-use and when-not-to-use guidance: it should be used for Task handle creation, not for ordinary execution (use run) or async submission (use submit_job). It also gives specific guidance on retrying with the same client_request_id and identical arguments, which is actionable for the agent.

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

submit_jobA

Explicitly submit one asynchronous or fan-out job without waiting.

Omitted backend and host values use the Awaitless configuration defaults. Reuse client_request_id only when retrying the same logical submission; an identical retry returns the original job and a conflicting retry is rejected. A named queue provides FIFO, non-preemptive admission for local or SSH work. Slurm options may contain account, constraint, cpus_per_task, gres, mem, nodes, ntasks, partition, qos, or time. Cluster config supplies defaults.

Do not use this as the default for a single command with uncertain duration; use run. Do not use it for MCP Tasks creation; use run_job. Do not resubmit merely because a client disconnected or a wait timed out: keep the original job_id, or retry the identical logical submission with the same client_request_id if the creation response was lost.

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdNo
envNo
hostNo
nameNo
queueNo
backendNo
commandYes
artifactsNo
resourcesNo
capture_logsNo
slurm_optionsNo
timeout_secondsNo
client_request_idNo
stall_timeout_secondsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.7/5.0
Behavior5/5

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

With no annotations, the description carries full responsibility. It discloses key behaviors: no waiting, defaults for omitted backend/host, client_request_id retry behavior (identical retry returns original, conflicting rejected), FIFO queue semantics, and allowed Slurm options. It also addresses an edge case (lost creation response). No contradictions with annotations (none provided).

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?

The description is moderately long but each sentence adds value. It is front-loaded with purpose, then details defaults, retry, queue, Slurm, and usage warnings. No redundancy; structure is logical. Slightly verbose but well-organized.

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 tool with 14 parameters and no annotations, the description covers important behavioral and usage aspects, including exclusions and retry pitfalls. It does not detail every parameter or the return value, but an output schema exists. Overall, it provides substantial context for a complex tool, though not exhaustive.

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 lacks property descriptions (coverage 0%). The description compensates by explaining backend/host defaults, client_request_id semantics, Slurm options allowed keys, and queue behavior. However, many parameters (cwd, env, artifacts, resources, capture_logs, timeouts) are not explained, leaving gaps. Still, it adds meaningful context for several key parameters.

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 description opens with a clear, specific statement: 'Explicitly submit one asynchronous or fan-out job without waiting.' This distinguishes it from sibling tools like run (synchronous) and run_job (MCP Tasks). Purpose is directly stated and unambiguous.

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?

Explicit guidance is provided: 'Do not use this as the default for a single command with uncertain duration; use run. Do not use it for MCP Tasks creation; use run_job.' It also warns against resubmitting on disconnection/timeout and explains retry semantics, giving clear when-to-use and when-not-to-use context.

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

wait_for_completionsA

Collect durable terminal results across multiple known jobs after a cursor.

Existing completions return immediately. Otherwise the call waits until at least one selected job completes or the optional call-level timeout expires. Reusing the same cursor replays results; advancing to next_cursor consumes the returned batch. A timeout never cancels a managed job.

Submit all independent jobs before calling this tool. Treat delivery as at-least-once: process and deduplicate by completion_id before advancing the cursor. Do not use this for one job, do not poll get_job_status between continuation calls, and never resubmit active jobs after a waiter disconnects.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
job_idsYes
after_cursorNo
timeout_secondsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.9/5.0
Behavior5/5

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

There are no annotations, so the description carries the full burden of behavioral disclosure. It goes beyond a simple 'wait for completions' by revealing durability, immediate return of existing completions, cursor replay/consume semantics, at-least-once delivery with deduplication by completion_id, timeout non-cancellation, and disconnect-related resubmission guidance.

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

Conciseness5/5

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

The description is compact and well-structured in three dense paragraphs: purpose/behavior, cursor semantics, and usage guardrails. Every sentence adds meaningful information, and the first sentence immediately establishes the tool's role.

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?

With no annotations and moderate cursor/wait complexity, the description is complete enough for an agent to use it safely: it covers delivery guarantees, cursor lifecycle, timeout behavior, and coordination expectations. Since an output schema exists, the lack of return-field elaboration is not a gap.

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 description coverage is 0%, so the description must add parameter meaning. It substantially explains after_cursor (replay vs. advancing to next_cursor) and timeout_seconds (excluding cancellation), while surface-level job_ids and limit are mostly left to their self-explanatory names and schema defaults. This is strong compensation, though not exhaustive for limit.

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 description states a specific verb+resource+scope: 'Collect durable terminal results across multiple known jobs after a cursor.' It also clearly distinguishes itself from siblings by explicitly saying 'Do not use this for one job' and naming get_job_status as a different polling approach, so there is strong sibling differentiation.

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?

The description gives explicit when/when-not guidance: submit independent jobs before calling, do not use for a single job, do not poll get_job_status between continuation calls, and never resubmit active jobs after a waiter disconnects. It also names an alternative tool (get_job_status) in the exclusion, making usage boundaries clear.

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

wait_for_jobA

Wait once for a known job_id and consume its durable terminal result.

Returns state, exit code, bounded logs, and declared Artifacts. A client-side timeout or disconnect does not cancel the Job; call this tool again later with the same job_id. Do not use it to start work, do not poll it repeatedly, and use wait_for_completions instead when collecting several independent Jobs.

ParametersJSON Schema
NameRequiredDescriptionDefault
job_idYes
timeout_secondsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.9/5.0
Behavior5/5

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

With no annotations provided, the description carries the full transparency burden, and it excels. It discloses durability semantics (client-side timeout does not cancel the job), describes return content (state, exit code, bounded logs, Artifacts), and implies idempotent re-invocation, providing rich behavioral context beyond what any annotation would offer.

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

Conciseness5/5

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

Four sentences, 67 words, each earning its place: purpose, return values, failure semantics, and usage guidance are all covered without a single wasted word. The description is front-loaded with the core action and follows with critical behavioral details.

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?

The description is complete for an agent to decide when and how to invoke this tool, given the 2-parameter schema and presence of an output schema. It covers return values, timeout behavior, retry semantics, and clearly differentiates from the most likely sibling alternative (wait_for_completions), fully addressing the tool's complexity.

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?

Despite 0% schema description coverage, the description adds meaning to both parameters: job_id is implied to be a known, reusable identifier, and timeout_seconds is contextualized as client-side ('A client-side timeout or disconnect does not cancel the Job'). However, it doesn't specify timeout_seconds value ranges or defaults, and parameter-specific details are inferred rather than explicit, keeping it from a 5.

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 sentence 'Wait once for a known job_id and consume its durable terminal result' provides a specific verb+resource with scope. It distinguishes from the sibling wait_for_completions by emphasizing single-job collection, making the purpose immediately unambiguous.

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?

The description gives explicit when-not guidance ('Do not use it to start work, do not poll it repeatedly'), names a direct alternative ('use wait_for_completions instead when collecting several independent Jobs'), and clarifies retry behavior on timeout ('call this tool again later with the same job_id'). This is textbook-grade usage guidance.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 4 tool updatesv0.8.0
    • Addedrun
    • Changedrun_job2 fields changed
      • addedInput schema / properties / capture_logs
        Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Capture Logs"
+}
      • addedInput schema / properties / resources
        Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Resources"
+}
    • Changedsubmit_job2 fields changed
      • addedInput schema / properties / capture_logs
        Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Capture Logs"
+}
      • addedInput schema / properties / resources
        Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Resources"
+}
    • Addedwait_for_completions
  2. 5 tool updatesv0.3.1
    • Addedcreate_queue
    • Changedlist_jobs1 field changed
      • addedInput schema / properties / queue
        Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Queue"
+}
    • Addedlist_queues
    • Changedrun_job1 field changed
      • addedInput schema / properties / queue
        Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Queue"
+}
    • Changedsubmit_job1 field changed
      • addedInput schema / properties / queue
        Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Queue"
+}
  3. 7 tool updatesv0.3.0
    • First observedcancel_job
    • First observedget_job_logs
    • First observedget_job_status
    • First observedlist_jobs
    • First observedrun_job
    • First observedsubmit_job
    • First observedwait_for_job
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: run for default single command, submit_job for async/fan-out, run_job for MCP Tasks compatibility, wait_for_job for single job waiting, wait_for_completions for multiple jobs, get_job_status for snapshots, get_job_logs for diagnostics, plus cancel/list/queue tools. Descriptions explicitly cross-reference when not to use each, eliminating ambiguity.

Naming Consistency5/5

All 11 tools follow a consistent verb_noun snake_case pattern (run, submit_job, wait_for_job, wait_for_completions, get_job_status, get_job_logs, cancel_job, list_jobs, create_queue, list_queues). No style mixing or vague verbs.

Tool Count5/5

11 tools cover the job lifecycle and queue management without excess. Each tool has a clear role, and the count is appropriate for a job orchestration server—neither too thin nor bloated.

Completeness5/5

The surface covers the full lifecycle: creation (run, submit_job, run_job), waiting and collection (wait_for_job, wait_for_completions), status (get_job_status), logs (get_job_logs), cancel (cancel_job), listing (list_jobs), and queue management (create_queue, list_queues). No obvious gaps for the domain.

Maintenance

ActivityMaintained
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-job-queue

    tommypj
    A
    license
    A
    quality
    C
    maintenance
    Enables MCP clients to submit long-running jobs that are executed safely in isolated child processes with a durable SQLite queue, configurable timeouts, retries with backoff, and backpressure.
    5
    MIT

  • mcp-sidecar

    lsequeiraa
    A
    license
    Not graded
    quality
    C
    maintenance
    A lightweight, cross-platform MCP server for managing background processes. Enables AI coding agents to spawn, monitor, and interact with long-lived processes.
    MIT

  • script-runner

    oyren-ai
    F
    license
    Not graded
    quality
    B
    maintenance
    Remote MCP server that launches user-supplied scripts inside disposable Docker containers, returning task IDs for async tracking and bounded output tails.
    -

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/xpluspro/Awaitless'

If you have feedback or need assistance with the MCP directory API, please join our Discord server