Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ns-hpc Create a new sandbox workspace for testing."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
HPC sandboxing via bubblewrap — an MCP server that manages sandbox instances and executes commands inside isolated bwrap containers.
pip install git+https://github.com/li-yq/namespaced-hpc-mcp.git# Run diagnostics
ns-hpc doctor
# Create an instance and run a command
ns-hpc instance create my-inst
ns-hpc bwrap my-inst -- ls -la
# Interactive shell
ns-hpc instance enter my-inst
# Start the MCP server
ns-hpc run # stdio (default)
ns-hpc run --transport streamable-http # HTTP on :8000/mcp
ns-hpc run -t streamable-http --uds /tmp/ns-hpc.sock # Unix socketRelated MCP server: secure-cluster-mcp
┌─────────────────────────────────────────────┐
│ MCP Client (LLM) │
└──────────────┬──────────────────────────────┘
│ stdio / streamable-http / SSE
┌──────────────▼──────────────────────────────┐
│ ns-hpc MCP Server │
│ │
│ ┌──────────────────────┐ ┌─────────────┐ │
│ │ submit_job / poll_job│ │ WebDAV /dav │ │
│ │ (bwrap exec) │ │ (GET/PUT) │ │
│ └──────────┬───────────┘ └──────┬──────┘ │
│ │ │ │
│ ┌──────────▼──────────────────────▼───────┐ │
│ │ bwrap sandbox │ │
│ │ ┌──────────────────────────────────┐ │ │
│ │ │ /workspace (rw, bind-mounted) │ │ │
│ │ │ /output (rw, bind-mounted) │ │ │
│ │ │ /usr /lib /bin /etc (ro) │ │ │
│ │ │ /proc /dev (virtual) │ │ │
│ │ │ /tmp (tmpfs) │ │ │
│ │ └──────────────────────────────────┘ │ │
│ └────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────┐ │
│ │ Instance: ~/.local/share/ns-hpc/ │ │
│ │ instances/{id}/ │ │
│ │ ├── workspace/ (rw host-side bind) │ │
│ │ ├── .ns_hpc_output/ (job outputs) │ │
│ │ ├── .ns_hpc_jobs/ (job state) │ │
│ │ ├── status/ (bwrap fd) │ │
│ │ ├── metadata.json │ │
│ │ └── audit.log (host-side only) │ │
│ └──────────────────────────────────────┘ │
└─────────────────────────────────────────────┘Stateless bwrap: Every command creates a fresh sandbox. No persistent Linux namespaces. The kernel tears down the sandbox when the outer bwrap process exits.
Audit log on host: Written outside the sandbox — the sandbox cannot tamper with its own audit trail.
Shared network: --share-net overrides --unshare-all, so processes
inside bwrap share the host network namespace. This enables WebDAV and
proxied MCP servers to bind ports reachable from the host.
Configuration merges three layers (highest priority last):
Built-in defaults
~/.config/ns-hpc/config.toml (XDG)
NS_HPC_CONFIG env var or --config CLI flag
See config/config.toml for the full reference.
# ~/.config/ns-hpc/config.toml
[namespace]
bwrap_command = [
"bwrap",
"--unshare-all", "--share-net",
"--proc", "/proc", "--dev", "/dev", "--tmpfs", "/tmp",
"--ro-bind", "/usr", "/usr",
"--ro-bind", "/lib", "/lib",
"--ro-bind", "/lib64", "/lib64",
"--ro-bind", "/bin", "/bin",
"--ro-bind", "/sbin", "/sbin",
"--ro-bind", "/etc", "/etc",
]
[jobs]
max_timeout = 3600
[jobs.local]
use_cgroups = true
cgroups_command = [
"systemd-run", "--user", "--scope",
"-p", "CPUQuota=400%",
"-p", "MemoryMax=8G",
"--",
]
[jobs.slurm]
sbatch_command = [
"sbatch",
"--partition", "cpu",
"--cpus-per-task={cpus}",
"--mem={memory}M",
]
[jobs.slurm.limit]
cpus = { default = 1, max = 8 }
memory = { default = 4096, max = 32768 }
# WebDAV file access (default: disabled)
[dav]
enabled = true
[dav.extras.external-data]
path = "/public5/home/t6s001890/data"
ro = true
[proxied_mcps.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/"]
# include = ["read_*", "list_*"]
# exclude = ["*_dangerous"]Command | Description |
| Diagnose system prerequisites |
| Run command in raw bwrap sandbox |
| Start MCP server (stdio, streamable-http, sse, UDS) |
| Remove stale instances |
| Create a new sandbox instance |
| List all instances |
| List archived instances |
| Show instance metadata |
| Update description |
| Interactive bash in sandbox |
| Run command as an async job |
| Check job status |
| List tracked jobs |
| Cancel a running job |
| Archive instance (disables new jobs) |
Tool | Description |
| Create a new sandbox instance |
| List all active instances |
| List all archived instances |
| Update instance metadata (description) |
| Archive an instance, disabling new jobs |
Tool | Description |
| Submit a command as an async job (local or Slurm) |
| Poll a running job, optionally wait for completion |
| List all tracked jobs for an instance |
| Cancel a running job and return final output |
Tool | Description |
| Read a file from the sandbox workspace |
| Write a file to the sandbox workspace |
| List directory contents |
| Additional proxied filesystem tools (search, move, etc.) |
The
filesystem__*tools are proxied from the@modelcontextprotocol/server-filesystemMCP server running inside bwrap. They can be filtered withinclude/excludepatterns in config.
When [dav].enabled = true (and the server runs in HTTP mode), the WebDAV
endpoint at /dav/ provides direct file access from Finder, Windows
Explorer, rclone, or curl.
/dav/instances/{id}/workspace/... (read-write)
/dav/instances/{id}/output/... (read-write)
/dav/{extra_name}/... (config-controlled, defaults to ro)# Mount in Finder: ⌘K → http://127.0.0.1:8000/dav/
# Or with curl:
curl http://127.0.0.1:8000/dav/instances/my-inst/workspace/file.txt
curl -T data.csv http://127.0.0.1:8000/dav/instances/my-inst/workspace/data.csv
curl -X DELETE http://127.0.0.1:8000/dav/instances/my-inst/workspace/old.txtWrites (PUT, DELETE, MKCOL) are audited to the instance audit.log.
Archived instances return 404.
Path traversal (symlinks, ..) is blocked.
Read-only extra mounts reject writes.
pip install git+https://github.com/li-yq/namespaced-hpc-mcp.git
ns-hpc doctor# ~/.config/ns-hpc/config.toml
[namespace]
bwrap_command = [
"bwrap",
"--unshare-all", "--share-net",
"--uid", "1000", "--gid", "1000",
"--ro-bind", "/home/user/.local/share/ns-hpc/rootfs", "/",
"--ro-bind", "/home/user/.local/share/ns-hpc/agent-tools", "/opt/agent-tools",
"--proc", "/proc", "--dev", "/dev",
"--tmpfs", "/run", "--tmpfs", "/tmp",
]
workspace_mount = "/home/agent"
output_mount = "/mnt/output"
shared_output_mount = "/mnt/shared-output"
[jobs.slurm]
sbatch_command = ["sbatch", "--partition", "compute", "--cpus-per-task={cpus}", "--mem={memory}M"]
[jobs.slurm.limit]
cpus = { default = 1, max = 32 }
memory = { default = 4096, max = 131072 }# stdio (for SSH-based MCP clients)
ns-hpc run
# Streamable HTTP (recommended for direct HTTP)
ns-hpc run --transport streamable-http --port 8000
# With WebDAV
ns-hpc run --transport streamable-http --port 8000 # set [dav].enabled=true{
"mcpServers": {
"ns-hpc": {
"command": "ssh",
"args": ["user@hpc-login", "ns-hpc", "run"]
}
}
}Or for HTTP:
{
"mcpServers": {
"ns-hpc": {
"url": "http://hpc-login:8000/mcp"
}
}
}uv sync
uv run pytest # Full test suite
uv run python -m ns_hpc doctor # Diagnostics
uv run python -m ns_hpc run # Start serverTests by tier:
Tier | Command |
Pure unit (no bwrap) |
|
Unit + bwrap |
|
Full Slurm integration |
|
All commands run via bwrap --unshare-all (user, PID, mount, IPC, UTS,
CGROUP namespaces)
System paths are read-only (--ro-bind)
/tmp is a fresh tmpfs
Workspace is the only writable bind mount
Audit log written host-side, never exposed to sandbox
Path traversal blocked in filesystem and WebDAV tools
ns-hpc doctor validates prerequisites
Linux with user namespaces enabled
bwrap (bubblewrap) 0.11+
Python 3.12+
(Optional) Slurm: sbatch, squeue, sacct
(Optional for WebDAV) network access for Finder/rclone/curl clients
MIT
Archive a sandbox instance, disabling new job submissions.
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes | Input for the archive_instance tool. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden; it usefully discloses that new job submissions are disabled. However, it does not disclose whether the action is reversible or what happens to already-submitted/running jobs, which is significant for a lifecycle-changing mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence states the action and its key effect with no filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with a complete schema, selection and invocation are adequately supported. However, with no output schema and no stated reversibility or side effects, the description leaves some context about post-archive behavior undefined.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for the single required instance_id, so the description does not need to restate it. The description adds no parameter-specific nuance beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Archive') with a clear resource ('sandbox instance') and adds the functional consequence (disabling new job submissions). This clearly distinguishes it from sibling tools like create_instance, update_instance, and submit_job.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case through 'disabling new job submissions,' but it does not explicitly state when to prefer archiving over update_instance or how archived instances relate to list_archived_instances. No when-not-to-use guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel a running job and return its final status and output tail.
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It clearly states the destructive action (cancel) and the response shape (final status and output tail). It does not disclose edge-case behavior such as idempotency, irreversibility beyond the act of cancelling, or failure behavior for non-running jobs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes: the action, the target, and the expected result are all present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides the essential cancellation and return contract but omits practical guidance around edge cases and validation—for instance, whether a queued job can be cancelled, what final status will be reported, or how errors are surfaced when cancellation fails. The absence of an output schema makes these details more important.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is reported as 0%, so the description should compensate by explaining parameters like instance_id, job_id, and tail. It only loosely references 'output tail' and gives no guidance on how to supply the required identifiers or how tail limits the returned output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Cancel') with a clear resource ('a running job') and states the expected return payload ('final status and output tail'). This clearly differentiates it from siblings like poll_job, submit_job, and list_jobs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when a running job needs to be cancelled. However, it does not explicitly state exclusions, such as what happens if the job is already finished, or mention alternatives like poll_job for checking status without cancelling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new sandbox instance with a persistent workspace directory.
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes | Input for the create_instance tool. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It does add one meaningful behavioral trait—the workspace directory is persistent—but it does not disclose side effects, failure behavior (e.g., duplicate instance_id), permissions, or whether creation is synchronous or asynchronous.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-front-loaded sentence with no filler. It communicates the core operation and the most important behavioral characteristic efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a relatively simple creation tool with full parameter documentation, the description is mostly adequate: it names the operation and the key persistence trait. However, with no output schema and no annotations, it omits information about return values, lifecycle expectations, and error conditions that would make it more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents both instance_id and description. The description does not add parameter-specific meaning, but the high schema coverage makes this acceptable; the persistence detail provides useful resource context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') and a clear resource ('new sandbox instance'), and adds a defining trait ('persistent workspace directory'). This clearly distinguishes it from sibling tools like update_instance, archive_instance, and list_instances.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the verb and resource: you call this when you need a new sandbox instance. However, the description does not explicitly state when to prefer it over alternatives or mention any exclusions, leaving the agent to infer routing from the tool name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a pre-configured host command or list available commands.
With no argument, returns the list of configured host commands and
their descriptions. With a command key, runs the matching
host command outside any sandbox (directly on the host).
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and it discloses the key behavioral trait: execution happens outside any sandbox, directly on the host. It also states the list-mode behavior; it stops short of describing side effects or return/error details, but 'pre-configured' narrows the expected blast radius.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences front-load the purpose and then give the two invocation modes without wasted words. The sandbox warning is placed at the end but earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, no-output-schema tool, the description combines with the schema to tell an agent exactly how to list and how to run. It does not describe what a run returns or error conditions, but the built-in list mode lets the agent discover available commands, so the definition is functionally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains that `command` is a config key and that omitting it yields the command list, which is the core semantics beyond the bare schema. The phrase 'no argument' is slightly loose given the required `input` object, but the intended meaning is recoverable from the schema and the command-key wording.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first line names a clear action and resource: run a pre-configured host command or list available commands. It is specific enough to separate this tool from instance/job management siblings, though it does not explicitly contrast with any sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit conditional usage: omit the command to list available commands, or supply a command key to execute. It does not name alternative tools or exclusions, but the two-mode guidance is clear enough for selecting this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all archived sandbox instances.
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes | Input for the list_archived_instances tool. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers the safety profile, and the description's 'List' wording is consistent with a read-only operation. The description adds minimal behavioral detail beyond the annotation, such as no mention of pagination or empty-result behavior, but nothing contradicts the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary wording. Every word contributes to understanding the tool's purpose and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation with no inputs, the description is sufficient to convey what the tool returns and for which resource. No output schema exists, but the description's 'List all archived sandbox instances' implies a list result; additional detail like pagination would be nice but is not critical for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a required 'input' wrapper object with no meaningful properties, so there are effectively no operation-specific parameters. The schema coverage is high, and the description does not need to explain parameters; it also does not add any parameter-related meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 specific resource 'archived sandbox instances', which distinguishes it from the sibling list_instances tool. There is no ambiguity about what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for archived instances, providing clear context for when to use it. It does not explicitly mention alternatives like list_instances for active instances, but the name and sibling list make the distinction easy to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all active (non-archived) sandbox instances.
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes | Input for the list_instances tool. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already communicates that this is a safe read operation, so the description doesn't need to repeat that. The description adds useful scoping context about active versus archived instances but does not disclose any additional behavior such as pagination or return format. This is adequate given the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded with the core action and resource, with zero wasted words. It is appropriately concise for a tool this simple.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter, read-only list tool with the readOnlyHint annotation and clear sibling context, the description is complete. It covers the essential scoping (active only) and nothing relevant is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool effectively has no meaningful parameters — the input schema requires an empty wrapper object. Schema coverage is 100% since the only property is described, and the description needs to add little because there is nothing to configure. The placeholder description 'Input for the list_instances tool' is empty but not misleading.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('active (non-archived) sandbox instances'), making the tool's function immediately clear. It also distinguishes itself from the sibling 'list_archived_instances' by explicitly scoping to non-archived instances.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'active (non-archived)' clearly implies this tool is for active instances and not for archived ones, which is a useful selection signal alongside the sibling list. However, it does not explicitly name the alternative tool or state a when-not-to-use condition, leaving a small inference gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tracked jobs for an instance, newest first, with pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals a safe read operation. The description adds useful behavior beyond that: results are ordered newest-first and pagination is supported. It does not cover details like auth, but the annotation lowers the bar and the added behavior is relevant.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler. It states the action, resource, scope, ordering, and pagination without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list operation, the description plus schema covers the required instance_id and optional pagination controls. There is no output schema, so a slightly fuller statement of what job fields are returned would help, but the overall shape is sufficient for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate for parameter meaning. It gestures at 'for an instance' and 'pagination,' but does not explain the instance_id, limit, or offset semantics itself. The nested schema provides some field descriptions, but the tool description adds little value for parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('tracked jobs for an instance'), and adds ordering ('newest first') and pagination. This clearly separates list_jobs from sibling tools like list_instances, submit_job, poll_job, and cancel_job.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The listing scenario is clear from 'List tracked jobs,' and the instance scoping plus pagination make the intended use obvious. However, it does not explicitly state when NOT to use it or name alternatives, such as using submit_job to create a job or poll_job to check a specific job's status.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Poll a running job. Optionally wait for completion.
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'optionally wait for completion' but does not disclose that the tool can block up to 3600 seconds, what timeout=0 means, how detach affects job survival, or any side effects. This is a significant gap for a potentially long-running operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler, and the main action is front-loaded. It is concise in the good sense, though it achieves this by omitting important context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with nested required parameters, no output schema, and no annotations, this description is incomplete. It does not explain return values, blocking semantics, what 'completion' means, error behavior, or where this fits in the job lifecycle alongside submit_job and cancel_job.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description names none of the parameters. While the nested schema provides descriptions for instance_id, job_id, tail, timeout, and detach, the top-level input wrapper has no description and the tool description adds zero meaning about the required contract. Given the stated 0% schema description coverage, the description does not compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Poll a running job.' It clearly identifies the core operation and is distinct from sibling tools like submit_job, cancel_job, or list_jobs. However, it does not explicitly clarify how 'poll' differs from listing jobs or what happens for non-running jobs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use poll_job versus list_jobs or cancel_job. 'Optionally wait for completion' hints at a use case, but there is no explicit context about polling after submission, checking status, or when to avoid using this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit a command as an async (non-blocking) job.
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description communicates the core non-blocking behavior, which is not derivable from the tool name alone. However, with no annotations, it carries the full burden; it does not disclose timeout kill behavior, job lifecycle (poll/cancel), or what a successful submission returns, relying on parameter descriptions in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no filler; 'async (non-blocking)' is front-loaded and adds behavioral precision without bloating the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex (nested input, local/slurm modes, timeouts, detached execution, no output schema), yet the description provides only a one-line overview. An agent cannot tell what the tool returns, how to retrieve results (beyond the detach parameter's mention of poll_job), or when different modes/timeouts apply, so the description is incomplete on its own.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds only a general 'command' framing; all parameter details are left to the schema, which already describes mode, tail, detach, command, timeout, instance_id, and slurm_resources. Given the detailed nested schema, this is adequate but not enhanced by the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action — 'submit a command' — and clarifies that it is asynchronous and non-blocking, which separates it from synchronous execution tools like host_exec. It does not name the sibling explicitly, so differentiation is implicit rather than fully stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Async (non-blocking)' gives a clear reason to choose this tool over synchronous alternatives, and the sibling set (poll_job, cancel_job, host_exec) reinforces that context. There is no explicit 'use X instead when...' sentence, so it does not earn a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update or get an instance's metadata (currently only description).
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes | Input for the update_instance tool. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It indicates that the tool updates metadata and currently only supports description, but it does not disclose side effects, idempotency, permission requirements, what happens when the description is omitted, or what the tool returns. The 'or get' wording also promises a retrieval behavior that is not explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with the primary verb 'Update' at the start and no filler. The 'or get' clause is unnecessary and creates ambiguity, so the sentence is concise but not fully clean in what it communicates.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation-oriented tool with no annotations and no output schema, so the description needs to compensate with more behavioral and usage context. The schema covers parameters well, but the description leaves unresolved questions about read-vs-write behavior, return values, and how this relates to list_instances and archive_instance, making it incomplete for reliable tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents instance_id and description, including the 'omit to leave unchanged' behavior. The description adds only marginal confirmation that description is the sole metadata field, without enriching the parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Update') and resource ('an instance's metadata') and narrows scope to 'currently only description,' which helps distinguish it from broader metadata tools. However, 'Update or get' introduces ambiguity about whether this tool also retrieves metadata, and it does not explicitly contrast itself with the sibling list_instances tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance about when to use update_instance versus create_instance, list_instances, or archive_instance. The phrase 'currently only description' implies a narrow use case, but no alternatives or exclusions are stated, leaving the selection logic to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.0archive_instancecancel_jobcreate_instancehost_execlist_archived_instanceslist_instanceslist_jobspoll_jobsubmit_jobupdate_instanceScored across 10 tools
Each tool targets a distinct resource and action: instance lifecycle, job lifecycle, and host commands are clearly separated. The only potential pairing, list_instances vs list_archived_instances, is explicitly disambiguated by 'archived' in both name and description.
Most tools follow a snake_case verb_noun pattern (create_instance, list_jobs, cancel_job). host_exec deviates slightly by placing the noun before the verb, though it remains readable and consistent in style.
Ten tools is well-scoped for an HPC sandbox service with instance management, asynchronous job execution, and host command access. Each tool covers a meaningful operation without unnecessary duplication.
The tool set covers the essential instance lifecycle (create, list, archive, update) and job lifecycle (submit, poll, list, cancel). Minor gaps exist, such as no direct single-instance getter, no unarchive/destroy operation, and limited job output retrieval outside poll/cancel.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
On-demand GPU nodes for agents: create nodes, run commands, and submit jobs, billed by the minute.
Build Apps and run code in 30 languages — sandboxed, with persistent sessions for agent loops.
Cross-agent artifact workspace with provenance across Claude Code, Codex, Cursor, LangGraph.
