Skip to main content
Glama
Sign In

Runtime Cloud

by com.withruntime
OverviewDiscussionsAdmin

runtime_sandboxes_fork

Idempotent

Start count (1 to 100 on prepaid credit, 1 to 8 without credit) running copies of a sandbox, with its files, memory and processes, on its host. Copies keep its size and CPU, and run on the free usage first, then credit. Returns {sandboxes, snapshot}; on an error, details.startedSandboxIds names copies that started, which are deleted (billed only on a 4xx). fork_unavailable means forks are switched off; do not retry it.

Input Schema

NameRequiredDescriptionDefault
idYes
nameNoYour own handle for the resource. Letters, digits, dot, dash, underscore.
countNoHow many copies: 1 to 100 on prepaid credit, 1 to 4 without credit. One fork takes at most a quarter of its server's free memory.
labelsNoYour own key/value tags, at most 32. Filter lists with label=key:value.
fundingNoAccepted and not read: copies run on what the account's new sandboxes run on, as for a create. On an account without credit, each copy must fit the limits without credit (it has the source's size) and takes one of its running slots.
secretsNoThe egress secrets the copies may use: a narrower list than the source's. Omit it and each copy keeps the source's list (every secret that reaches it, when the source names none). A name the source may not use is refused.
keepSnapshotNoKeep the snapshot the copies started from, to start more later (it is billed as snapshot storage). By default it is deleted when the fork ends, whether every copy started or not, and nothing is billed for it.
idempotencyKeyNoOptional: left out, one is made and returned as idempotencyKey. Send it back only to retry this exact call after a temporary error.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / secrets
      Added value: +{
+  "description": "The egress secrets the copies may use: a narrower list than the source's. Omit it and each copy keeps the source's list (every secret that reaches it, when the source names none). A name the source may not use is refused.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
  2. Changed1 schema field changed
    • changedInput schema / properties / count / description
      Previous value: -"How many copies: 1 to 100 on prepaid credit, 1 to 8 without credit. One fork takes at most a quarter of its server's free memory."New value: +"How many copies: 1 to 100 on prepaid credit, 1 to 4 without credit. One fork takes at most a quarter of its server's free memory."
  3. Added

TDQS

A4/5.0
Behavior5/5

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

Adds substantial context beyond the annotations: copies run on free usage first then credit, copies that started before an error are deleted and billed only on a 4xx, the source snapshot is deleted when the fork ends unless keepSnapshot is set, and details.startedSandboxIds names partial results. That is exactly the operational detail an agent needs and the annotations (non-readonly, idempotent, non-destructive) cannot supply.

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

Conciseness4/5

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

Front-loaded with the core action and its limits, and every sentence carries operational information with no filler. The second half is packed into long run-on clauses, which makes it dense to parse, but nothing is wasted.

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

Completeness5/5

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

With no output schema, the description steps in and documents the return shape ({sandboxes, snapshot}) as well as error semantics (details.startedSandboxIds, fork_unavailable). For an 8-parameter mutation with partial-failure behavior, nothing essential is missing.

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 88%, so the schema already documents count, funding, secrets, keepSnapshot and idempotencyKey well; baseline is 3. The description adds useful framing (copies keep the source's size and CPU, rollover order), but it also states '1 to 8 without credit' while the schema says '1 to 4 without credit' — an inconsistency that could mislead a caller choosing count.

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 uses a specific verb and resource — it starts running copies of a sandbox including files, memory and processes on the host — which clearly separates it from runtime_sandboxes_create (new sandbox) and runtime_snapshots. It never names a sibling explicitly, so the differentiation comes from the nature of the operation rather than from routing guidance.

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?

Retry behavior is stated precisely ('fork_unavailable means forks are switched off; do not retry it'), which is genuinely useful. But there is no guidance on when to fork versus creating a new sandbox or restoring a snapshot, and no prerequisites are given. Usage is implied by the operation itself rather than explained.

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

All Runtime Cloud toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources