Runtime Cloud

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

Annotations already declare readOnlyHint=true and destructiveHint=false, yet the description still adds real behavioral context: sso requires an owner or admin key and is changed on the website, emails is explicitly read-only with where to mutate it, and the credit paragraph explains addedBy agent and the topup command. This is useful context beyond the safety annotations.

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 a short "Read the account", but each action then becomes a dense run-on with nested parentheticals, URLs and asides (e.g. the credit/topup clause inside limits). Most content does earn its place given there is no output schema, but the wall-of-text structure makes it hard 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?

There is no output schema, so the description rightly describes what each action returns (balance, holds, free usage, quota_exceeded limits, referral credit, cost comparison, SSO state, email flags). Coverage is strong for all six actions, with only minor gaps like pagination and general error behavior.

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?

With 0% schema coverage the description must carry the params, and it does: each action enum value is defined in prose, compare documents its provider and days arguments, and it states the days default (30) which the schema does not. The provider list is largely mirrored from the schema rather than adding meaning, keeping it short of a 5.

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?

Opens with a specific verb+resource ("Read the account") and then enumerates each of the six actions with what it returns, so an agent knows exactly what is on offer. It is distinguishable from sandbox/volume siblings by being the account-wide introspection tool, though it never explicitly names a sibling to contrast with.

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 through the per-action breakdown and a few conditional hints ("with no usage yet, a stated example workload is priced", "Needs an owner or admin key" for sso). The only alternative routing is for emails, where it points at POST /v1/account/emails:update and the Settings UI; there is no general when-to-use/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds real value beyond them: it discloses the required authorization level ('Needs an owner or admin key') and the newest-first ordering, both of which shape whether and how an agent calls it.

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 dense sentences with no filler; the resource and ordering are front-loaded, followed immediately by filtering, pagination and the auth requirement. It is compact and front-loaded, though the single run-on inventory of record types is slightly heavy.

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 returned fields (time, client address, request id) and the auth requirement, so an agent knows what it gets and what it needs. Coverage is solid for a read-only list tool; only explicit sibling routing 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 already 100%, so the baseline is 3. The description nonetheless adds meaning: it clarifies that 'before' is a pagination cursor tied to the previous page's next value, and that 'action' accepts either a specific action or a dotted group prefix, reinforcing the schema's semantics in task terms.

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 resource (the account's audit log) and its ordering (newest first), plus the record types it contains. An agent can tell it apart from most siblings, though it never explicitly contrasts with runtime_events_list, which is the closest potential confusable.

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 concrete operational guidance for filtering (action or group ending in a dot) and pagination (page with before), which implies how to use it. However, it never states when to reach for this tool versus runtime_events_list, and offers no exclusions or prerequisites beyond the key requirement.

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

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

Annotations already cover safety (readOnlyHint, openWorldHint=false, destructiveHint=false), so the bar is lower. The description still adds real value by disclosing the return format (Markdown) and fidelity ('the same text as https://withruntime.com/docs'), which is the main behavioral question for a docs tool. It stops short of stating caching, auth, or length constraints.

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, and the core action plus source is front-loaded before the topic examples. The topic enumeration is somewhat duplicative of the enum and could be trimmed, but it aids fast scanning.

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 read tool with no output schema, the description covers what is returned and what can be requested; the remaining gap is only the 'when to use it' routing, which belongs to usage guidance rather than 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 100% and the topic parameter has a full 57-value enum, so the schema already carries the semantics. The description echoes a subset of those values ('start, javascript, python, cli, mcp, api...'), which is redundant rather than additive; no extra meaning (case sensitivity, aliases, fallback behavior for an invalid topic) is provided.

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 Runtime documentation page as Markdown') and identifies the source URL, so the agent knows exactly what comes back. It does not need to name siblings because none of the runtime_* tools are documentation readers, but it also never explicitly says so.

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 topic list (start, migrate, pricing, troubleshooting), which hints at when to reach for it, but there is no explicit 'use this when' or 'prefer this over runtime_support' guidance. The agent must infer the trigger condition.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, yet the description adds substantial detail beyond them: remove kills open connections before responding and requires the agent to delete DNS records at the external provider, verify reports whether the name currently points at Runtime, and add requires a funded top-up. These side effects and prerequisites are exactly the kind of context an agent cannot infer from annotations.

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?

One front-loaded purpose sentence followed by compact per-action clauses; every sentence carries information. The signature-style notation (add(...), verify(...)) is terse but readable, though the run-on quality of some clauses slightly reduces scanability.

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 does the work of describing returns: DNS records for add, activation status plus pointing state for verify, state and records per domain for list. It covers all four actions adequately, with only minor gaps (e.g. possible domain states, whether list paginates).

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% (hostname and action undocumented), but the description compensates by showing the per-action signatures — add(hostname, sandboxId, port), verify(hostname), remove(hostname) — which tells the agent which parameters apply to which action. It adds real meaning over the bare enum, though it doesn't clarify the shape of 'list' input.

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 opening sentence names a specific verb and resource — serving a sandbox port at a custom hostname with automatic HTTPS — and the per-action breakdown (add/verify/list/remove) makes each capability explicit. No sibling tool covers custom-domain mapping, so the resource itself is disambiguating.

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 lays out the workflow conditions: add returns records to configure, verify must be run and only activates when the TXT matches, remove stops serving. The prerequisite 'Needs a kept top-up' is stated. It does not name alternative tools (e.g. previews/ports) or say when not to use this one, but the resource is niche enough that the forward path is clear.

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

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

Annotations already declare readOnlyHint/ non-destructive/closed-world, so the bar is lower, and the description still adds substantive context: 14-day retention, newest-first ordering, and that each event carries the resource state as it was at the time, with stopReason explaining sandbox stops. It omits anything about pagination limits or result size, which matters for a list 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 tightly packed sentences: scope and ordering first, then the event taxonomy, then the resourceId routing hint and retention. No filler, and the most decision-relevant facts are front-loaded.

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 read-only list tool with annotations covering safety and no output schema, the description covers scope, ordering, event semantics, filtering, and retention. The remaining gap is pagination behavior (how cursor works, what happens past the limit), which an agent would need for large histories.

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 25% (only limit is documented), so the description must carry weight. It explains resourceId and gestures at the type enum via example event names, but cursor is never mentioned and the enum's meanings (e.g. host_unreachable vs unreachable) are left unexplained. Partial compensation only.

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: recent lifecycle events across sandboxes, snapshots, volumes, egress secrets and upstream proxy, ordered newest first. The event examples (created, running, paused, stopped) make the content concrete. It does not distinguish itself from the sibling runtime_audit_list, which an agent could plausibly confuse it with.

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?

"Pass resourceId for one sandbox's history" gives clear conditional usage for the main filtering axis, and "Kept 14 days" sets expectations on reach. No explicit when-not or alternative-tool routing (e.g. vs runtime_audit_list) is offered, so it stops 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.

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), the description discloses real behavior: reports go to the Runtime team, the requester is notified when a fix ships, duplicates merge, and list returns status plus ship note with an hourly sorting cycle. It also states a data-safety boundary. This is rich context that annotations alone do not convey.

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?

It is dense but front-loads the value proposition ('Reports go straight to the Runtime team...') and then walks the two actions in order. Some clauses are run-on (the kind enumeration, the sorting note), but each sentence carries 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 10-parameter tool with no output schema and mutation semantics, the description covers both actions, the lifecycle of a report, and submission constraints. It stops short of stating what submit returns (the schema notes an idempotencyKey is returned), leaving a small gap in the round-trip picture.

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 70%, so much is already documented, but the description adds routing meaning by grouping the 'kind' categories under the submit action and clarifying that 'requestId' comes from the error being reported and 'competitor' names another provider. The action enum (submit vs list) is only made meaningful here, which is the required 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?

The description states specific verbs and resources across two actions: 'submit(...)' for filing a bug/gap/idea and 'list(limit?)' for viewing this organization's reports. An agent can distinguish the two modes immediately, but no sibling tool (e.g. runtime_support, runtime_notices) is named to differentiate this feedback channel from adjacent support paths.

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 context for each action: submit when you hit a bug, limit, missing feature, doc gap, slowness or competitor gap (and praise), list to see org reports. It also states submission hygiene ('give what was tried, what happened and the requestId, never credentials, private files or user data'). What's missing is explicit routing against the sibling support/reporting tools.

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

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

Annotations already declare destructiveHint=true, and the description adds substantial operational detail beyond that: delete removes the version and its tags, running sandboxes are unaffected, and an image still needed by an App is refused with image_in_use. It also clarifies tag movement/removal and list-versus-get log behavior.

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 front-loaded with the overall scope, then compact action-specific clauses. Every sentence carries operational information, and there is no filler despite covering four actions and ten parameters.

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 complex four-action, destructive tool with no output schema, the description provides list/get return shape, pagination behavior, deletion effects, and a key error case. It does not describe tag/delete return values or every optional parameter in detail, but it is sufficient for an agent to invoke 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?

With only 40% schema description coverage, the description compensates well by spelling out action signatures and explaining cursor back-passing, tag movement and removal, and logsAfter as build-log lines. It still leaves state filtering and some optional parameter semantics implicit, so it is not fully exhaustive.

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 specific actions (list, read/get, tag, delete) on a specific resource (images sandboxes start from), and explicitly names runtime_images_build as the sibling that creates them. An agent can distinguish this tool from the build tool without opening either 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 per-action descriptions make clear what each action does and implicitly when to choose it, and the build sibling is explicitly named as the alternative for creating images. There is no explicit exclusion guidance against runtime_images_registries or sandbox-creation tools, so it falls short of a full when/when-not treatment.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false and openWorldHint=true; the description adds substantial context beyond that: builds are queued asynchronously, each build of a `name` becomes the next version tagged latest (or `tags`), `start` controls sandbox runtime and readiness, a Dockerfile's CMD/HEALTHCHECK fills it in, and rebuilds reuse unchanged layers unless `cache` is false.

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 source-selection constraint and the async/versioning behavior are front-loaded, and every sentence carries information rather than filler. It is a dense block of many clauses in one paragraph, which slightly taxes parseability, but nothing is wasted.

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 16 parameters, nested objects, no output schema and only 75% schema coverage, the description supplies the missing lifecycle context: return value ('returns the image queued'), how to poll readiness, and how sandboxes consume the result by id or name:tag. A handful of auxiliary parameters remain unexplained, but the core workflow is 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 coverage is 75%, so the schema carries much of the load, but the description adds real meaning for the highest-risk parameters: the semantics of `recipe` fields, that COPY reads `files`, that `start` is what a sandbox runs at launch, and that `tags` defaults to latest. It does not document several declared params (`labels`, `region`, `dockerignore`, `buildArgs`, `build`), so it does not fully compensate for the coverage gap.

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 ('Build a sandbox image') and immediately enumerates the three mutually exclusive sources (`image`, `dockerfile`, `recipe`) with examples. It also names the related sibling (`runtime_images` action get) that reports readiness, so an agent can distinguish this build tool from the list/manage image tools without opening schemas.

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 'exactly one of' constraint plus per-source descriptions make it clear which input to pick for a given situation, and it tells the agent where to check readiness afterward. It stops short of explicit when-not-to-use guidance (e.g., when a public image alone suffices and no build is needed), so it is clear context rather than full routing.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is partly covered. The description adds genuinely new behavior: credentials are 'Never returned', which tells the agent that list output cannot expose secrets and that set is a write-only store. It omits confirmation behavior for delete and any auth requirements.

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 purpose, then the payload variants, then the 'Never returned' caveat. No filler or repetition of the schema.

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 6-parameter mutation/read tool with no output schema, the description covers purpose, per-provider payload formats, and the secrecy of the values. It does not explain list return shape (acceptable, since 'Never returned' covers the security-relevant part) or delete semantics beyond the annotation's destructiveHint.

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 83%, so the baseline is 3, but the description goes further by spelling out the two distinct set payload shapes ({registry, username, password} vs {registry, accessKeyId, secretAccessKey}) and the Google _json_key convention. This tells the agent which parameters are mutually exclusive per provider, information not fully conveyed by flat schema fields.

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 specific verbs (list/store/forget) and a precise resource: the credentials builds use to pull private images. An agent can distinguish this from runtime_images_build or runtime_images without opening the schema. It stops short of naming siblings explicitly, but the scope 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?

The action enum (list/set/delete) is mirrored in prose, so the mapping between operation and tool is implied. However, there is no guidance on when to prefer this over runtime_secrets or runtime_images_build, and no stated prerequisites (e.g., permissions) for storing credentials.

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

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

Annotations already flag the mutating/destructive profile (readOnlyHint=false, destructiveHint=true), and the description adds real context beyond them: reserve requires credit on the account, and release immediately causes all sandboxes to send from shared addresses again. This discloses side effects and prerequisites not present in the structured fields.

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?

Purpose is front-loaded, then each action is covered in a compact clause with no filler. Slightly dense run-on phrasing and the redundant 'list: The organization's reserved addresses' restatement cost it the top score.

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 three-action mutation tool with no output schema and no parameter descriptions, the description covers operations, prerequisites, and side effects well. It does not describe what list returns, but with no output schema that is a minor gap.

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 0%, so the description must carry the meaning: it explains family values (4 default, 6), the addressId role (give one back by addressId), and the three action values. It meaningfully compensates for the missing schema descriptions, though it omits format details like the UUID nature of addressId.

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 resource (the organization's dedicated outbound addresses) and then names all three actions with concrete verbs and effects. An agent can tell what each action does without opening the schema, and the tool is clearly distinct from all 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?

Each action is given a clear context for selection (list = reserved addresses, reserve = per-sandbox addresses, release = return to shared), and the credit prerequisite for reserve is disclosed. There are no named exclusions or alternatives, but none exist among the siblings, so the guidance is effectively complete.

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

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

Discloses far more than the annotations: billing order (free usage first, then credit at sandbox rates within spending limits), no automatic retry on unknown outcomes, blockedReason enum values (credits, capacity, cost_cap, permission, volume) with a 30-second retry cadence, run_in_progress refusal on trigger, paused jobs staying paused, and volume rw vs snapshot semantics. Nothing here contradicts readOnlyHint=false / destructiveHint=true.

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 front-loaded first two sentences are strong and every clause carries real information, but the back half degenerates into a comma-spliced run-on enumerating ten actions, which is hard to parse at a glance. Content-dense but poorly structured.

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 9-parameter, deeply nested, 12-action tool with no output schema, the description covers execution, billing, failure and mutation semantics thoroughly. The gap is return values — list/get/runs/logs output shapes are never described, and the output schema's absence means the agent learns nothing about them here.

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 44%, but the description compensates by mapping each action to the parameters it consumes — create(input), cancel(id), trigger(id), reschedule(id, schedule), update(id, input), runs(id, order?), run(id), logs(id of a run, cursor?). That action-to-parameter mapping is nowhere in the schema and is exactly what an agent needs to call this multi-action tool correctly.

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?

Opens with a specific verb+resource+scope: jobs run a command in a fresh sandbox, once or on a cron schedule. That distinguishes it from runtime_sandboxes_exec (one-off execution) by the scheduling dimension, and it points at runtime_volumes semantics for persistence. It never explicitly names the sibling it replaces, 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?

Usage conditions are implied through the action enumeration (pause/resume/cancel/trigger/reschedule/update/runs/run/logs) and a few cross-references (runtime_secrets action jobs_put, compute.volumes). It explains trigger's refusal behavior precisely, but gives no explicit 'use this instead of X when Y' guidance against sibling sandbox tools.

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

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

Annotations already cover safety (readOnly, non-destructive) and the description is consistent with them via 'Changes nothing.' It adds real behavior the annotations don't: blocked jobs (multiple tasks, GPU, mounted volumes), per-setting notes explaining what couldn't carry over, and the fact that the output is a plan rather than a created job.

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?

One long run-on paragraph with heavy enumerations (compute, secrets, schedule, five-field cron, return fields). The purpose is front-loaded, but the middle sentences are dense and hard to parse, and some detail (Dockerfile FROM phrasing) is buried rather than structured into steps.

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, so the description carries the return-shape burden and does so fully: from, jobs with named subfields including blocked, and notes split into unmapped/changed/info. Combined with the next-step guidance, an agent has everything needed to call and act on the result.

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 `from`, `files` and `parameters` are already fully documented with pairings and the 1 MiB limit. The description restates the [{path, text}] shape and which file pairs go together, but adds little syntax or semantics beyond the schema. 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?

Opens with a specific verb and resource: read another platform's job (Cloud Run or AWS Batch) into Runtime jobs that use the same container. It names the two source platforms, the file types accepted, and the sibling tools (runtime_images_build, runtime_jobs action create) that follow, so an agent can separate it from runtime_jobs alone.

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 it changes nothing and that `runtime jobs import` builds and creates the plan, then routes to the build-then-create sequence with the other tools. Missing an explicit when-not (e.g., importing an already-Runtime job), but the workflow context is clear.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false. The description adds real behavioral detail beyond the annotations: `false` cuts open connections 'within seconds' and requires a kept top-up (billing/auth requirement) while being free. This is useful context the structured fields do not convey.

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 first sentence is front-loaded and states the core capability, but the text is a dense run-on with 'kept top-up' repeated three times and the get/set explanations folded awkwardly into one paragraph. It is understandable but could be tightened and split into clearer labeled lines.

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 helpfully states what `get` returns (on/off plus account eligibility) and what `set` does in each state, and it discloses the destructive cut-off from the annotations. Only minor gaps remain, such as nothing about how `<name>` is chosen or response error cases.

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% and the description compensates: it explains what `action: get` versus `action: set` do, which the schema leaves undocumented, and reinforces the `enabled` true/false semantics (including the connection-cutting consequence). It adds meaning beyond the schema's terse descriptions.

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 concrete verb and resource: enabling/disabling name-based (`<name>.sandbox.internal`) TCP reachability between sandboxes, plus the `get`/`set` duality. It is clear and specific, but it does not explicitly distinguish itself from networking siblings like runtime_networks_upstream_proxy or runtime_networks_wireguard, which an agent might otherwise confuse it with.

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 clearly separates the two actions: `get` reports current on/off state and account eligibility, while `set(enabled)` toggles reachability with explicit true/false outcomes. The 'Needs a kept top-up' condition tells the agent a prerequisite. However, it offers no guidance on when to prefer this over the other network tools.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true), and the description adds real behavioral context beyond that: credit requirement, that it's free, that disabling stops new signatures immediately but existing ones expire within 5 minutes, and that signed traffic is recognized by Cloudflare and other bot managers. It does not, however, describe auth/permission requirements for enabling.

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?

Purpose is front-loaded in the opening sentence, then structured by action (get, set). There is mild redundancy: the signature/outbound-request phrasing, the 'free' qualifier, and the 5-minute expiry are each effectively stated more than once across description and schema.

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, yet the description notes what 'get' returns (on/off state and whether the account may enable it), and the mutation lifecycle for 'set' is covered, including the 5-minute expiry grace. Adequate for an agent to call this toggle 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 coverage is only 50% (action has no schema description), but the description compensates by explaining the get/set semantics and the effect of enabled=true vs false. It meaningfully adds meaning beyond the enum and the enabled field description, which are the only structured cues.

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: letting sandboxes obtain Runtime's Web Bot Auth signature for outbound HTTP requests, or stopping them. This is a distinct capability from siblings like runtime_networks_wireguard or runtime_networks_upstream_proxy, though it does not name them 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?

The description splits behavior by the 'get' and 'set' actions and explains what each does, which implies when to invoke each. However, it gives no explicit when-to-use guidance, no prerequisites beyond 'needs credit', and no comparison to alternative networking tools an agent might reach for instead.

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

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

Annotations already flag destructive=true, readOnlyHint=false and openWorld=true, but the description adds real behavioral context beyond them: fail-closed semantics ('A proxy that fails fails the connection; nothing goes around it') and removal latency ('within seconds'). The only weak spot is the vague 'kept top-up' requirement.

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 overall purpose, then structures the three actions compactly in a single block with no wasted sentences. The cryptic 'kept top-up' clause is the one element that costs it a perfect score.

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 output schema, the description covers what each action does, the fail-closed safety behavior, and removal timing, and annotations handle the safety profile. It lacks any auth/permission or billing detail (what 'kept top-up' actually requires), leaving a small gap.

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 75%, so the schema already documents url, hosts, secret, and the action enum in detail. The description's 'set(url, secret?, hosts?)' merely restates the parameter list without adding format or meaning beyond the schema, fitting the baseline 3 for a well-covered 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?

States a specific verb+resource: routing the organization's sandboxes' outbound connections through a user-supplied HTTP/HTTPS proxy, and enumerates all three actions (get/set/remove) with their effect. The resource is distinct from sibling network tools like runtime_networks_wireguard and runtime_networks_private, though it never names them to draw the contrast 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?

The per-action breakdown (get = show current proxy, set = configure, remove = connections leave directly) implies when each mode applies. However, it gives no explicit guidance on when to choose this tool over alternatives such as wireguard or private networks, and the phrase 'Needs a kept top-up' is opaque rather than actionable.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, and the description goes further by quantifying destruction: the old key stops working and tunnels/connections end 'within seconds'. It also discloses a genuine hidden behavior — the generated private key appears in the config and is 'shown once'. It does not cover permission/auth requirements or rate limits.

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

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

The overall purpose is front-loaded, then a compact action-by-action breakdown follows, with no filler sentences. It is dense to the point of being a single run-on paragraph, but every clause carries information an agent needs.

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 six parameters, no output schema, and a mutation-heavy surface, the description carries the return-value burden itself and does so: get returns endpoint, gateway key, peers and per-sandbox addresses; add_peer returns a wg-quick config. The main remaining gap is account/prerequisite detail behind 'Needs a kept top-up' and any preconditions for create.

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?

With only 50% schema description coverage, the description compensates well: it gives the subnet default (10.250.0.0/16), explains that omitting publicKey makes Runtime generate the pair, ties peerId to rotate/remove, and contextualizes name for add_peer. The only under-specified parameter is the action enum itself, whose values are only implied by the per-action prose.

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?

Opens with a specific resource (a WireGuard private network connecting the user's own network into sandboxes) and then names every action verb explicitly: create, get, add_peer, rotate_peer, remove_peer. This clearly separates it from sibling network tools such as runtime_networks_private and runtime_networks_upstream_proxy.

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?

Each action is given a usage context (create it, get endpoint/keys, add a machine or router of yours, rotate to get a new key, revoke a peer), which tells an agent which action to pick for a given intent. It stops short of naming alternatives or stating when-not to use this tool versus its network siblings, and 'Needs a kept top-up' is left unexplained.

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

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

With destructiveHint=true and readOnlyHint=false, the annotations only signal that something here mutates; the description pinpoints exactly which action mutates ('read does, keeping the first read time') and which does not ('get'). That is the crucial side-effect disclosure the annotations cannot express. It still omits auth requirements, whether acknowledgement is reversible, and any rate limits.

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

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

Two dense sentences with no filler, and the highest-value fact (which action mutates) is front-loaded in the second sentence. The clipped, note-like phrasing reads as slightly fragmentary but wastes nothing.

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 4-parameter tool with 0% schema coverage and no output schema, the description leaves too much open: no mention of pagination via cursor/limit, no description of what a notice record contains, and no coverage of the 'list' action. Adequate only for the narrow get-vs-read decision.

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 must carry parameter meaning, and it explains only the 'action' enum for two of its three values. The 'id', 'limit', and 'cursor' parameters receive no explanation anywhere, leaving pagination and targeting semantics undocumented.

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 sentence names the resource concretely (account notices) and enumerates what they cover: pause expiry, unpaid storage, deletion deadlines. The second sentence distinguishes two of the three actions, so an agent knows this is the notice retrieval/acknowledgement tool. It falls short of a clean verb+resource statement for the 'list' action.

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 a real when-to-use distinction between 'get' (non-mutating) and 'read' (marks as read), which is the most consequential choice for the caller. However, it says nothing about when to use 'list' vs 'get', when paging is needed, or the broader context in which notices matter.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the agent knows this mutates and reaches outside. The description adds genuinely useful behavior beyond that: header values are never shown back and flush pushes immediately. It does not disclose the consequences of delete (does removing an export stop telemetry?) or whether existing exports keep pushing while modified, which are the traits an agent most needs 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?

Three sentences, purpose first, then action-specific notes; no filler. The noun-phrase opening ('Exports that push...') is slightly awkward but the information density is good and nothing is redundant.

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 seven-parameter, six-action mutation tool flagged destructive with no output schema. The description covers only create and flush while list, get, update and delete are invisible, and return behavior is never described. An agent would have to guess at most of the action surface before calling it.

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 57%, so the description should fill gaps, but it only touches endpoint, headers and signals, and mostly restates what the schema already says (OTLP base URL, auth headers). Parameters id, enabled and the action-specific meanings of list/get/update/delete receive no explanation anywhere, leaving half the interface undocumented.

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 sentence names the resource and what it does: configures exporters that push sandbox events, metrics and API spans over OTLP/HTTP JSON to an external endpoint. That is specific enough to separate it from siblings like runtime_sandboxes_metrics or runtime_webhooks_manage. It falls short of a 5 because the multi-action scope (list/get/update/delete) is never stated, only the create and flush semantics appear.

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 usage for two actions: create needs endpoint, headers and signals; flush pushes immediately. It says nothing about when to use list/get/update/delete, when not to use the tool, or what prerequisites exist for pushing to an endpoint. Usage is inferable from generic CRUD naming rather than explained.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the bar is lower, and the description still adds real behavioral facts: open is idempotent per sandbox and port, it requires a kept top-up, and close terminates existing connections before it returns. These are non-obvious traits not carried by the annotations. It could say more about failure modes or quota behavior, but this is solid added value.

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 resource definition, then one compact clause per action; there is little waste. The phrasing is telegraphic in places ('Needs a kept top-up', 'or one sandbox's'), which briefly costs clarity but keeps the definition short.

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 four parameters, no output schema, and annotations already covering the safety profile, the description is nearly sufficient: it scopes the tool, enumerates all three actions, maps their parameters, and even states the open return value. Only minor gaps remain, such as the return shape for list and the error behavior when a top-up 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 only 50% (action and portId are undescribed in the schema). The description compensates by mapping parameters to actions — open(sandboxId, port), list(sandboxId?), close(portId) — which the schema cannot express, and by noting that port is the in-sandbox listening port. That is meaningfully beyond the structured fields, though it adds no format or constraint detail for portId.

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 opening sentence names the concrete resource (public address:port pairs for raw TCP into a sandbox) and scopes it precisely with parenthetical examples (databases, game servers) plus the discriminating phrase 'anything not HTTP', which separates it from the HTTP-serving preview/domain siblings. Each of the three actions is then named with its verb and resource, so an agent can tell what the tool does 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?

It gives clear per-action usage context: open for exposing a listening port, list with an optional sandboxId to scope results, and close by portId. It also implies when this tool is the right choice ('anything not HTTP'). It does not, however, explicitly name an alternative sibling (e.g. the HTTP preview tool) or state when not to use it, so it stops short of full routing guidance.

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

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

Goes well beyond the annotations (destructiveHint=true, openWorldHint=true) by disclosing the economics and side effects: unused room bills at a quarter of the memory rate, cancellation at least an hour before start costs nothing, a balance covering the estimate is required, declarations of what happens on decline, and that cancelling returns room while running sandboxes keep running and 'at the end nothing is stopped'.

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?

Content is front-loaded on create, the most important action, but the body is a dense semicolon-chained block of roughly 500 words with repeated material (the unused-room rate is stated twice) and no per-action structure, which makes the list/get/update/cancel guidance hard 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 15-parameter, five-action mutation tool with no output schema, the description still explains what each action yields — list returns bookings and declines newest first with window, status, phase and nextCursor; get returns status, window, phase and in-use counts; update and cancel describe their outcomes and failure behavior. Nothing essential to invoking it 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 description coverage is 93%, so the schema already documents ranges, defaults and per-field meanings for sandboxes, vcpu, memoryMiB, diskMiB, forKey, snapshots and region. The description restates most of this (1 to 10000 sandboxes, default 2 vCPU / 4096 MiB, 24-hour and 14-day limits) and only marginally adds, so 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 opening line states a specific verb and resource — hold/book room for many sandboxes, either for a time window or as standing room — and enumerates the five actions (create, list, get, update, cancel). An agent can tell this apart from runtime_sandboxes_create because the description explains room is booked in advance and creates are then never refused up to the booked amount.

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 reach for it — 'Use it before a batch of evals, rollouts or browser runs' — and gives the condition for standing room (a pool that deletes a sandbox after each use and makes another). It does not name a sibling alternative or state a when-not condition (e.g. single sandbox creation should use runtime_sandboxes_create), so it falls short of full routing guidance.

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

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

Annotations already declare destructiveHint/openWorldHint/readOnlyHint=false, but the description adds real context beyond them: start latency of 1-2s, a ~1 minute first-start penalty only on custom non-Ubuntu-24.04 x86_64 images because Chromium comes from the host, and the fact that get mints a fresh cdpUrl. It does not say whether stop is idempotent or what happens to an already-stopped browser.

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?

Purpose is front-loaded in the first clause and every subsequent sentence carries load-bearing detail (return values, timing, image caveat, internal address). The middle sentence is long and semicolon-chained, which slightly hurts scannability but not content quality.

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 steps up and documents the key return (cdpUrl) for both start and get, plus the practical latency and image caveats an agent needs before calling. Only peripheral details (id meaning, stop idempotency, behavior on second start) are 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?

Schema coverage is 60% (headless, width, height documented; id and action bare), and the description adds meaning: headless=false 'shows it on the sandbox's desktop with a live view', plus the semantics of each action enum value. It still never explains what the required id refers to, leaving the agent to infer it is a sandbox id.

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 resource (a Chromium browser running inside a sandbox, reachable over CDP) and its three lifecycle actions. It is clearly distinguishable from the desktop_* siblings and exec, since it names the CDP/Puppeteer/Playwright use case rather than generic desktop control.

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?

Explains what each action does in context: start returns a cdpUrl to hand to Playwright/Puppeteer/browser-use/Stagehand, get refreshes state and the cdpUrl, stop ends it, and headless=false selects the live-view desktop mode. It never names an alternative sibling or an explicit when-not condition, so it stops 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.

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

Annotations only declare the generic write/open-world/idempotent profile, while the description adds substantive behavior: billing order (free usage then credit, 'nothing to choose'), idle-pause at 300 seconds, quota caps for uncredited accounts, and that a paused sandbox holds no slot. Nothing here conflicts with the annotations, and the funding/pausable no-op notes explain surprising parameters.

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 purpose, image contents, and defaults before the quota caveats, and every sentence carries information. The final quota sentence is dense and hard to parse on one read ('8 vCPU / 16 GiB in all, at most 5 sandboxes kept and 50 made a day'), which costs it the top score.

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 30-parameter, nested-object creation tool with no output schema, the description covers the essentials an agent needs before calling: defaults, wait behavior, what is returned ('returns its state', plus idempotencyKey), and quota limits. Remaining gaps (region, image resolution, volumes) are largely handled by schema descriptions.

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 already 87%, so the baseline is 3, but the description adds real meaning the schema lacks: the effective default shape (2 vCPU / 4096 MiB / 4096 MiB disk), no time limit by default, and the credit-dependent ceilings on vcpu/memory/disk and sandbox counts. Region, cpu, volumes, and tailscale are still left entirely to 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?

States a specific verb and resource with concrete content: 'Create a Linux sandbox (Ubuntu with python3, node, bun, git, gcc and sudo)'. That clearly distinguishes it from creation-adjacent siblings such as runtime_sandboxes_fork, runtime_sandboxes_list, or runtime_sandboxes_manage.

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?

Tells the agent the creation lifecycle: it waits up to 60 seconds, returns its state, and 'run commands once it is running' points at the exec sibling. No explicit when-not or direct alternative (fork, snapshot) is named, so it stops short of full routing guidance.

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

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

Annotations already declare readOnly=false, destructive=true, and openWorld=true, so the safety profile is covered. The description adds real operational context beyond them: start returns a live view URL, input is by pixel coordinates, keys use xdotool names, and open/launch spawn external programs.

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 purpose, then a compact semicolon-delimited enumeration of capabilities. Dense but well organized for a 16-action tool, with the screenshot note last as a natural follow-up.

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 carries value by noting that start yields a live view URL and that screenshot reveals results. It does omit several enum actions (stop, cursor, status, mouseDown/mouseUp), leaving minor gaps for a multi-action 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?

Schema coverage is 61%, and the description compensates by mapping parameters to actions ('start (width,height)', mouse via pixel coordinates, keys, url, argv/launch). This action-to-parameter mapping is not present in the schema itself, so it adds genuine value despite coverage gaps on x/y/width/height/button.

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 ('Drive a sandbox's Linux desktop') and enumerates the concrete operations it supports, so an agent immediately knows this is the interactive input tool. It explicitly distinguishes itself from the sibling runtime_sandboxes_desktop_screenshot, which it delegates result inspection to.

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 ('like a person') and names the complementary tool to use for results ('Take runtime_sandboxes_desktop_screenshot'). It does not, however, state when to prefer this over runtime_sandboxes_browser or runtime_sandboxes_exec, which are plausible alternatives.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so safety is covered. The description adds genuinely new operational context: only one recording at a time, an 8192 MiB per-sandbox retention cap, and automatic stop before the disk fills. These constraints are useful and not derivable from the structured fields.

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, then the action workflow, then constraints, with no redundant sentences. The semicolon-heavy telegraphic style is dense but every clause carries distinct 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 output schema, the description appropriately explains what start returns (a recording id) and how to retrieve the finished file. For a 7-parameter, four-action tool the coverage is solid, though it could briefly note default behaviors per action.

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 71% and crf/fps/maxMiB/maxSeconds already carry schema descriptions, so the schema does much of the work. The description nonetheless adds meaning by mapping action values to parameters (start returns an id; stop/delete take recordingId), clarifying the otherwise opaque enum-to-argument relationship.

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?

Names a specific verb (record) and resource (a sandbox's desktop to an MP4 file), clearly distinguishing it from siblings like runtime_sandboxes_desktop_screenshot and runtime_sandboxes_desktop_act. An agent knows immediately this tool captures desktop video rather than a still frame or input action.

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?

Describes the multi-step workflow precisely: start returns a recording id, stop (recordingId) finalizes the file, and list/delete round out the actions, plus the exact fetch command for download. It stops short of stating when to prefer this over the screenshot sibling, but the action semantics give clear usage context.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds meaningful behavior beyond that: the result is base64-encoded image bytes and the tool fails without a started desktop, which the agent needs to sequence calls correctly.

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, value and precondition front-loaded, with no filler. It is efficient; a brief clause on parameter format would not have hurt but the current length is defensible.

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 states the return type (base64 image data), and it notes the runtime prerequisite. However, for a two-parameter tool at 0% schema coverage it leaves parameter meaning undocumented, so it is only marginally 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 0% for two parameters, so the description carries the full burden, yet it never explains the required 'id' (presumably the sandbox/desktop identifier) nor the 'format' enum (png/jpeg) even though the output format is mentioned generically. An agent cannot infer valid values for 'format' or what 'id' refers to from the description alone.

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 resource (a sandbox's desktop) and the output form (base64 image data), which is enough to distinguish it from siblings like runtime_sandboxes_desktop_act and runtime_sandboxes_desktop_record. It never uses an explicit verb, but 'screenshot' functions as the action.

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 a concrete precondition — the desktop must be started via runtime_sandboxes_desktop_act action start — naming the specific sibling and action needed to enable this tool. It does not state when to prefer this over related desktop tools, but the prerequisite guidance is unusually actionable.

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

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

Goes well beyond the destructive/openWorld annotations: 16,000-char per-stream truncation with first line plus tail and outputCut, timeout returning timedOut: true with partial output, background returning a processId immediately, and the execution identity (sandbox user with passwordless sudo, HOME=/workspace, root alternative). It also notes env values are never echoed back, which is meaningful secret-handling 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 core action and result shape, then progressive detail on truncation, timeout, background and identity. Dense but nearly every clause adds information; the closing env sentence partially restates the schema description.

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 11 parameters and no output schema, the description supplies what's missing: the result fields (exitCode, stdout, stderr, timedOut, outputCut, processId, idempotencyKey) and the truncation/timeout behaviors that change how an agent must parse output. Nothing essential for correct invocation 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?

Schema coverage is already 91%, so the baseline would be 3; the description earns above that by explaining the observable effect of user/root, the sudo-saving intent, timeout semantics, and the security rationale for env. Minor overlap with schema text (env, timeoutMs) keeps it from a 5.

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?

Opening sentence names a specific verb (run), the resource (a command in a sandbox), both invocation modes (bash -c or argv) and the return values (exitCode, stdout, stderr). It also routes background work to runtime_sandboxes_process, distinguishing it from that 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?

Explicitly states when to use background: true (servers, watchers, interactive programs) and which sibling controls the resulting process. It also notes the tool waits for a still-starting sandbox. It doesn't cover when to prefer runtime_sandboxes_interpreter_run or files_write over a raw shell command, so it stops short of full when/when-not guidance.

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

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

Beyond the annotations, it discloses the important behavioral traits: links are public without an API key, expire within a bounded range, GET downloads while PUT accepts a raw body, archive folders become .tar.gz files, and the response includes url and expiresAt. It also notes how to revoke all sandbox links, which is valuable operational 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?

The definition is dense but efficient: it front-loads the core purpose, then packs method, archive, expiry, response, and revocation context into very little text. The examples and revoke note are useful rather than 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?

There is no output schema, but the description states that the answer contains url and expiresAt. With high schema coverage and annotations, the description supplies the remaining operational context an agent needs to invoke 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?

Schema coverage is already 88%, so the schema does most of the parameter documentation. The description reinforces method, archive, and expiry semantics but largely repeats what the schema already says for those fields and does not add much for id, path, wake, filename, or maxBytes.

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 opens with a specific verb and resource: making an expiring file link in a sandbox. It also states the key scope distinction that the link is publicly openable without an API key, which separates it from sibling file-read/write 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?

It gives clear contextual usage for browser downloads and service fetches, and explains how to choose between GET and PUT modes plus archive behavior. It does not explicitly name alternative sibling tools or say when not to use this tool, keeping it 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.

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely useful operational context beyond that: the 2,000-entry cap and an explicit truncation indicator, plus the depth ceiling of 10. It does not describe pagination mechanics or the exact truncation field name, 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?

Three tight sentences, front-loaded with the core action and return shape, then the modifiers, then the hard limit. 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?

With no output schema, the description usefully enumerates return fields and the truncation signal, and annotations cover the safety profile. It stops short of explaining the 'hidden' parameter or how to page past a truncated result, which leaves a minor hole for a 6-parameter listing 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?

Schema description coverage is only 17% (path alone), so the description has to carry the load, and it does for most parameters: path default (/workspace), depth semantics ('goes deeper', up to 10), and glob filtering with a concrete pattern example. limit is implied by the 2,000-entry mention, but 'hidden' and 'id' get no explanation, leaving a gap.

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 in a sandbox') and even enumerates the returned fields (name, path, type, size, mode, modifiedAt), which cleanly separates it from siblings like runtime_sandboxes_files_read, files_write and files_watch. An agent can identify the operation 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?

Usage is implied rather than stated: it notes the default path (/workspace) and how depth/glob behave, but never says when to use this versus runtime_sandboxes_files_read or files_manage, nor any exclusion. Adequate context, no routing guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds real behavioral context beyond that: overwrite replaces an existing target, recursive is required to remove a directory, and remove/mkdir are tolerant of missing paths. It stops short of stating permission requirements or what stat actually returns.

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 terse action-prefixed clauses, front-loaded by action name, with zero filler. Every sentence contributes a distinct semantic detail.

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 6-parameter mutation tool with no output schema, the action semantics are covered but the return behavior of stat ('what it is') is left vague and the sandbox-id parameter and authorization model are untouched. Adequate but with visible gaps.

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 33%, so the description carries meaningful weight, and it does: 'to' is tied to rename, 'overwrite' is explained as the replace toggle, and 'recursive' is tied to directory removal. The 'id' and 'action' parameters are self-evident, so the ambiguous booleans are the ones that matter and they are covered.

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 enumerates the four actions (stat, mkdir, rename, remove) with a concrete effect for each, so an agent knows exactly what the tool does. It distinguishes the tool from read/write/list siblings via the action vocabulary, though it does not name alternatives 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?

Usage is implied by the per-action breakdown rather than stated as when-to-use guidance, and no sibling alternative (e.g. files_read, files_write) is named as a fallback. The note that missing paths are not errors for remove/mkdir is a useful operational hint but not routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: a 1 MiB per-read limit, that the reply includes total line count, and that any path the sandbox user may read is allowed. It omits error/oversize behavior, but the added constraints are substantive.

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 tight sentences, front-loaded with the core action and immediately followed by the encoding and paging mechanics. No filler; every clause conveys an operational detail.

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 does note the reply carries the total line count, and it covers size limits, encoding, paging, and permission scope. A little more on the returned content structure (e.g., how base64 vs text is surfaced, truncation signaling) would make it fully 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 low (20%), so the description carries real weight: it explains encoding (text/base64), the startLine/lineCount line-range semantics, and the path access permission scope. Only 'id' remains unexplained, but its UUID type makes it self-evident, so the description compensates well for the coverage gap.

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 (read) and resource (a file in a sandbox) with the scope of what it returns (text UTF-8 or base64). This clearly separates it from siblings like files_list, files_write, files_manage, and files_watch without needing to open 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 implies usage through the encoding and line-range mechanics but never states when to choose this over alternatives such as files_list or files_manage, nor any prerequisites. Usage is inferable from context rather than explicitly guided.

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

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

Annotations only supply the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false); the description goes well beyond them by disclosing the 4-watch cap, webhook rate limit (one event per 2 s, 16 watches per account), timeout behavior (1 h default, 0 = until stopped), and the key operational fact that reading never wakes a paused sandbox.

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?

Dense, front-loaded and organized by action with semicolon-separated clauses, so no sentence is wasted. It is information-rich rather than bloated, though the action list runs long enough that an agent must parse several clauses to find the one it needs.

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 15-param mutation-capable tool with no output schema, the description supplies the return contract for read (events since cursor, folded writes with count, nextCursor) and the lifecycle constraints. It leaves the semantics of batchMs, maxWatches and idempotencyKey to the schema, but overall an agent has enough to 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?

With 67% schema coverage across 15 params, the description carries real weight by mapping arguments to actions (path/recursive/events/include/exclude/timeoutMs/webhook for start; watchId/cursor/waitMs for read) and explaining folded write counts. It omits batchMs, maxWatches and idempotencyKey, which only the schema documents, but the core semantics are covered.

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+resource ('Watch a sandbox file or directory for changes') and then enumerates the four sub-actions (start/read/list/stop) with their arguments and return shapes. An agent can distinguish this watch-based change-notification tool from the sibling runtime_sandboxes_files_read/write tools 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?

It clearly delineates when each action applies: start returns a watch plus cursor, read consumes the cursor, list enumerates watches, stop terminates one. It also notes access events are opt-in and that watches cap at 4 per sandbox. It never names an alternative tool or an explicit 'use this instead of X' condition, so it stops 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.

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

Annotations declare destructiveHint=true and idempotentHint=true, and the description reinforces this with "create or replace" and adds value beyond them: the write is atomic, parent directories are created automatically, content is interpreted as text unless encoding is base64, and there is a hard 1 MiB size ceiling. Atomicity, implicit directory creation, and the size cap are all behavioral facts an agent cannot get from the annotations.

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 padding. The core action and its atomic/replace semantics come first, the encoding rule and size limit follow, and the escalation path for large files closes it out. Everything 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 4-parameter mutation tool with no output schema and a sparse schema, the description covers the important behavior (atomicity, overwrite semantics, directory creation, size limit, encoding). It does not mention permission/auth requirements or what a successful call returns, but the absence of an output schema means return-value detail is not required.

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 only 25% (only `path` is documented in the schema). The description compensates for the undocumented `encoding` parameter by stating "content is text unless encoding is base64," which is genuinely useful. However, it says nothing about `id` (presumably the sandbox UUID) or about path constraints beyond what the schema already states, so the low coverage is only partially offset.

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+resource pair: "Create or replace a file in a sandbox," which tells an agent exactly what the tool does and implicitly separates it from the read/list/watch siblings. It does not explicitly name or contrast with any sibling (e.g. files_manage, files_read), so it stops short of full routing clarity.

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 an explicit fallback condition and alternative: files over 1 MiB should use the SDK or `npx withruntime sandboxes cp`. That is a clear when-to-use-something-else rule. It offers no guidance on when to prefer this over runtime_sandboxes_files_manage or other file siblings.

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

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.

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.

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.

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.

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.

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.

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description goes further by disclosing what data each aspect returns (reserved disk/price/charges, spending cap/retained-data deadline, latest recovery point), which helps the agent predict results. It still omits error/edge behavior and requires the id to resolve to an existing sandbox.

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?

It is compact and every clause is a value-to-output mapping that earns its place. The opening fragment 'One aspect of a sandbox.' is fairly empty, but the enum listing is dense and front-loaded after it.

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 read-only inspect tool with no output schema, the description is close to sufficient: it tells the agent exactly what each aspect yields. Remaining gaps are the meaning of `id` and any relation to sibling inspection tools, which are minor.

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 0%, so the description must carry the weight, and it fully explains all four values of the `what` enum, which is the enum parameter. The `id` parameter is left unexplained, presumably because it is self-evident, so it falls just short of full compensation.

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 enum breakdown ('storage: reserved disk, price and charges', 'lifetime: persistence, spending cap...') makes it clear the tool retrieves one facet of a sandbox's state, matching the inspect verb in the title. It does not, however, differentiate itself from siblings like runtime_sandboxes_metrics or runtime_sandboxes_list. The leading fragment 'One aspect of a sandbox' is weak but the enum glosses carry the meaning.

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 per-value descriptions implicitly guide which enum to pick for which question (want disk cost -> storage, want retention -> lifetime), but there is no explicit when-to-use versus alternatives or when-not-to-use guidance. An agent must infer that this is a scoped read compared to broader siblings.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description usefully goes beyond them by specifying exactly what restart destroys (variables) versus interrupt (keeps them). This is real behavioral context beyond the safety flags, though it doesn't cover permissions or the isolation model in more depth.

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, dense and front-loaded: the operation list leads, followed by the resource definition, then the restart/interrupt clarifications. 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 six-parameter destructive multi-action tool with no output schema, the description conveys the key lifecycle semantics an agent needs before invoking it. It omits return-value expectations and per-action parameter requirements, but the absence of an output schema and the strong action semantics keep it largely 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 adds meaning for the 'action' parameter's variants, explaining restarts/interrupts in terms of variable lifecycle, which the enum alone does not convey. Schema coverage is 67% and parameters like env, context, and idempotencyKey are documented in-schema, so the description mostly complements rather than compensates.

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 resource ('a sandbox's interpreter contexts') and enumerates the exact operations (list, create, restart, interrupt, remove), matching the action enum. It also distinguishes the resource from siblings like runtime_sandboxes_interpreter_run by defining a context as 'an isolated interpreter with its own variables.'

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 two semantic clauses tell the agent what restart and interrupt do, which implicitly guides action choice, but there is no explicit when-to-use guidance versus siblings such as interpreter_run, nor does it state which action requires which parameter (e.g., create needing language/context).

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

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

Annotations only declare write/destructive/open-world characteristics; the description adds substantial context beyond them: per-context state persistence (with the Go declaration caveat), the full return surface (stdout/stderr/results/errors with traceback), a 48 KiB size threshold that switches to file refs, and the timeout default.

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 action and scope, then behavior, then sibling routing, then a trailing default. Dense but every clause carries information; no filler sentences.

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 correctly takes on the burden of explaining return values and error shape, and it discloses the destructive nature beyond annotations. Remaining gap is the partial parameter coverage (43%), but the description is complete enough for correct invocation.

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 43%. The description compensates partially, adding the timeoutMs default (300000) and elaborating the persistence semantics of 'context', but idempotencyKey semantics live only in the schema and several parameters lack description-level detail. Baseline-to-marginal value given the coverage gap.

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 (Run) and resource (code in a stateful interpreter inside a sandbox), and explicitly distinguishes itself from the sibling runtime_sandboxes_exec ('runs shell commands'). An agent can tell them apart without opening either 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?

Names the alternative tool and its distinguishing purpose ('For data analysis, charts and quick computations; runtime_sandboxes_exec runs shell commands'), giving a clear selection condition. It lacks explicit when-not exclusions, but the routing guidance is strong.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavior beyond that: default page size of 50, the nextCursor/cursor round-trip, and the fact that stopped sandboxes still appear unless includeStopped is set. It does not describe the response shape, but the pagination contract is the important disclosure here.

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 dense sentence with the primary action and the most important constraint front-loaded. It is packed but nearly every clause carries information (filtering, pagination, stopped behavior, read-by-id). Slightly run-on, costing it a point.

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 supplies the return-value contract an agent needs: paginated results with a nextCursor. It covers filtering, defaults, pagination, and the read-by-id mode, and the annotations cover safety. Nothing essential to correct invocation 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 only 43%, so the description must compensate, and it does: it clarifies includeStopped semantics, the 'key:value' label filter syntax, the cursor round-trip, page size, and that id switches to single-resource read. State, limit bounds and name format are left to the schema, which covers them, so the gap is minor.

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?

Starts with a specific verb+resource ('List your sandboxes') and scopes it precisely with the live/stopped distinction. It also notes the dual read mode ('Give id to read one'), which is useful but slightly muddles whether this is a list tool or a getter. It does not name the sibling that handles single-resource reads (runtime_sandboxes_inspect).

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 through the includeStopped toggle and the state/name/label filters, giving the agent context for when to use it. However, it never explicitly routes to alternatives like runtime_sandboxes_inspect for a single sandbox, nor does it state exclusions. Adequate but leaves the sibling selection to inference.

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

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

Annotations only declare destructive/idempotent hints, but the description adds cost behavior (compute charges stop, paused storage billing), irreversible data loss for delete and switch-image, the 'snapshot first' mitigation, rollback on failure, live-vs-restart disk growth, and no_capacity outcomes. 'Waits until done' is disclosed too.

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?

It is front-loaded with the most-used actions and every clause carries information, but it reads as one dense run-on block with no line breaks and repeats several schema parameter descriptions (seconds, days, diskMiB, keep). Structure, not length, is the weakness.

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 an 11-action, 22-parameter mutation tool with nested policy and no output schema, the description covers destructive outcomes, cost implications, failure modes, and waiting behavior. An agent has what it needs to act safely.

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 already 86%, so the baseline is 3; the description adds value by tying parameters to actions and by clarifying interactions the schema states piecemeal (diskMiB alone growing live, restart=false refusing instead of restarting, seconds meaning extend vs. wake's time limit, keep only 'workspace'). Some parameter text is duplicated from the schema rather than adding new 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 enumerates concrete verbs and resources per action (stop, delete, pause, wake, extend, retention, persist, restart, switch-image, update, resize), so an agent knows this is the sandbox lifecycle-management tool. It does not name sibling tools (e.g. runtime_sandboxes_exec, runtime_sandboxes_create) to sharpen that boundary, keeping it 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?

Each action's consequence is stated in a way that directly selects between alternatives: stop keeps the disk for restart, pause keeps memory and disk, delete removes disk and paused memory for good, retention sets keep-days, persist prevents idle pausing. The agent can choose an action without guessing.

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

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

Annotations already declare openWorldHint=true and destructiveHint=true, but the description adds real behavioral value beyond them: secrets are resolved by the egress proxy so "a server never holds the value", and "servers keep to the sandbox's network rules". It also distinguishes expiring vs permanent (public) URLs. It stops short of what stop actually tears down.

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?

Dense but front-loaded: the core purpose leads, then actions are covered in a compact sequence of clauses. The semicolon-heavy packing is efficient, though the final sentence bundles two unrelated facts (secret resolution and network rules) somewhat awkwardly.

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 multi-action tool with six parameters and no output schema, the description covers the return shape of start and get but gives little on catalog or stop, and omits the semantics of replace and port entirely. It is adequate to invoke the common paths but leaves several parameters and one action under-specified.

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 only 17%, so the description must carry the load; it clarifies the action dimension and the meaning of public (URLs that never expire), but leaves replace, port, and options unspecified in both schema and prose. The secrets mapping it explains is already documented in the schema, so it adds limited net value.

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?

Starts with a concrete verb+resource ("Run well-known MCP servers in a sandbox") and then enumerates the four actions (catalog/start/get/stop), so an agent can tell exactly what this does and distinguish it from runtime_sandboxes_create and runtime_sandboxes_exec. The catalog examples (GitHub, Postgres, Playwright, filesystem, fetch, git, Notion) make the scope 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?

The description gives per-action context (catalog to list, start to provision, get to inspect, stop to end) and notes that public URLs are configured "once", which is genuine routing guidance. It also points the secret flow at the sibling runtime_secrets. What it lacks is an explicit when-not or a contrast with alternatives like runtime_sandboxes_exec for custom servers.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the default range when omitted (1h), the meaning of 'Waiting' as measured wall-time percentage, and the null semantics where the host lacked complete same-run readings. Return shape and pagination/aggregation behavior 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?

A single dense sentence that front-loads the metric list and the range option, then appends the two caveats (default range, waiting/null semantics). It is efficient, though the run-on structure makes the trailing caveats easy to skim past.

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 does the work of enumerating return content and the 'latest reading' inclusion plus null semantics. For a read-only two-parameter metrics tool with annotations covering safety, this is close to complete; only the response structure/series format and the id target are left implicit.

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 must carry parameter meaning. It fully documents the range parameter including the default ('1h when omitted'), which the schema does not encode. The id parameter is only implied ('A sandbox's...') and never states that it is the sandbox UUID required to identify the target.

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 enumerates the specific resource (a sandbox) and the exact measured quantities returned (CPU percent/cores, resident memory, CPU wait, memory stalls, disk use, disk I/O, network per second). It is unambiguous what the tool returns, though it omits an explicit verb like 'get' and does not name the sibling it differs from (e.g. runtime_sandboxes_inspect).

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 states an intended purpose ('to size a sandbox or find what drove a bill'), which implies when to reach for it. However, it names no alternatives and gives no when-not guidance, so an agent must still infer how this differs from runtime_sandboxes_inspect or runtime_sandboxes_list.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds real behavioral context: 'secret keeps the key out of the sandbox' (credential handling via the egress proxy) and 'What was written stays in the bucket' (unmount does not delete remote data). These are useful disclosures beyond the structured fields, though permission/rate-limit details are absent.

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 resource statement, then compact per-action signatures. Dense and mostly waste-free, though the parentheses-style signatures are terse enough that some clarity is traded for brevity.

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 an 11-parameter, multi-action tool with no output schema, the description covers all three actions and even summarizes the list() return ('each mount and whether it is mounted now'). Combined with 82% schema coverage, it is largely complete, with only cross-tool guidance 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 82%, so the schema already documents nearly all parameters including endpoint, provider enum, and secret. The description largely restates the mount parameter list with optional markers, adding little beyond what the schema provides; baseline 3 applies when the schema does the heavy lifting.

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 resource (S3/R2/GCS bucket mounts in a running sandbox) and decomposes the tool into three clearly labeled operations (mount/list/unmount) with signatures. It is easily distinguished from siblings like runtime_volumes or runtime_sandboxes_files_manage.

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?

Each action's purpose is spelled out via its signature, giving clear context for when each applies. However, it never states when to prefer this over alternatives such as runtime_volumes or the files tools, so the routing decision is left implicit.

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

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

Annotations already flag this as destructive, non-read-only and open-world, and the description adds rich behavioral detail beyond them: changes apply immediately including to already-open connections, allow/deny narrow every port while connect adds host:port pairs, paid orgs reach every port versus ports 80/443 without credit, and private addresses are always refused.

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?

Dense but well organized, front-loading the resource and then splitting into get/set signatures with the rules that follow. Sentences are long and somewhat run-on, but nearly every clause adds usable information rather than 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?

With no output schema, the description correctly explains what get returns (rules, host version enforcement, host:port reach), and for the mutation path it covers the scope of effect. Per-permission error behavior and prerequisites are not stated, but for a two-action rules tool this is largely 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?

Top-level schema coverage is 0% (only the array item strings are documented), so the description carries real weight: it explains id, internet's interaction with the org's paid status, and the distinct semantics of allow/deny (narrow every port) versus connect (adds host:port). It adds meaning beyond the schema, though action's enum itself is only shown by example rather than described.

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 the resource (a sandbox's internet access and its allow/deny/connect rules) and cleanly separates the two operations it exposes, get(id) and set(id, internet, allow?, deny?, connect?). Unlike the sibling network tools (private, upstream_proxy, wireguard), it is clearly scoped to a single sandbox's egress rules, so an agent can route correctly.

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 context for each action: get retrieves the rules and enforcement/reach status, set applies changes. However, it never explicitly contrasts this tool with sibling network tools (runtime_networks_private, runtime_networks_upstream_proxy), so an agent must infer that this is the sandbox-level variant.

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

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

Goes well beyond the annotations (destructiveHint=true, openWorldHint=true) by disclosing that private previews need the x-runtime-preview-token header, that public visibility requires a kept top-up and shows a one-time browser warning, that WebSockets work, that create is idempotent per port, that rotate invalidates old tokens, and that session tokens are shown only once. These are the exact behavioral facts an agent needs for a multi-action mutation surface.

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 resource definition before the per-action breakdown, and every clause maps to a distinct action or constraint, so little is wasted. The dense run-on packing of all seven actions into one paragraph makes it harder to scan than a bulleted layout would be.

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 carries the return burden and does describe what list returns (ports plus a fresh private token) and that session_create's token is shown once. All seven actions and the key visibility/embedding behaviors are covered, leaving only minor gaps such as the meaning of origins/sessionSeconds.

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 50% (port, ttlSeconds, expiresAt, visibility, embedOrigins documented in-schema). The description reinforces visibility/embedOrigins semantics and implies a day-long default ttl, but origins, sessionSeconds and sessionId are only named in the action signatures, not explained, so the description does not fully compensate for the coverage gap.

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?

Opens with a concrete resource and format ('HTTPS addresses for ports inside a sandbox, https://<port>-<sandbox>.<domain>/') and then names a specific verb for every one of the seven actions (create, list, rotate, delete, session_create, session_list, session_revoke). The purpose is unmistakable, though it never explicitly distinguishes itself from adjacent siblings like runtime_ports or runtime_sandboxes_browser.

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?

Each action carries usage context: 'rotate... as when a link leaked', 'delete: Stop sharing the port', 'list: Each shared port, with a fresh day-long token if private'. This tells the agent when each action applies, but there is no explicit when-not guidance or named alternative tools for the cases where a sibling (e.g. runtime_ports) would be the better choice.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=true. The description adds behavior beyond that: signal defaults to SIGTERM and SIGKILL terminates the entire process tree, the long-poll nature of waitMs (holds the call up to 8000ms), and the stdinMode/pty prerequisite for write. It still omits what 'list' returns or the meaning of state/exitCode.

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?

Dense but organized action-by-action with the critical scoping fact (process must come from exec background:true) front-loaded. Every clause carries information; the only nit is that the single long sentence is somewhat run-on and could be split for scannability.

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 an 8-parameter, multi-mode tool with no output schema, the description covers the action semantics well but is incomplete: eof and processId are never mentioned, the id vs processId relationship is unexplained, and the read-state/exitCode values are named without defining them.

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 13% (8 params, essentially one described), so the description must carry the load. It does add real meaning for cursor ('pass the returned nextCursor next time'), waitMs ('up to 8000 holds the call until there is output'), data and signal (SIGTERM default, SIGKILL for the whole tree), but leaves eof, processId and the required id/processId distinction completely unexplained.

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 ('Work with a process started by runtime_sandboxes_exec background: true') and enumerates the exact operations (read, write, signal, list). It explicitly ties itself to the sibling runtime_sandboxes_exec, so an agent can tell which tool starts a process and which one follows it.

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 each action and a precondition for write ('the process needs stdinMode pipe or a pty'), plus the routing hint that the process must have been started with exec background: true. It lacks explicit when-not guidance or a direct alternative comparison, but the usage context is solid.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered, but the description goes beyond them: down 'leaves the tailnet at once' (immediate destructive effect) and authKeySecret warns to use an ephemeral key because 'a reusable one lets the sandbox log in again by itself after a long pause' — a real persistence/security trait. Missing only permission/reversibility detail.

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 a one-sentence summary of the resource, then a compact per-action map. Minor inefficiency from the 'Paid sandboxes.' fragment and some phrasing overlap, but no filler and every clause carries operational meaning.

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 multiplexed, destructive, no-output-schema tool this is close to sufficient: each action's effect, the key mechanism, and the immediate leave-on-down behavior are stated. It could say a bit more about what status returns and any permission requirements, but nothing critical for correct invocation 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?

Schema coverage is 60% and the description adds meaning the flat schema lacks by mapping parameters to actions — up(id, authKeySecret?, hostname?, tags?) versus status(id) and down(id). It also clarifies authKeySecret names a job secret and carries the ephemeral-key caveat, exceeding the schema's own text.

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 resource (a sandbox's Tailscale network membership) and enumerates the three operations: join with an auth key, view tailnet addresses, or remove the machine. Each action verb is explicit, so an agent can tell this apart from generic network siblings like runtime_sandboxes_network or runtime_networks_wireguard 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?

The per-action breakdown (up/status/down) implies when each sub-operation applies, and 'Paid sandboxes' is a useful eligibility constraint for up. However, there is no explicit when-not guidance, no prerequisites, and no routing to alternative network tools for an agent unsure whether this is the right tool.

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

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

Annotations only say destructive/openWorld/readOnly false; the description carries the real burden and does so richly: values are never returned, delete does not revoke the provider token, reveal needs its own permission, versioning and expectedVersion 409 behavior, exposed requires exec on each write, and the exact permission model (storing key, named agents, person) for list/bind/reveal/rotate/delete. It is consistent with destructiveHint.

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 content is mostly relevant and front-loads the core concept, but it is delivered as a single dense run-on paragraph with no line breaks or per-action structure, making it hard to scan for 11 actions and 20 parameters. It is adequately sized for the complexity but poorly structured.

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 still explains what list and get return (names, kind, version, hosts, header, placeholder; never values) and how pagination works via next/after. Combined with coverage of permissions, version conflicts, and the jobs_* lifecycle, it is sufficient for an agent to invoke 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 coverage is already 85%, but the description adds the crucial action-to-parameter mapping (e.g. set(name, value, hosts?, header?, format?, rules?, only?, githubApp?, git?, api?, env?, exposed?, expectedVersion?)) and explains cross-field constraints like header/format pairing and exposed requiring sandboxes or apps rather than labels. This is meaningfully more than the schema alone, though several parameter details are duplicated from 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 states the resource (secrets/API keys), the core mechanism (placeholder in sandbox, egress proxy injects the value on HTTPS to named hosts), and then enumerates every action (set, list, get, delete, jobs_*) with a specific verb. It explicitly distinguishes the jobs_* family and points to runtime_jobs for binding, so an agent can tell it apart from siblings like runtime_sandboxes or runtime_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?

It gives concrete usage context per action (e.g. delete does not revoke at the provider, reveal requires its own permission so 'prefer binding', share replaces the agents named) and names an alternative workflow via runtime_jobs create input.secrets. It lacks a broad 'use this when / not when' exclusion statement across the whole tool, so not a 5.

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

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

Goes well beyond the annotations (readOnly=false, destructive=true, openWorld=false): create momentarily pauses a running sandbox and wakes it, the volume restriction, the non-retryable fork_unavailable state, delete freeing storage while derived sandboxes keep running, and update leaving captured bytes and billing unchanged. This is the kind of side-effect disclosure a mutation tool 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?

Front-loads the resource definition, then structures the rest per action with parenthesized signatures, which scans well for a five-action tool. It is dense but nearly every clause carries information (constraints, side effects, pagination). Slightly verbose in the retention explanation but nothing wasted.

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 12-parameter, no-output-schema, destructive multi-action tool, the description covers every action, the key constraint, pagination, update semantics and deletion consequences, and even sketches get's return fields. Minor gaps remain, such as the meaning of the state enum values (capturing/ready/failed/deleting), but it is close to 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 coverage is 58%, and the description compensates by mapping parameters to actions and adding semantics the schema omits: "omitted fields stay unchanged. Null clears the name" for update, and "Pass nextCursor back as cursor" for list pagination. mode, limit, ifLabels and retentionDays are largely already covered by the schema, so it does not fully carry the parameter burden, but it adds real value.

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?

Opens with a precise verb/resource definition ("Kept copies of a paused sandbox's files, memory and processes, to start copies from") and then enumerates each action with its arguments. It distinguishes itself from siblings by naming images as the alternative for preinstalling dependencies. An agent can tell exactly what this tool does and each sub-action's scope.

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 concrete when/when-not guidance: volumes cannot be snapshotted and images are the route for preinstalled dependencies; fork_unavailable means snapshots are disabled and must not be retried. It also clarifies that delete leaves sandboxes started from the snapshot running. It lacks a broad routing statement against the many other runtime_* siblings, but the key exclusions and alternatives are present.

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

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

With annotations covering the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), the description adds real context beyond them: human escalation is possible, replies arrive within about a minute while status is 'working', and proposed actions are gated behind an id+hash approval pair. It does not say what happens to a conversation if abandoned or whether approvals are single-use.

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 what the tool is before the per-action mechanics, and every sentence carries information. The compressed semicolon-clause style makes the message/read split slightly harder to parse than it needs to be, but 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 6-parameter tool with no output schema, the description still explains the read return shape (status, newest reply, actions awaiting approval) and the full approval lifecycle. Missing only edge behavior such as what an expired or unknown conversationId does.

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 only 17%, so the description must compensate, and it largely does: conversationId is sourced ('from the returned conversationId'), message is the entry point, and the approveActionId/approveInputHash pairing plus denyActionId are explained as an approve/deny mechanic. The 'message' vs 'read' action enum values are not individually defined, which is the residual gap.

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?

Names a specific resource (Runtime's support agent) and the concrete situations it handles: errors, a sandbox that will not start, billing, how-to, plus escalation to a person. This is clearly distinguishable from the surrounding runtime_sandbox_*, runtime_billing-adjacent and docs 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 an actionable flow: 'Start with message; continue with the returned conversationId', and states the precondition for running a proposed action (approveActionId together with its approveInputHash) versus declining it (denyActionId). It does not compare against siblings such as runtime_docs_read for how-to questions, which is the one obvious alternative left unaddressed.

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