A persistent Linux computer for your AI: what it installs and writes survives the session.
Scored across 18 tools
Most tools target a distinct resource+action (files, commands, packages, ports, checkpoints, environments) and are easy to tell apart. The one soft spot is the trio list_environments / get_environment_info / get_active_environment, which all return environment metadata and could be momentarily confused, though the descriptions do draw the line between 'which computer is active' and 'status/resources'.
Every tool follows a clean verb_noun snake_case pattern (create_checkpoint, list_environments, expose_port, install_package, run_command). Affixed forms like expose_port/unexpose_port/list_exposed_ports stay predictably related, and there is no mixing of conventions.
18 tools is on the heavier side but each maps to a real operation across six coherent domains (environments, checkpoints, files, commands, packages, ports). Nothing looks redundant, though it sits just above the ideal 3-15 range.
Checkpoints are full CRUD and files/commands/packages/ports are well covered, so core workflows have no dead ends. The notable gap is the absence of delete_environment (and file delete/rename), which matters since create_environment explicitly fails when you're at your machine limit.
Save a checkpoint of this computer — the state of the filesystem and everything installed, kept under a name so you can put the machine back to exactly this state later. The computer keeps running; nothing is interrupted.
Take one before anything you would struggle to undo: a database migration, a dependency or framework upgrade, a large refactor, a destructive script, or handing the machine to a different task. This is the persistent-computer version of "let me start fresh" — you cannot start fresh here, but you can come back.
Only the first checkpoint copies the whole computer; each one after it saves what changed since the last, so taking one before every risky step is cheap and is the intended habit. There is still a limit on how many are kept, so name them for what they are ("before the schema change") rather than by number.
The state is taken from the live filesystem, so finish or stop anything mid-write first — a database being written to, a build in progress — or that file is captured half-written.
| Name | Required | Description | Default |
|---|---|---|---|
| label | No | What state this is — "before the auth refactor". Shown to the owner. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses incremental storage (only the first copies the whole computer), a retention limit, that the machine keeps running uninterrupted, and that the state is read from the live filesystem so mid-write operations must be stopped first.
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?
Four short paragraphs, front-loaded with the core definition before the when-to-use advice and caveats. Every paragraph is functional, though the 'let me start fresh' color is slightly decorative relative to the operational content.
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 mutating tool with no annotations, no output schema, and one well-documented parameter, the description is nearly complete — it covers intent, timing, incremental behavior, retention, and write-in-flight risk. It does not describe the return value, a minor gap given no output schema exists.
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 coverage is 100% and the schema documents the single 'label' parameter, so the baseline is 3. The description adds meaning beyond it by prescribing a naming convention (name for what it is, e.g. 'before the schema change', not by number), which is genuinely useful guidance not present in 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?
Specific verb (save) plus resource (checkpoint) with an immediate definition of what a checkpoint captures — filesystem state and installed software, named and restorable. It is clearly distinguishable from restore_checkpoint and list_checkpoints by the direction of the operation.
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?
Explicitly enumerates when to take one (database migration, dependency/framework upgrade, large refactor, destructive script, handing off the machine) and frames the intended habit of checkpointing before every risky step. The alternative action, restoring, is implied by 'you can come back'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set up a new persistent computer — a fresh Linux machine that will keep whatever you install on it. Fails if the account has no active subscription, or is already at the number of computers it pays for — in either case the owner must act on the idle9 dashboard; do not retry. These machines are for development work: coin mining, denial-of-service traffic and internet-wide scanning are detected and get the machine suspended.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Human-readable name, e.g. "my-api" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses persistence, the exact failure conditions, that retrying is futile, and that abusive workloads (mining, DoS, scanning) cause suspension. The main omission is what the call returns — no output schema exists, and a creation tool's identifier is what every sibling (run_command, install_package, expose_port) needs.
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 sentences, front-loaded with the core action and persistence guarantee, then failure handling, then the acceptable-use constraint. Every sentence changes agent behavior — no filler or restatement of the title.
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 provisioning tool with no annotations or output schema, the description covers purpose, failure modes, retry policy, and usage restrictions. The remaining gap is the return value / resulting machine identity, which an agent would need before chaining into run_command or expose_port.
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?
Only one parameter ('name') and schema description coverage is 100%, including an example, so the schema already does the work. The description adds no naming conventions, length limits, or uniqueness constraints beyond it. Baseline 3 applies when structured data fully covers the parameters.
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?
States a specific verb and resource ('Set up a new persistent computer — a fresh Linux machine') and immediately clarifies persistence ('keep whatever you install on it'), which is exactly what separates it from ephemeral siblings like create_checkpoint or sleep_environment. An agent can tell what it produces without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context for use (provisioning a durable dev machine) and unusually actionable failure guidance: it names the two failure causes (no active subscription, at paid-machine limit) and tells the agent not to retry and to route the owner to the dashboard. It does not, however, mention alternatives such as get_active_environment/list_environments for checking whether a machine already exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a saved checkpoint permanently, freeing its share of this computer's checkpoint storage. The computer itself is untouched. Use this to make room when the limit is reached.
Later checkpoints hold only the changes since the ones before them, so deleting an early one is refused while newer ones are built on it — the refusal names them. Prefer deleting the newest states you are confident you will never go back to. Only pass cascade after telling the owner exactly which of their save points it would take: deleting several of somebody's checkpoints to make room for one of yours is the failure this feature exists to insure against.
| Name | Required | Description | Default |
|---|---|---|---|
| cascade | No | Also delete every later checkpoint built on this one. Ask the owner first. | |
| checkpoint | Yes | Checkpoint id, from list_checkpoints |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses permanence, that storage is freed, that the computer is unaffected, that deleting an early checkpoint is refused while newer ones depend on it, and that the refusal names the dependents. It also warns that cascade destroys multiple of someone else's save points. This is unusually rich behavioral disclosure for a destructive tool.
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 core action, storage effect, and the corrective non-effect are front-loaded in the first sentence, with the caveats following. The prose is a little dense in the third sentence, but every clause carries operational weight and none is filler.
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 two-parameter destructive tool with no annotations and no output schema, the description covers safety, dependency semantics, refusal behavior, and the dangerous cascade case. Nothing material an agent needs to call this correctly 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?
Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: it explains that cascade removes 'every later checkpoint built on this one' and requires the owner's consent first, going past the schema's terse 'Ask the owner first.' The dependency relationship between checkpoints is semantic context the schema does not convey.
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?
States a specific verb and resource ('Delete a saved checkpoint permanently') with the scope clarified ('the computer itself is untouched'). This clearly separates it from siblings like restore_checkpoint and list_checkpoints without needing to open a schema.
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?
Explicitly says when to use it ('make room when the limit is reached') and which checkpoint to prefer ('the newest states you are confident you will never go back to'). It also gives a conditional guardrail for cascade and explains the refusal case for early checkpoints, so the agent knows both when to act and when not to.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Expose a TCP port from your computer to the internet, and return the public address, so the owner can look at whatever you are running. The address is remembered: it survives the computer sleeping and comes back with it, so there is no need to re-expose a port you have already published. Give it a label when you know what it is — the owner sees these on their dashboard and a bare port number tells them nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| port | Yes | ||
| label | No | What is on this port — "web app", "API docs". Shown to the owner. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the whole burden and does well: it discloses the return value (public address), the persistence/survival-across-sleep behavior, and where the label surfaces (owner dashboard). It omits error/failure behavior (e.g. port already exposed or not listening) and any permission or rate-limit context.
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?
Front-loaded with the action and its return value, then persistence, then the label guidance — a sensible priority order. Three sentences, each carrying a distinct fact, though the label sentence is slightly chatty.
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 mutation tool with no annotations and no output schema, the description covers the essentials an agent needs: what it does, what it returns, and that the exposure is durable. Missing failure modes and permission requirements keep it short of full completeness.
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 coverage is only 50% and the description compensates: it clarifies that the port is a local TCP port being published (schema only gives an integer range) and explains why a label matters to the owner, adding intent beyond the schema's "shown to the owner." It does not state that label is optional or that port is required.
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?
States a specific verb and resource with its effect: "Expose a TCP port from your computer to the internet, and return the public address." The agent knows exactly what the call does and what it produces, and it is clearly distinguishable from unexpose_port and list_exposed_ports.
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?
Provides a clear when-not condition: because the mapping persists across sleep, "there is no need to re-expose a port you have already published," which steers the agent toward checking list_exposed_ports first. It does not, however, explicitly name the sibling tools or state the inverse case for unexpose_port.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report which computer the machine tools (run_command, read_file, …) currently operate on.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. 'Report' implies a side-effect-free read, and the description usefully defines what 'active environment' means, but it never states that this is read-only, cheap, or side-effect free, nor what the response contains (name, id, host?).
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. The core assertion (which computer) comes first and the clarifying parenthetical is brief.
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 zero-parameter getter with no output schema, the description does cover the essential question of what the return value represents. It could be slightly stronger by noting the return shape or that the active environment can change via wake_environment/sleep_environment, but nothing critical to calling it correctly is absent.
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 takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter-level explanation is needed or missing.
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?
States a specific verb (report) and a precise resource (which computer the machine tools operate on), and grounds it by naming sibling tools (run_command, read_file). It is clear this returns the current/active target rather than a listing. It does not explicitly distinguish itself from get_environment_info or list_environments, which are the closest siblings.
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: an agent would call this to learn which machine its run_command/read_file calls will hit. There is no explicit when-to-use or when-not-to-use guidance and no named alternative for related questions (e.g., listing all environments vs. the active one), leaving the routing decision to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get status, resources and metadata for the computer you are currently working on.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden, but there is little behavior to disclose for a zero-argument read. It implicitly signals a non-mutating read, yet never states read-only semantics, permissions, or whether the call is local versus remote.
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; the verb, resource, and returned content all appear in one pass.
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?
With no output schema, the description usefully names the return categories (status, resources, metadata), which is enough for an agent to call and interpret it. It could say slightly more about scope (the 'computer you are currently working on'), but nothing essential 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 takes no parameters, so there is no parameter semantics to convey and the baseline of 4 applies. The description correctly avoids inventing inputs that don't exist.
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?
States a specific verb ('Get') and resource ('environment info') and enumerates the payload (status, resources, metadata), so the agent knows what it returns. It does not explicitly differentiate itself from the sibling get_active_environment, so it stops short of a 5.
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?
No when-to-use guidance, no prerequisites, and no mention of the obvious alternative get_active_environment. The agent must infer usage purely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Install Debian/Ubuntu packages on your computer via apt-get. The install is permanent: it is still there next session, so check whether something is already installed before reinstalling it.
| Name | Required | Description | Default |
|---|---|---|---|
| packages | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose a valuable behavioral trait — persistence across sessions. However, it omits whether root/sudo privileges are required, what happens on failure, and whether dependencies are pulled in, which matters for a mutation tool.
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?
Two tight sentences, zero waste. The core action is front-loaded and the permanence caveat follows immediately, making it easy to scan.
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-annotation, no-output-schema mutation tool, it covers purpose, persistence, and a reinstall caution. It falls short only on permission requirements and failure/return behavior, which an agent would benefit from knowing.
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% and the single parameter is undocumented in the schema. The description only implies plurality via the word 'packages' but adds no format, naming, or count-limit detail (e.g., the 1–20 item bound and the allowed character pattern).
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 verb (Install), a precise resource (Debian/Ubuntu packages), and the mechanism (via apt-get). An agent can immediately distinguish this from siblings like run_command or write_file without opening any schema.
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?
It gives clear operational context: the install is permanent, so check whether something is already installed before reinstalling. This guides when to use it and cautions against redundant calls, though it names no alternative sibling tool for package inspection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the saved checkpoints of this computer, oldest state to newest, with when each was taken, how large it is, and which one the computer is currently running from ("YOU ARE HERE"). Worth checking before a risky change — there may already be a recent one — and before saving another, since the number a computer may keep is limited.
The list is a history, not a stack: if an older checkpoint was restored and work carried on from there, the checkpoints saved down the path that was left are still listed and still restorable.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the load and discloses genuinely non-obvious behavior: ordering is oldest-to-newest, there is a cap on retained checkpoints, and — importantly — the list is a history rather than a stack, so checkpoints on abandoned paths remain listed and restorable. It does not state permission/auth needs or the return format, but the disclosed semantics are unusually rich.
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?
Front-loads the core purpose and the return contents in the first sentence, then uses the second paragraph only for the non-obvious history-vs-stack caveat. Slightly long for a zero-param lister, but nearly every sentence adds real information.
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?
With no annotations, no output schema and no parameters, the description fully compensates by describing the returned fields, the ordering, the retention cap and the restore-path behavior. An agent has everything it needs to call and interpret this 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?
The tool takes zero parameters, so the baseline is 4. The description correctly implies no filtering or input is required for this listing.
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?
Specific verb (List) plus resource (checkpoints) plus scope (of this computer) plus the exact contents returned (when taken, size, which one is running, marked 'YOU ARE HERE'). It is immediately distinguishable from its create_checkpoint, delete_checkpoint and restore_checkpoint siblings.
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?
Gives two concrete triggers — check before a risky change, and check before saving another because the number kept is limited — which is clear situational context. It stops short of explicitly naming the sibling to use for the save/restore actions, so it is clear but not fully routed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a directory on your computer (ls -la). Worth doing at the start of a session — the machine usually still holds work, tools and notes from last time.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Default /workspace |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. The '(ls -la)' analogy usefully implies a read-only listing with hidden files and details, but it says nothing about permissions, path handling, or return format edge cases.
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?
Two short sentences that are front-loaded with the core action and then the rationale. Every sentence earns its place with no filler.
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 trivial one-parameter read tool with no annotations or output schema, the description conveys purpose, the ls -la output shape, and when to invoke it. Only explicit return-format or permission notes are 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?
Schema description coverage is 100%, so the single 'path' parameter (default /workspace) is already documented. The description adds no syntax or format detail about paths beyond what the schema supplies, matching the baseline for high-coverage schemas.
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?
States a specific verb and resource ('List a directory') and clarifies the format with the '(ls -la)' equivalence. It is clear on its own but does not distinguish itself from siblings like read_file or the other list_* tools.
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?
Gives clear usage context — 'Worth doing at the start of a session' — and explains why (the machine holds prior work, tools, and notes). It stops short of naming alternatives or when not to use it, so it lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every computer on this account with its status, plus how many may exist and how many may run at once. Each one is a persistent machine that keeps whatever was installed on it.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does add real context beyond the name: persistence ('keeps whatever was installed on it') and quota semantics ('how many may exist and how many may run at once'). It does not say whether the call is read-only in effect, how results are ordered, or whether the listing can be large — gaps that matter for a no-annotation tool.
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?
Two short sentences, front-loaded with the primary action, and the second sentence earns its place by explaining the persistence/durability model an agent needs to reason about the returned machines.
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?
There is no output schema and no annotations, so the description should describe the return shape more concretely — 'status' values, quota fields, and ordering are all left vague. It is adequate for a simple list but not fully self-contained.
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 takes zero parameters, so there is nothing for the description to clarify; the baseline for a parameterless tool is 4.
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 gives a specific verb and resource ('List every computer on this account') and adds what each entry includes (status, quotas). That distinguishes it from the other list_* siblings (list_checkpoints, list_directory, list_exposed_ports), though it never names them directly.
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 statement of when to use this versus get_environment_info or get_active_environment, which are the obvious overlapping siblings for inspecting machines. Usage is only implied by 'List every computer'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every port this computer publishes to the internet, with its public address. Use this before exposing a port — a port published earlier, even in a previous session, is still published now.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it delivers a genuinely non-obvious behavioral trait: published ports persist across sessions ('even in a previous session, is still published now'). It also discloses the output shape (port + public address). It does not state permissions, rate limits, or refresh semantics, keeping it short of a 5.
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?
Two sentences, zero filler. The scoping clause is front-loaded and the persistence caveat follows immediately as the reason to act.
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 zero-parameter, annotation-free, output-schema-free tool, the definition covers purpose, trigger, and the key stateful behavior. It stops short of describing full return structure or error conditions, but an agent has enough to select and call it 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?
Zero parameters, so the baseline is 4. The description correctly describes the return payload rather than params, and there is nothing to compensate for.
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?
Specific verb ('List') plus a precisely scoped resource ('every port this computer publishes to the internet'), with an added output detail ('with its public address'). It is clearly distinguishable from the other list_* siblings and from expose_port/unexpose_port.
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?
Explicitly states when to call it ('Use this before exposing a port') and why the check matters. It does not name expose_port as the alternative tool, but the ordering context is clear enough to route the agent correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a file from your computer, including files written in an earlier session.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path, or relative to /workspace |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It adds one useful fact — files from earlier sessions persist and are readable — but says nothing about error behavior on missing paths, size or encoding limits, binary files, or permission failures.
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 zero filler; the persistence detail is folded into the same sentence rather than tacked on. Nothing could be removed without losing information.
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 read tool with 100% schema coverage and no output schema, the definition is functional but thin: it never says what is returned or how failures manifest. The session-persistence note is the only behavioral content beyond the name.
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 single parameter is fully documented in the schema, including that the path may be absolute or relative to /workspace, so the baseline is 3. The description adds no additional meaning about path resolution or edge cases beyond what the schema already states.
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?
States a specific verb and resource ('Read a file'), which is unambiguous and distinct from write_file and list_directory. However, it does not explicitly name or contrast itself with any sibling, so an agent must infer the boundary on its own.
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 only implied by the verb; there is no statement of when to prefer this over list_directory or run_command (e.g. for cat-like reads), nor any prerequisites. The persistence clause hints at a valid context but does not constitute routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Put this computer back to a saved checkpoint. The entire filesystem and everything installed is replaced by the state it was in then.
THIS DISCARDS WORK. Anything done since that checkpoint — files written, packages installed, commits not pushed anywhere — is gone. Pass keep_current_as to save the current state as its own checkpoint first, which is almost always what you want when you are not certain.
It does NOT delete the checkpoints saved after the one you go back to. They stay listed and restorable, and anything saved from here on branches off the point you returned to — so going back to try a different approach costs nothing but the work not kept.
The computer restarts to do it and is briefly unavailable; any process you left running stops. If it is asleep, the checkpoint is applied the next time it wakes.
| Name | Required | Description | Default |
|---|---|---|---|
| checkpoint | Yes | Checkpoint id, from list_checkpoints | |
| keep_current_as | No | Save the current state under this name before replacing it |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so richly: entire filesystem and installed packages are replaced, uncommitted work is lost, the machine restarts and is briefly unavailable, running processes die, and a sleeping machine defers the restore until wake. These are non-obvious operational traits an agent must know before invoking.
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?
Front-loads the single most important fact in caps ('THIS DISCARDS WORK'), then proceeds through mitigation, non-destructive nuance, and restart side effects. Every sentence carries unique information; nothing is padding.
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 destructive, restart-triggering operation with no annotations and no output schema, the description covers consequences, mitigation, reversibility of the checkpoint list, and availability impact — everything an agent needs to call it correctly and warn the user.
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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the motivation and semantics of keep_current_as ('save the current state as its own checkpoint first'), not just its name. The checkpoint parameter is left to the schema's pointer to list_checkpoints.
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?
States a specific verb and resource ('Put this computer back to a saved checkpoint') and immediately names the sibling it is not: create_checkpoint, delete_checkpoint, and list_checkpoints are all implicitly contrasted by the restore semantics. An agent can distinguish it from every other checkpoint tool without opening a schema.
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?
Explicitly frames the decision: this DISCARDS WORK, and 'Pass keep_current_as ... which is almost always what you want when you are not certain.' It also clarifies that later checkpoints survive and future saves branch, so the agent knows returning is cheap. This is exactly the when/when-not guidance the dimension asks for.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a shell command on your computer (bash). Returns stdout, stderr and the exit code. This is a real persistent machine — anything you install or change here is still here next session.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory (default /workspace) | |
| command | Yes | Shell command to run | |
| timeout_seconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does add genuinely useful context — the return channels (stdout/stderr/exit code) and, importantly, that state persists across sessions, which is a real behavioral trait. But it omits destructiveness/irreversibility warnings, timeout semantics (capped at 600s), and any sandbox or permission model.
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-loaded with the action and output contract, then the persistence caveat. Every sentence adds information; there is no filler.
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?
No output schema exists, and the description does cover the return contract, which helps. But with zero annotations and an arbitrary-execution tool, it should still say more about timeout behavior, failure semantics, and how it relates to the dedicated sibling tools.
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 coverage is only 67%: cwd and command are documented inline, but timeout_seconds has no description at all. The description says nothing about parameters — not the /workspace default working directory, not the timeout bounds — so it fails to compensate for the undocumented parameter.
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?
States a specific verb and resource ('Run a shell command on your computer (bash)') and enumerates the return values (stdout, stderr, exit code). However, it never distinguishes itself from siblings like install_package, read_file, write_file, or list_directory, which it clearly overlaps with as a generalized escape hatch.
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 when-to-use or when-not-to-use guidance and no mention of any alternative. An agent must infer on its own whether to reach for run_command versus the many dedicated siblings (install_package, read_file, list_directory), which is a material omission for such a broad tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Put a computer to sleep. Its entire filesystem — files, installed packages, databases and caches — is archived and restored intact on the next wake. Nothing is lost by sleeping one.
| Name | Required | Description | Default |
|---|---|---|---|
| environment | Yes | Computer id, slug or name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose the key trait: state is archived and restored intact on wake, so nothing is lost. This tells the agent the operation is reversible and non-destructive. It stops short of stating auth requirements, cost/latency, or whether the environment remains reachable while asleep.
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?
Two sentences, front-loaded with the verb, and the second sentence earns its place by explaining the persistence guarantee. No filler or repetition.
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 no annotations and no output schema, the description covers the core behavior adequately but omits the state of the environment after sleeping, how it is resumed (the wake_environment sibling), and any permission implications. Adequate but with clear gaps given the structured fields provide no support.
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?
Single 'environment' parameter with 100% schema description coverage, so the schema already defines it as 'Computer id, slug or name'. The description adds no parameter detail, which is the expected baseline when the schema does the work.
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?
States a specific verb+resource ('Put a computer to sleep') and describes the effect on the filesystem. It is clearly distinguishable from the obvious counterpart wake_environment, though it never names that sibling explicitly.
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 when-to-use guidance, no mention of prerequisites, and no reference to alternatives like wake_environment, create_checkpoint, or restore_checkpoint. The relevant usage is only implied by the verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop publishing a port to the internet. The address stops working immediately and is forgotten, so it does not come back the next time this computer wakes.
| Name | Required | Description | Default |
|---|---|---|---|
| port | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does a good job disclosing the key behavioral trait: the address stops working immediately and is forgotten, so it will not reappear after the computer wakes. That persistence semantics is exactly the non-obvious detail an agent needs. It stops short of covering error behavior (e.g., unexposing a port that isn't published) or whether the call is idempotent.
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?
Two short sentences, front-loaded with the action and followed by the consequence. Every clause earns its place and nothing is padded.
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 mutation with no annotations and no output schema, the description covers the essential effect and its persistence semantics. Missing only edge-case behavior (already-unexposed port, error handling) that would make it fully self-sufficient.
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% for the single 'port' parameter, so the description is the only source, and it only indirectly signals that 'port' is a published port number rather than any local port. It adds no format, range, or matching detail beyond the schema's 1-65535 bound.
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?
States a specific verb ('Stop publishing') and resource ('a port'), scoped to the internet. It doesn't name the sibling expose_port explicitly, but the inverse relationship is unmistakable from the verb and the sibling list.
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 only implied: the agent can infer this is the tool to call to take back a port published with expose_port, but there is no explicit when-to-use statement, no prerequisite check (must the port be currently exposed?), and no mention of list_exposed_ports as a discovery step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Wake a sleeping computer and make it the active one, restoring its whole filesystem exactly as it was left. Any other running computer is put to sleep first, which archives its files rather than discarding them.
| Name | Required | Description | Default |
|---|---|---|---|
| environment | Yes | Computer id, slug or name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that the woken machine becomes active, that its filesystem is restored exactly as left, and crucially that any other running computer is put to sleep with its files archived rather than discarded. This is exactly the side-effect information an agent needs before a state-changing call. Auth/permission requirements and error behavior (e.g., unknown environment id) are not covered.
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?
Two sentences, front-loaded with the core action, then the consequential side effects. No filler, no restatement of the title.
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 state-changing tool with no annotations and no output schema, the description covers the essential behavior an agent must know: activation, filesystem restoration, and preemption of other environments. It is slightly thin on failure modes and what (if anything) is returned, but nothing critical 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?
Schema description coverage is 100% and the single parameter ('environment': computer id, slug or name) is fully documented there. The description implies the parameter identifies a sleeping computer but adds no syntax or resolution details 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?
States a specific verb and resource (wake a sleeping computer), then adds the two distinguishing outcomes: it becomes the active environment and its filesystem is restored exactly as left. This clearly separates it from sleep_environment and create_environment without needing to read the schema.
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 precondition is explicit – the target must be a sleeping computer – so an agent knows the trigger condition. It does not name alternatives (e.g., create_environment for a fresh machine) or state when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a file on your computer (creates parent directories). Files under /workspace and the home directory survive across sessions; /tmp does not.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path, or relative to /workspace | |
| content | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses that parent directories are created and which paths persist across sessions, but omits critical write semantics such as whether existing files are overwritten, encoding, and permission errors.
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?
Two tight sentences with zero waste. The core action is front-loaded and the persistence caveat follows immediately, so every clause 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 mutation tool with no annotations and no output schema, the description covers the essentials (action, directory creation, persistence) but leaves overwrite semantics and failure modes unaddressed. Adequate but with a notable gap for a destructive-by-nature operation.
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 coverage is 50%: 'path' is documented in the schema while 'content' is not, though its meaning is self-evident. The persistence note adds useful meaning about path location semantics beyond the schema's 'absolute or relative to /workspace' line, but overwrite behavior of content is left unspecified.
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?
States a specific verb and resource ('Write a file on your computer'), which clearly separates it from read_file and list_directory among the siblings. It does not explicitly name an alternative tool, so it stops short of full sibling routing, but the action is unambiguous.
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 when-to-use or when-not-to-use guidance. The persistence note (workspace/home survive, /tmp does not) implicitly guides where to write, which is real directional advice, but it never states prerequisites or contrasts with other tools.
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.
create_checkpointcreate_environmentdelete_checkpointexpose_portget_active_environmentget_environment_infoinstall_packagelist_checkpointslist_directorylist_environmentslist_exposed_portsread_filerestore_checkpointrun_commandsleep_environmentunexpose_portwake_environmentwrite_fileA private persistent computer: files and a bash shell that survive between runs.
Persistent Linux microVMs for agents: root, internet, sub-second resume and a public URL.
Real Linux labs your AI agent deploys, routes and runs, with domains, TLS, DBs and an audit log.
Remote Linux boxes for coding agents: Docker, a browser, screenshots, logs, human takeover.
Add one secure layer between your agents and this server.