A
licenseNot graded
qualityB
maintenanceProvides agentic MCP tools for the Flux Framework, enabling job submission, management, and resource scheduling for HPC workloads.
1
MIT
srunx
by ksterx
The srunx server provides a comprehensive toolkit for managing SLURM jobs, workflows, and cluster resources via CLI, Python API, web dashboard, and MCP server integration.
Job Management
Submit jobs with full resource control (GPUs, CPUs, memory, time limit, partition, conda/venv, containers, env vars)
List, query status, cancel jobs, and retrieve stdout/stderr logs
Workflow Orchestration
Create, validate, and run multi-step YAML pipelines with DAG dependencies, Jinja2 templating, inter-job data passing, parameter sweeps, retries, partial/dry-run execution
List and inspect workflow YAML files
Cluster Resources & Configuration
Check real-time GPU and node availability across partitions
Retrieve srunx configuration (resource defaults, environment settings)
List and manage SSH connection profiles for remote clusters
Remote Cluster Support
Transparently dispatch all operations to remote SLURM clusters over SSH
Sync files between local and remote via rsync (by mount point or explicit paths)
Additional Features
Web dashboard for visual job and workflow management
Slack notifications on job completion
MCP server integration for AI agents (e.g., Claude Code) to submit jobs and run workflows programmatically
Sends notifications about job state changes and GPU availability to Slack channels.
srunx
A unified CLI, web dashboard, and Python API for SLURM job management.
Stop juggling sbatch scripts, squeue loops, and SSH sessions.
Submit & manage SLURM jobs from CLI, browser, or Python
Orchestrate multi-step workflows with YAML and dependency graphs
Monitor GPU availability and job states with Slack notifications
Local or remote, one CLI — target a local SLURM or any SSH'd cluster with
--profile <name>; no shell-in, no separate "remote" commands — the same verbs you already knowContainer-native — Pyxis, Apptainer, and Singularity support built in
Installation
Requires Python 3.12+ and access to a SLURM cluster (local or via SSH).
uv add srunx # with uv (recommended)
pip install srunx # or with pipThe web dashboard and Slack notifications are included in the base install — no extras required.
For AI agent integration (MCP server), add the mcp extra:
uv add "srunx[mcp]"Related MCP server: mcp-slurm
Quick Start
Submit a job, wait for it, and view the logs — end to end:
# 1. Submit
$ srunx sbatch --job-name training --gpus-per-node 2 --conda ml_env --wrap "python train.py"
✅ Submitted job training (id=847291)
# 2. Follow until completion
$ srunx watch jobs 847291
⠋ 847291 training PENDING → RUNNING → COMPLETED (4m 12s)
# 3. Inspect output
$ srunx tail 847291 -n 20Or describe the whole pipeline once and let srunx drive it:
srunx flow run workflow.yamlSame commands, remote cluster
Every command above accepts --profile <name> and dispatches transparently over SSH — same syntax, same output, same feel as local:
srunx sbatch --profile dgx --job-name training --gpus-per-node 2 --conda ml_env --wrap "python train.py"
srunx squeue --profile dgx
srunx tail --profile dgx 847291 --follow
srunx flow run pipeline.yaml --profile dgxsrunx rsyncs your code under a per-mount lock, runs sbatch in place on the remote, and streams logs back. Your shell never leaves the laptop.
Why srunx?
Instead of stitching together sbatch, squeue, SSH, and a pipeline runner, srunx offers one coherent surface that covers the day-to-day SLURM loop.
Capability | srunx | submitit | simple-slurm | Snakemake |
CLI for submit / status / cancel | ✅ | ❌ | ❌ | ⚠️ partial |
Python API | ✅ | ✅ | ✅ | ✅ |
Web dashboard | ✅ | ❌ | ❌ | ❌ |
Workflow DAG with dependencies | ✅ | ❌ | ❌ | ✅ |
Inter-job value passing (load-time) | ✅ | ❌ | ❌ | ⚠️ via files |
Matrix parameter sweeps | ✅ | ⚠️ manual | ❌ | ⚠️ via wildcards |
GPU availability monitoring | ✅ | ❌ | ❌ | ❌ |
SSH remote submit + file sync | ✅ | ❌ | ❌ | ❌ |
Container support (Pyxis / Apptainer / Singularity) | ✅ | ⚠️ limited | ❌ | ⚠️ via rules |
Slack notifications | ✅ | ❌ | ❌ | ⚠️ plugin |
If you need full-featured scientific workflow tooling, Snakemake / Nextflow are still the right call. srunx targets the sweet spot of "SLURM + a few dependencies + a nice UI" without Airflow-scale infrastructure.
CLI
Every command below runs locally or against a remote cluster over SSH. Add --profile <name> (or set $SRUNX_SSH_PROFILE) and sbatch / squeue / sinfo / sacct / history / gpus / tail / watch / flow run transparently dispatch through the SSH adapter — no shell-in first, no separate "remote" subcommand. srunx ssh is just for managing those profiles (add / list / sync / test); it does not run jobs itself.
Type column: SLURM = mirrors the native SLURM CLI (muscle memory maps directly); srunx = srunx-original command with no direct SLURM counterpart.
Job submission & control (SLURM parity)
Command | Type | Description |
| SLURM | Submit a SLURM job |
| SLURM | Cancel a job |
Status & accounting
Command | Type | Description |
| SLURM | List active jobs (use |
| SLURM | Partition / state / nodelist listing (native-sinfo parity) |
| SLURM | Real SLURM |
| srunx | srunx's own submission history (SQLite-backed) |
| srunx | GPU aggregate summary across partitions |
| srunx | View / stream job logs |
| srunx | Watch for state changes / resource availability |
Workflows & sweeps
Command | Type | Description |
| srunx | Run / validate YAML workflows |
| srunx | Override workflow |
| srunx | Ad-hoc matrix parameter sweep |
Environment & tooling
Command | Type | Description |
| srunx | Manage SSH profiles (add / list / sync / test) — remote execution itself is |
| srunx | Manage configuration |
| srunx | Manage job templates |
| srunx | Launch the web dashboard |
More CLI examples: User Guide · Python-side counterparts: API Reference
Web Dashboard
A dashboard for visual cluster management. Connect to your SLURM cluster over SSH and manage jobs, workflows, and resources from a browser.
srunx ui # -> http://127.0.0.1:8000
srunx ui --port 3000 # custom portJobs
Browse, search, filter, and cancel jobs.
Workflow DAG
Visualize job dependencies. Run workflows directly from the UI.
Resources
GPU and node availability per partition.
Explorer
Browse remote files via SSH mounts. Shell scripts can be submitted as sbatch jobs directly from the file tree.
Full walkthrough: Web UI tutorial · Web UI how-to · Explorer how-to
Workflow Orchestration
Define pipelines in YAML. Jobs run as soon as their dependencies complete — independent branches execute in parallel automatically.
name: experiment
args:
model: "bert-base-uncased"
output_dir: "/outputs/{{ model }}"
jobs:
- name: preprocess
command: ["python", "preprocess.py", "--out", "{{ output_dir }}/data"]
exports:
DATA_PATH: "{{ output_dir }}/data/processed.parquet"
- name: train
command: ["python", "train.py", "--model", "{{ model }}", "--data", "{{ deps.preprocess.DATA_PATH }}"]
depends_on: [preprocess]
gpus_per_node: 2
environment:
container:
image: nvcr.io/nvidia/pytorch:24.01-py3
mounts:
- /data:/data
exports:
MODEL_PATH: "{{ output_dir }}/models/best.pt"
- name: evaluate
command: ["python", "eval.py", "--model", "{{ deps.train.MODEL_PATH }}"]
depends_on: [train]What this shows off:
argswith Jinja2 — reusable, parameterized pipelines ({{ model }},{{ output_dir }})Inter-job exports — parents declare
exports:; children read them via{{ deps.<parent>.<key> }}, fully resolved at workflow load time (no runtime env files)Containers per job — Pyxis / Apptainer / Singularity are first-class (
environment.container)Dependency-driven scheduling —
evaluateblocks ontrain; parallel branches run automatically
Run it:
srunx flow run workflow.yaml # execute
srunx flow run workflow.yaml --dry-run # show plan only
srunx flow run workflow.yaml --from train # resume / partial executionRetry with retry: N and retry_delay: <seconds> per job.
Parameter Sweeps
Run the same workflow across a matrix of hyperparameters without copying YAML. Each cell materializes into its own sbatch submission and is tracked independently.
name: train
args:
lr: 0.01
seed: 1
sweep:
matrix:
lr: [0.001, 0.01, 0.1]
seed: [1, 2, 3]
fail_fast: false
max_parallel: 4
jobs:
- name: train
command: ["python", "train.py", "--lr", "{{ lr }}", "--seed", "{{ seed }}"]
gpus_per_node: 1Run it — or declare the axes ad-hoc on the command line:
srunx flow run train.yaml # YAML-declared sweep
srunx flow run --sweep lr=0.001,0.01 --max-parallel 2 train.yaml # ad-hoc
srunx flow run --sweep lr=0.001,0.01 --max-parallel 2 --dry-run train.yamlSweeps are a first-class concept across CLI, Web UI, and MCP. Web-triggered sweeps route cells through a bounded SlurmSSHExecutorPool against the configured SSH profile, while CLI and MCP runs use the local SLURM client by default. The Web UI surfaces per-cell progress with ETA, filter / sort, and per-cell cancellation.
Full workflow surface (validation, retries, partial execution, sweep recipes): Workflows how-to
Monitoring
# Monitor a job until completion
srunx watch jobs 12345
# Wait for GPUs, then submit
srunx watch resources --min-gpus 4
srunx sbatch --wrap "python train.py" --gpus-per-node 4
# Periodic cluster reports to Slack
srunx watch cluster --schedule 1h --notify $SLACK_WEBHOOKFull monitoring options (continuous watch, thresholds, scheduled reports): Monitoring how-to
Remote SSH
Keep your local editor workflow while the jobs actually run on the cluster. Configure a profile once, and every srunx command accepts --profile <name> with the same syntax as local:
# One-time setup
srunx ssh add --profile dgx --ssh-host dgx1
srunx ssh mount add --profile dgx --mount ml-exp \
--local ~/projects/ml-exp --remote /home/user/ml-exp
# Same verbs you already use — now against the remote cluster
srunx sbatch train.sh --profile dgx # auto-rsyncs the mount + sbatch runs in-place on the remote path
srunx squeue --profile dgx # live queue on the remote cluster
srunx tail 847291 --profile dgx --follow # stream remote logs
srunx flow run pipeline.yaml --profile dgx # full DAG: sync once, hold the per-mount lock, submitSSH config hosts, saved profiles, and ProxyJump support
Environment variable passthrough (
--env KEY=VALUE)File sync via rsync with per-mount locking — auto-detects profile from current directory
Mount model, sync semantics, and in-place execution rules: SSH sync how-to
Slack Notifications
Get notified when jobs finish — set SLACK_WEBHOOK_URL (or configure it in the web dashboard), then append --slack to any srunx flow run command. In Python, pass SlackCallback to the runner (see the Python API section below).
export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."
srunx flow run workflow.yaml --slackMCP Server
srunx ships an MCP server so Claude Code (and other MCP clients) can submit jobs, inspect the queue, and drive workflows over stdio. Install the extra and register the server with your client:
uv add "srunx[mcp]"
srunx-mcp # launch the stdio server directly
# Or register with Claude Code in one shot
claude mcp add --scope user srunx -- uvx --from 'srunx[mcp]' srunx-mcpOnce connected, the agent can call run_workflow with optional sweep and mount parameters:
run_workflow(
yaml_path="train.yaml",
sweep={"matrix": {"lr": [0.001, 0.01]}, "max_parallel": 2},
transport="dgx",
mount="my-project",
)transport="<profile>" selects the remote cluster; the optional mount=<name> translates work_dir / log_dir into that mount's remote paths. mount requires transport — passing mount alone is an error — so the agent can launch mount-aware submissions against a remote cluster without leaving the chat.
Setup + tool-by-tool usage: MCP Setup tutorial · MCP Usage how-to · MCP Tools reference
Python API
The full CLI surface is available as a Python library. Use it inside notebooks, existing Python pipelines, or custom tooling.
Submit and wait:
from srunx import Job, JobResource, JobEnvironment, Slurm
job = Job(
name="training",
command=["python", "train.py"],
resources=JobResource(nodes=1, gpus_per_node=2, time_limit="4:00:00"),
environment=JobEnvironment(conda="ml_env"),
)
client = Slurm()
completed = client.run(job) # submit, poll, and return when terminal
print(completed.status, completed.job_id)Fire-and-track:
submitted = client.submit(job) # returns Job with job_id populated
info = client.retrieve(submitted.job_id) # poll status on demand
client.cancel(submitted.job_id) # if you change your mindRun a YAML workflow programmatically, with callbacks:
from srunx.observability.notifications.legacy_slack import SlackCallback
from srunx.runtime.workflow.runner import WorkflowRunner
runner = WorkflowRunner.from_yaml(
"workflow.yaml",
callbacks=[SlackCallback(webhook_url="...")],
)
runner.run() # blocks until the DAG finishesDocumentation
Full docs (Diátaxis-structured) at ksterx.github.io/srunx:
Tutorials (learn by doing) — Installation · Quickstart · Web UI · MCP setup
How-to guides (solve specific tasks) — User guide · Workflows & sweeps · Monitoring · SSH sync · Web UI · Explorer · MCP usage · Settings · Smoke-test notifications
Reference (look up exact API) — Python API · Web API · MCP tools
Explanation (how it works under the hood) — Architecture · MCP architecture
Development
git clone https://github.com/ksterx/srunx.git
cd srunx
uv sync --dev
# Full pre-commit quality gate
uv run pytest && uv run mypy . && uv run ruff check .Contributions welcome — please open an issue or PR on GitHub.
License
Apache-2.0
Available Tools
15 toolscancel_jobA
Cancel a running or pending SLURM job.
Args:
job_id: SLURM job ID to cancel
transport: Cluster selector — omit / "local" for local SLURM, or an
SSH profile name to cancel on that remote cluster.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | ||
| transport | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A3.7/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full behavioral disclosure. It mentions cancellation but does not describe side effects (e.g., incomplete output), idempotency, required permissions, or behavior if job is already finished.
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 extremely concise with two lines plus an Args section. Every sentence adds value, and there is no redundant or extraneous information.
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 cancellation tool with an output schema (not shown), the description covers basic purpose and parameters. However, it lacks usage guidelines and behavioral transparency, making it moderately complete.
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%, but the description explains both parameters: job_id as 'SLURM job ID' and transport as cluster selector with valid values. This adds meaning beyond the schema, though format validation (e.g., job_id pattern) is missing.
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 verb 'Cancel' and resource 'SLURM job', with scope 'running or pending'. It distinguishes from sibling tools like submit_job, list_jobs, etc., which focus on other actions.
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?
The description provides guidance on the transport parameter (local vs remote SSH), but does not explicitly state when to use this tool versus alternatives, such as when a job is already completed or prerequisites for remote cancellation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_workflowA
Create a SLURM workflow YAML file.
Generates a YAML workflow definition that can be executed with run_workflow.
Each job in the workflow can depend on other jobs, forming a DAG.
Args:
name: Workflow name for identification
jobs: List of job definitions. Each job dict should contain:
- name (required): Job identifier
- command (required for regular jobs): Command as string or list of strings
- script_path (required for shell jobs): Path to shell script
- depends_on: List of job names this job depends on (e.g. ["preprocess"])
Supports dependency types: "afterok:job_a", "after:job_a", "afterany:job_a"
- retry: Number of retry attempts on failure (default 0)
- retry_delay: Seconds between retries (default 60)
- resources: Dict with nodes, gpus_per_node, ntasks_per_node,
cpus_per_task, memory_per_node, time_limit, partition, nodelist
- environment: Dict with conda, venv, env_vars, container
- log_dir: Log directory path
- work_dir: Working directory path
output_path: File path to write the YAML workflow (e.g. "workflow.yaml")
args: Optional template variables for Jinja2 templating in job definitions
default_project: Default SSH project/mount name for file syncing
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | ||
| jobs | Yes | ||
| name | Yes | ||
| output_path | Yes | ||
| default_project | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
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 and discloses key behaviors: creates a YAML file, supports DAG dependencies, retry settings, resource specs, and environment configuration. It doesn't explicitly state file overwriting behavior or required permissions, but covers many aspects.
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 well-structured with a summary line and detailed Args section. It front-loads the purpose and each sentence adds value. However, it could be slightly more concise by grouping related details (e.g., dependency types) without losing clarity.
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?
Given the complexity of the tool (5 parameters including a nested jobs array) and the presence of an output schema, the description covers inputs comprehensively but omits some behavioral details like error handling or file overwrite policy. It is largely sufficient for correct agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/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 thoroughly: it explains the structure of the 'jobs' array, required and optional fields, example syntax for dependencies, and other parameters like 'args' and 'default_project'. This adds substantial meaning beyond the bare 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 description clearly states the tool creates a SLURM workflow YAML file, specifies it generates a DAG workflow definition for use with run_workflow, and distinguishes from sibling tools like run_workflow or validate_workflow by its creation role.
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 explains that the output is executable with run_workflow, implying when to use this tool (before running). However, it lacks explicit guidance on when not to use it or comparisons with alternatives like validate_workflow or direct submission.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_configA
Get the current srunx configuration including resource defaults and environment settings.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A4.1/5.0
Behavior3/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 states 'Get' which implies a read-only operation, but does not explicitly confirm safety, side-effect-freeness, or any other behavioral traits. Minimal transparency beyond the obvious.
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, clear sentence that directly states the tool's purpose. Every word is necessary, and it is front-loaded with the key action and resource.
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 zero parameters, no annotations, and the presence of an output schema (which covers return values), the description is entirely sufficient for a simple getter. It is complete for 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?
The tool has zero parameters, and the input schema coverage is 100%. According to guidelines, 0 parameters yields a baseline score of 4. The description does not need to add parameter details since none 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 uses a specific verb ('Get') and clearly identifies the resource ('srunx configuration') with additional detail about contents ('resource defaults and environment settings'). This distinguishes it from sibling tools like get_resources or get_job_status.
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?
No explicit guidance on when to use this tool versus alternatives. The description implies it is for retrieving configuration, but with sibling tools like get_resources also available, clear differentiation is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_job_logsA
Get stdout/stderr logs for a SLURM job.
Args:
job_id: SLURM job ID
job_name: Optional job name to help locate log files
transport: Cluster selector — omit / "local" for local SLURM, or an
SSH profile name to fetch logs from that remote cluster.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | ||
| job_name | No | ||
| transport | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
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, and the description only states the tool's action without disclosing any behavioral traits such as auth requirements, error handling, or what happens when logs are unavailable. The description does not fill the gap left by missing annotations.
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 core purpose is front-loaded in the first line. The parameter list is clear but could be more concise; it restates some schema information. Overall, it is short and functional.
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?
With an output schema present, the description does not need to detail return values. It covers the main inputs adequately but omits edge cases or behavior for missing logs, which is acceptable for a focused tool. Completeness is moderate.
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 schema has 0% description coverage, but the description adds meaningful context for each parameter: job_id is a SLURM job ID, job_name helps locate files, and transport specifies local vs remote clusters. This compensates well for the schema's lack of detail.
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 begins with a clear verb and resource: 'Get stdout/stderr logs for a SLURM job.' It immediately distinguishes itself from sibling tools like get_job_status or list_jobs by specifying logs retrieval.
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?
The description explains the parameters and their roles but does not explicitly state when to use this tool versus alternatives or any prerequisites. It provides implicit context but lacks formal 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 the status of a specific SLURM job.
Args:
job_id: SLURM job ID to check
transport: Cluster selector — omit / "local" for local SLURM, or an
SSH profile name to query that remote cluster.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | ||
| transport | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A4.3/5.0
Behavior3/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 does not disclose whether the operation is read-only, requires authentication, or has any side effects. Given that there is an output schema (from context), the return format is not required, but behavioral traits are still lacking.
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 with two sentences plus a bullet list. The first sentence clearly states the tool's purpose, and the parameter details are directly relevant. No unnecessary words.
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?
With 2 parameters and an output schema, the description is sufficiently complete. It explains how to specify job_id and transport, and the output schema covers return values. It lacks example usage but is adequate for a simple status-check tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/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 fully explains both parameters: job_id is 'SLURM job ID to check' and transport is described with specific usage options (local vs. SSH profile). This adds significant meaning beyond the raw 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 description clearly states 'Get the status of a specific SLURM job' with a specific verb (get) and resource (status of a specific SLURM job). It distinguishes from siblings like list_jobs or cancel_job by focusing on a single job's status.
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 provides explicit guidance on the transport parameter: 'omit / “local” for local SLURM, or an SSH profile name to query that remote cluster.' This helps the agent decide when to use local vs. remote. However, no direct comparison with sibling tools is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_resourcesA
Get current GPU and node resource availability on the SLURM cluster.
Args:
partition: Specific partition to check (None for all partitions)
transport: Cluster selector — omit / "local" for local SLURM, or an
SSH profile name to query that remote cluster.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| partition | No | ||
| transport | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A3.8/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 burden for behavioral disclosure. The description states 'Get' which implies read-only, but does not explicitly confirm no side effects, required permissions, rate limits, or data volume. The description is minimal on behavior beyond the basic function.
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, with a clear first sentence stating the purpose. The parameter details are included efficiently. However, the Args section is embedded in the description text, which is acceptable but slightly repetitive. No unnecessary words.
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?
Given the tool has only two optional parameters and an output schema exists (so return values are covered), the description is fairly complete. It explains how to specify partition and cluster. However, it does not mention usage patterns like checking before submit, which could enhance context. Still, it's sufficient for an AI agent to understand the tool's inputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/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 effectively adds meaning: partition is explained as a specific partition to check (default all) and transport as a cluster selector with options for local or remote via SSH profile. This goes beyond the raw schema and provides clear actionable guidance.
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 gets current GPU and node resource availability on the SLURM cluster. It uses a specific verb ('Get') and resource ('GPU and node resource availability'), and the sibling tool list includes other operations like job management and workflow creation, so this tool is distinct.
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?
The description provides some guidance via parameters (partition and transport) but does not explicitly state when to use this tool versus alternatives like get_config or list_jobs. It implies usage for checking resource availability before job submission, but lacks direct when-not-to-use or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_workflowB
Read and parse a workflow YAML file, returning its full structure.
Args:
yaml_path: Path to the YAML workflow file
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| yaml_path | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
B3.4/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 only states the tool reads and parses, but does not disclose read-only nature, error behavior (e.g., missing file), or whether it accesses local/remote storage.
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 with a one-line summary followed by an Args section. It is front-loaded and has no wasted words, though additional context could be added without significant bloat.
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?
Given the tool has only one parameter and an output schema exists, the description covers the basic purpose. However, it lacks context on error handling, read-only behavior, and potential side effects, making it only partially complete.
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%. The description adds 'Path to the YAML workflow file' to the parameter 'yaml_path', which adds meaning beyond the schema's type definition, but the parameter is simple and no additional constraints or formats are given.
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 verb ('Read and parse') and resource ('workflow YAML file') and outcome ('returning its full structure'). This distinguishes it from siblings like validate_workflow or create_workflow.
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?
The description implies usage when needing the full structure of a specific workflow file, but provides no exclusions or alternative tools. It does not explicitly say when not to use it vs other workflow tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
inspect_mountA
Report what syncing a mount would change, without changing anything.
Read-only: this never transfers, deletes, or creates anything on the
cluster. Call it freely, including before a sync you are unsure about.
Its main job is answering a question ``sync_files`` cannot: **what is on the
cluster that no longer exists locally?** A sync is additive, so those files
stay — including code deleted in a local refactor, which a job on the
cluster can still import and run. They are listed here as
``mirror_delete_candidate_paths``.
Those candidates mix two kinds of thing:
* **produced by jobs** — checkpoints, logs, outputs. Must NOT be deleted.
* **left over locally** — stale modules, renamed files. Usually should be.
``stale_upload_paths`` is the second group on its own: paths srunx recorded
uploading that are no longer present locally. Job output was never uploaded,
so it does not appear there — which holds even when the mount's exclude list
misses an output directory, the case that otherwise buries a few stale
scripts among dozens of artifacts.
One exception: output pulled into the local tree with ``srunx ssh sync
--pull`` becomes a file the next push manages, so it is recorded like any
other and can be reported as stale once its local copy is removed. Excluding
the output directories on the mount avoids that, and is worth doing anyway.
**Check ``stale_uploads_known`` first.** When it is false the record could
not answer (nothing uploaded with tracking yet, an unreadable record, or a
changed exclude filter), and ``stale_uploads: 0`` means "could not tell",
not "nothing is stale" — ``stale_uploads_unknown_reason`` says which. Fall
back to reading the full candidate list yourself in that case.
Args:
transport: SSH profile name to inspect. Required — there is no local
inspection, and (unlike the CLI) no implicit current-profile
fallback. Call ``list_ssh_profiles`` for the available profiles and
the mounts each defines.
mount: Mount name from that SSH profile.
max_paths: Cap on how many paths to list. Counts stay exact regardless;
past the cap the list is omitted rather than shortened, and
``mirror_delete_candidate_paths_omitted`` says so.
Returns:
``files_would_transfer``, ``mirror_delete_candidates`` (a count),
``mirror_delete_candidate_paths``, whether that list was omitted,
``effective_exclude_patterns``, and the stale-upload fields described
above (``stale_uploads_known`` / ``stale_uploads`` /
``stale_upload_paths`` / ``stale_uploads_unknown_reason``).
The exclude list matters for reading the result: excluded paths are
invisible to this inspection *and* protected from a mirror's deletions,
so something absent from the candidates may simply be excluded rather
than in sync.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mount | Yes | ||
| max_paths | No | ||
| transport | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
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 burden, and it excels: it declares read-only behavior, explains the max_paths cap behavior (counts stay exact, list omitted), clarifies the effect of exclude patterns ('invisible to this inspection and protected from a mirror's deletions'), and details the stale-upload semantics including the failure case (stale_uploads_unknown_reason).
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 lengthy but well-structured: bold key concepts, clear headings for args and returns, and each paragraph addresses a distinct concern (read-only, candidates, stale uploads, exclusion). The core purpose is front-loaded. While it is verbose, no sentences are wasted; it earns its length for a complex inspection tool.
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?
Even though an output schema exists (per context signal), the description explicitly lists every return field and their meaning, explains edge cases (stale_uploads_known false, max_paths omission, exclusion invisibility), and provides fallback guidance. For a tool with this complexity, the description leaves nothing an agent needs to know to call and interpret it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/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 fully explain parameters. It does: transport is described as an SSH profile name with no implicit fallback, mount is tied to that profile, and max_paths is given with its cap behavior (counts exact, list omitted if exceeded). This adds meaning far beyond the simple schema definitions.
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 precise verb+resource ('Report what syncing a mount would change') and immediately distinguishes itself from sync_files by stating it cannot answer what is on the cluster that no longer exists locally. This makes the tool's unique purpose unmistakable and differentiates it from siblings.
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 when to call ('before a sync you are unsure about'), how to call safely ('Call it freely'), and provides a decision rule: check stale_uploads_known first, and fall back to reading the full candidate list if it is false. It also names sibling tools like list_ssh_profiles for parameter guidance, covering both when and how to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_jobsB
List SLURM jobs in the queue (all users, like squeue).
Args:
transport: Cluster selector — omit / "local" for local SLURM, or an
SSH profile name to query that remote cluster.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| transport | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
B3.3/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It only mentions listing all users and the transport parameter, but omits whether the operation is read-only, idempotent, or if there are any side effects or rate limits.
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 very concise, with two sentences that efficiently convey purpose and the key parameter. It is front-loaded and avoids unnecessary words.
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, one-parameter tool with an output schema, the description covers the main points. However, it lacks explicit statements about safety, idempotency, or whether the tool can be invoked without side effects, which is important for an AI agent.
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?
With 0% schema description coverage, the description adds significant value for the only parameter, explaining its role as a cluster selector with explicit values ('local' or SSH profile). This compensates for the lack of schema-level documentation.
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 clearly states the tool lists SLURM jobs in the queue, using 'like squeue' to reinforce behavior. It distinguishes from siblings like get_job_status by noting 'all users', but could explicitly differentiate further.
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?
The description provides guidance on the transport parameter (local vs remote), but does not indicate when to use this tool over alternatives like cancel_job or get_job_status, nor 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.
list_ssh_profilesA
List all configured SSH connection profiles for remote SLURM clusters.
Shows profile names, hostnames, and configured mount points.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A4.3/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. It discloses that the tool lists profiles and shows specific fields, but does not mention side effects, authentication needs, or error scenarios. For a simple read operation, this is adequate but minimal.
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?
Two sentences, 20 words, front-loaded with the main action. Every sentence adds value without repetition.
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 zero parameters and an output schema (not shown but exists), the description is complete: it names the returned fields and the tool's scope. No further details are necessary.
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 no parameters, so the baseline is 4. The description adds no parameter info, which is acceptable as none is needed.
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 verb 'list' and the resource 'SSH connection profiles for remote SLURM clusters', distinguishing it from sibling tools that deal with jobs, workflows, or configuration.
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 implies use for viewing profiles, and no sibling tool performs this function, so explicit alternatives are unnecessary. However, it lacks explicit when-to-use or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_workflowsA
List workflow YAML files in a directory.
Scans the directory for YAML files that contain a valid srunx workflow
structure (must have 'name' and 'jobs' keys).
Args:
directory: Directory to search for workflow files (default: current directory)
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| directory | No | . |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A3.8/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context by stating it scans for YAML files with 'name' and 'jobs' keys, which implies filtering. However, it does not explicitly state that the operation is read-only or mention any side effects. Since no annotations are provided, the description bears the full burden, and this is a moderate effort but lacks explicit safety indicators.
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 with three sentences: the first states the purpose, the second explains the filtering, and the third clarifies the parameter. Every sentence adds value, and there is no redundancy or fluff.
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?
Given that an output schema exists, the description does not need to detail return values. It covers the main input and behavior. However, it is silent on whether the search is recursive or handles symlinks. For a simple list tool, this is adequate but could be more precise.
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 input schema has 0% description coverage, so the description must compensate. It adds meaning by explaining that the 'directory' parameter is the 'Directory to search for workflow files (default: current directory),' which goes beyond the schema's type and default. This provides the agent with the purpose of the parameter effectively.
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 'List workflow YAML files in a directory,' specifying the verb ('list'), resource ('workflow YAML files'), and scope ('in a directory'). This distinguishes it from sibling tools like create_workflow, run_workflow, or validate_workflow, which have 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 guidance on when to use this tool versus alternatives. It does not mention any prerequisites, exclusions, or context where other tools might be more appropriate. The agent receives no help in deciding between listing workflows and, say, viewing a specific workflow or submitting a job.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
run_workflowA
Execute a SLURM workflow from a YAML file.
Jobs are executed in dependency order - independent jobs run in parallel,
dependent jobs wait for their prerequisites to complete.
Args:
yaml_path: Path to the YAML workflow file
from_job: Start execution from this job (skip earlier jobs)
to_job: Stop execution at this job (skip later jobs)
single_job: Execute only this specific job, ignoring dependencies
dry_run: If true, show what would be executed without actually running
args: Optional mapping merged over the YAML ``args`` section before
Jinja rendering. ``python:`` prefix values are rejected.
sweep: Optional sweep spec: ``{"matrix": {...}, "fail_fast": bool,
"max_parallel": int}``. When present, the request goes through
:class:`SweepOrchestrator` and the response contains
``sweep_run_id``.
transport: Cluster selector — omit / "local" for local SLURM, or an
SSH profile name to run against that remote cluster. Orthogonal to
``mount``: ``transport`` picks *which* cluster, ``mount`` picks the
path-translation root within it.
mount: Optional mount name within the SSH profile, enabling mount-aware
path translation for ``work_dir`` / ``log_dir``. Requires an SSH
``transport``; passing ``mount`` with a local transport is an error.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | ||
| mount | No | ||
| sweep | No | ||
| to_job | No | ||
| dry_run | No | ||
| from_job | No | ||
| transport | No | ||
| yaml_path | Yes | ||
| single_job | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A4.5/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description carries full burden. It discloses dependency-based execution order, parallel independent jobs, rejection of python: prefix in args, and sweep orchestration behavior. Missing details on auth or rate limits, but covers key behavioral traits.
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?
Efficiently structured with a one-sentence summary followed by parameter explanations. Every sentence adds value; no redundant text despite covering 9 parameters.
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?
With output schema present, return values are likely covered. Description explains sweep response (sweep_run_id). For normal execution, it does not detail return, but schema fills gap. Overall complete for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It does so thoroughly, explaining each parameter's purpose, constraints (e.g., mount requires SSH transport), and behavior (e.g., dry_run shows without executing).
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 begins with a clear verb and resource: 'Execute a SLURM workflow from a YAML file.' It distinguishes from siblings like validate_workflow, create_workflow, and submit_job by focusing on execution with dependency ordering.
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?
It explains when to use parameters like from_job, to_job, single_job, dry_run, transport, mount, and sweep, and describes dependency ordering. However, it does not explicitly state when NOT to use this tool vs. alternatives like validate_workflow or submit_job.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
submit_jobB
Submit a SLURM job.
Args:
command: Shell command to execute (e.g. "python train.py --epochs 100")
name: Job name for identification in SLURM queue
nodes: Number of compute nodes to allocate
gpus_per_node: Number of GPUs per node (0 for CPU-only)
ntasks_per_node: Number of tasks per node
cpus_per_task: Number of CPUs per task
memory_per_node: Memory per node (e.g. "32GB", "64G")
time_limit: Wall time limit (e.g. "4:00:00", "1-00:00:00")
partition: SLURM partition name (e.g. "gpu", "cpu")
nodelist: Specific nodes to use (e.g. "node001,node002")
conda: Conda environment name to activate before running
venv: Path to Python virtual environment to activate
env_vars: Additional environment variables as key-value pairs
log_dir: Directory for stdout/stderr log files
work_dir: Working directory for the job (defaults to cwd)
transport: Cluster selector — omit / "local" for local SLURM, or an
SSH profile name to submit to that remote cluster.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | job | |
| venv | No | ||
| conda | No | ||
| nodes | No | ||
| command | Yes | ||
| log_dir | No | logs | |
| env_vars | No | ||
| nodelist | No | ||
| work_dir | No | ||
| partition | No | ||
| transport | No | ||
| time_limit | No | ||
| cpus_per_task | No | ||
| gpus_per_node | No | ||
| memory_per_node | No | ||
| ntasks_per_node | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
B3.3/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It omits key traits like if submission is synchronous/asynchronous, job lifecycle effects, error handling, or if it returns a job ID. The description focuses on parameters, not behavioral side effects.
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 a readable parameter list preceded by a clear summary. It is not overly verbose, but is somewhat lengthy due to 16 parameters. Front-loaded with the purpose, which is good.
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?
With an output schema (context signals), return values are covered. The description covers all 16 parameters with brief explanations, addresses local vs remote submission via 'transport', and includes defaults. Missing some context like default for work_dir, but overall sufficient for a complex tool.
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 coverage is 0%, so description must explain parameters. It adds one-line explanations (e.g., 'Shell command to execute', 'Job name for identification'), which is helpful but minimal. Some parameters like 'nodelist' just repeat the parameter name. Overall, adds some value beyond schema types.
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 starts with 'Submit a SLURM job', a specific verb+resource, and the parameter list makes it distinct from sibling tools like cancel_job or get_job_logs.
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?
No guidance on when to use this tool versus siblings. It does not mention whether to use submit_job for batch jobs, interactive jobs, or alternatives like run_workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
sync_filesA
Sync a configured mount from this machine to a remote SLURM cluster.
Copies new and changed files only. Files that exist on the cluster but not
locally are left untouched unless ``delete=True``.
That means a file deleted locally stays on the cluster, where a job can
still pick it up. This tool does not report those — call ``inspect_mount``
to see them. It is read-only, so it is safe to call before or after a sync;
reach for it rather than setting ``delete=True`` to find out what is stale.
Args:
transport: SSH profile name to sync against. Required and must name
an SSH profile — there is no local-to-local sync, and (unlike
the CLI) no implicit current-profile fallback. ``"local"`` is
rejected. Call ``list_ssh_profiles`` to see profiles and the
mounts each one defines.
mount: Mount name from that SSH profile. Only pre-registered mounts
can be synced; arbitrary paths are not accepted.
dry_run: Preview only. Reports exactly what would be transferred and
deleted without touching the cluster. Prefer this first whenever
you are unsure, and always before a ``delete=True`` run.
delete: Mirror the mount — also DELETE cluster files that no longer
exist locally. **This destroys remote-only data** such as
training checkpoints, job logs, and outputs written by jobs on
the cluster, which by definition do not exist locally. Leave it
off unless the user explicitly asked for a mirror, and preview
with ``dry_run=True`` before running it.
max_delete: Refuse the mirror, without changing anything, if it would
delete more than this many **entries**. Entries are files *and*
directories, matching rsync's own ``--max-delete`` unit: removing
a directory holding two files counts as three entries (both files
plus the directory), so set this above the file count you have in
mind. Guards against mirroring from a wrong or half-populated
local directory. Must be >= 1; to sync without deleting, leave
``delete`` off. Only applies to a real ``delete=True`` run — a
``dry_run`` preview is never capped, so it can show the whole list.
Returns:
On success: ``files_transferred``, ``entries_deleted``, and the
``deleted_paths`` list. Past a very large number of deletions the list
is omitted and ``deleted_paths_omitted`` is set — the count stays
exact, and no list is ever silently shortened.
The two counts use different units on purpose, because that is what
rsync reports: ``entries_deleted`` includes removed directories, while
``files_transferred`` counts only regular files whose data actually
crossed the wire — matching rsync's own "regular files transferred"
statistic. Directory creations, symlinks, devices, hard links and
attribute-only touch-ups move no data and are excluded, so a sync can
legitimately change the remote while reporting zero transfers.
Counts are reliable; path *strings* have one documented limit. rsync
separates its flag block from the filename with whitespace whose width
varies by version, so a filename that itself begins with spaces cannot
be told apart from that separator, and those leading spaces are lost
from the reported string. Such a deletion is still counted, so the
cap and the refusal logic are unaffected.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mount | Yes | ||
| delete | No | ||
| dry_run | No | ||
| transport | Yes | ||
| max_delete | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosure and exceeds it. It explains that files deleted locally persist on the cluster, that the tool does not report them, that delete destroys remote-only data, that dry_run does not touch the cluster, that max_delete counts both files and directories, and even documents the whitespace limitation on reported filenames. This is exceptionally transparent.
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 long but every sentence earns its place. It is front-loaded with a summary sentence, then structured into Args and Returns sections. The use of bold for delete and clear unit explanations makes it scannable. The length is justified by the tool's complexity and safety implications. It could not be meaningfully shortened without losing crucial detail.
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 tool with five parameters, a destructive delete mode, and nuanced return counts, the description covers all necessary context: parameter choices, return value meanings, count unit differences, and edge-case behavior. Even with an output schema, this description enriches the semantics and leaves no obvious gap for an agent to misuse the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description fully compensates. Each of the five parameters is explained with real semantics: transport must be an SSH profile (no local-to-local, 'local' rejected), mount must be pre-registered, dry_run is a no-touch preview, delete is destructive and mirrors, and max_delete counts entries with a clear unit definition. This adds meaning far beyond the plain 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 description opens with a specific verb and resource: 'Sync a configured mount from this machine to a remote SLURM cluster.' It explicitly notes it copies new and changed files only, distinguishing it from inspect_mount (which lists stale files) and from list_ssh_profiles (which discovers mounts). This clearly separates it from sibling tools.
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 usage guidance: call inspect_mount to identify stale files rather than enabling delete=True, call list_ssh_profiles to see profiles and their mounts, prefer dry_run first when unsure, and always before delete=True. It also warns to leave delete off unless the user explicitly asks for a mirror. This is strong when-to-use/when-not-to guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
validate_workflowA
Validate a workflow YAML file for correctness.
Checks for valid YAML syntax, correct job structure, dependency resolution,
and circular dependency detection.
Args:
yaml_path: Path to the YAML workflow file to validate
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| yaml_path | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A4.1/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the validation checks performed, but does not describe output format or side effects. Output schema exists but description could add context on return values.
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?
Description is concise (two paragraphs, 4 lines) with front-loaded purpose. No redundant information.
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?
Tool is simple with one parameter and output schema exists, but description does not explain what the output looks like (e.g., success/failure, error details). This gap reduces completeness despite schema coverage.
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 description must compensate. It provides a clear parameter description: 'Path to the YAML workflow file to validate'. This adds meaningful context beyond the schema's type-only definition.
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?
Description clearly states the tool validates a workflow YAML file for correctness, listing specific checks (YAML syntax, job structure, dependency resolution, circular dependency detection). This distinguishes it from siblings like run_workflow or create_workflow.
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 (before running a workflow) but no explicit guidance on when to use vs alternatives like run_workflow or create_workflow. No exclusions or prerequisites mentioned.
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.
2 tool updates
v4.0.1- Added
inspect_mount - Changed
sync_files8 fields changed- added
Input schema / properties / deleteAdded value: +{ + "default": false, + "title": "Delete", + "type": "boolean" +} - removed
Input schema / properties / local_pathRemoved value: -{ - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "default": null, - "title": "Local Path" -} - added
Input schema / properties / max_deleteAdded value: +{ + "default": 100, + "title": "Max Delete", + "type": "integer" +} - removed
Input schema / properties / mount / anyOfRemoved value: -[ - { - "type": "string" - }, - { - "type": "null" - } -] - removed
Input schema / properties / mount / defaultRemoved value: -null - added
Input schema / properties / mount / typeAdded value: +"string" - removed
Input schema / properties / remote_pathRemoved value: -{ - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "default": null, - "title": "Remote Path" -} - changed
Input schema / requiredPrevious value: -[ - "transport" -]New value: +[ + "transport", + "mount" +]
4 tool updates
v3.0.3- Added
cancel_job - Added
get_workflow - Added
run_workflow - Added
validate_workflow
4 tool updates
v3.0.2- Removed
cancel_job - Removed
get_workflow - Removed
run_workflow - Removed
validate_workflow
8 tool updates
v0.1.1- Changed
cancel_job2 fields changed- added
Input schema / properties / transportAdded value: +{ + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Transport" +} - removed
Input schema / properties / use_sshRemoved value: -{ - "default": false, - "title": "Use Ssh", - "type": "boolean" -}
- Changed
get_job_logs2 fields changed- added
Input schema / properties / transportAdded value: +{ + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Transport" +} - removed
Input schema / properties / use_sshRemoved value: -{ - "default": false, - "title": "Use Ssh", - "type": "boolean" -}
- Changed
get_job_status2 fields changed- added
Input schema / properties / transportAdded value: +{ + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Transport" +} - removed
Input schema / properties / use_sshRemoved value: -{ - "default": false, - "title": "Use Ssh", - "type": "boolean" -}
- Changed
get_resources2 fields changed- added
Input schema / properties / transportAdded value: +{ + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Transport" +} - removed
Input schema / properties / use_sshRemoved value: -{ - "default": false, - "title": "Use Ssh", - "type": "boolean" -}
- Changed
list_jobs2 fields changed- added
Input schema / properties / transportAdded value: +{ + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Transport" +} - removed
Input schema / properties / use_sshRemoved value: -{ - "default": false, - "title": "Use Ssh", - "type": "boolean" -}
- Changed
run_workflow1 field changed- added
Input schema / properties / transportAdded value: +{ + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Transport" +}
- Changed
submit_job2 fields changed- added
Input schema / properties / transportAdded value: +{ + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Transport" +} - removed
Input schema / properties / use_sshRemoved value: -{ - "default": false, - "title": "Use Ssh", - "type": "boolean" -}
- Changed
sync_files5 fields changed- added
Input schema / properties / mountAdded value: +{ + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Mount" +} - removed
Input schema / properties / mount_nameRemoved value: -{ - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "default": null, - "title": "Mount Name" -} - removed
Input schema / properties / profile_nameRemoved value: -{ - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "default": null, - "title": "Profile Name" -} - added
Input schema / properties / transportAdded value: +{ + "title": "Transport", + "type": "string" +} - added
Input schema / requiredAdded value: +[ + "transport" +]
14 tool updates
v0.1.0- First observed
cancel_job - First observed
create_workflow - First observed
get_config - First observed
get_job_logs - First observed
get_job_status - First observed
get_resources - First observed
get_workflow - First observed
list_jobs - First observed
list_ssh_profiles - First observed
list_workflows - First observed
run_workflow - First observed
submit_job - First observed
sync_files - First observed
validate_workflow
TDQS
A4/5.0
Scored across 15 tools
Disambiguation5/5
Each tool targets a distinct resource and action: job submission, status, logs, and cancellation are cleanly separated, as are workflow create/validate/run/list/get. Even the closely related inspect_mount and sync_files are clearly differentiated as read-only inspection versus actual transfer.
Naming Consistency5/5
All tool names follow a consistent verb_noun snake_case pattern, such as list_jobs, get_job_status, submit_job, cancel_job, create_workflow, run_workflow, and sync_files. The naming conventions are predictable and make the tool surface easy to navigate.
Tool Count5/5
Fifteen tools is at the upper edge of the ideal range, but each tool earns its place across three coherent subdomains: SSH/resource inspection, SLURM job management, and workflow orchestration. There are no redundant or filler tools.
Completeness4/5
The core lifecycle is well covered: jobs can be submitted, listed, monitored, logged, and canceled; workflows can be created, validated, run, listed, and read; file sync includes both preview and mirror modes. Minor gaps exist, such as no workflow update/delete tool and no SSH profile management, but agents can work around these via file/config operations.
Maintenance
ActivityActive
ResponsivenessResponsive
Related MCP Connectors
On-demand GPU nodes for agents: create nodes, run commands, and submit jobs, billed by the minute.
Dispatch and track Alchemist Cloud tickets, watch deploys, read logs, and query your project DB.
Manage Sprites: sandboxed compute environments with exec, services, and checkpoints.
GPU cloud platform — create, manage, and monitor instances, snapshots, SSH keys, and billing.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage SLURM HPC clusters via SSH. Supports job submission, resource monitoring, queue management, and file operations.9 npm4-
- FlicenseNot gradedqualityAmaintenanceAn MCP server for monitoring and managing multi-cluster Slurm GPU jobs, enabling AI agents to execute commands, check allocations, and explore logs across HPC clusters.1-
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to manage SLURM cluster jobs with safety guardrails, including file transfer, job submission, log reading, and remote command execution.1MIT