Runtime Cloud

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 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?

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 give the safety profile (destructiveHint=true, readOnlyHint=false), and the description adds meaningful context beyond that: delete removes a version and its tags but sandboxes already started keep running; tag moves a tag rather than creating a new version. This is exactly the kind of side-effect disclosure the agent needs and couldn't infer from annotations alone.

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 the four actions are laid out compactly with their parameter signatures. It is dense but every clause maps to an action or parameter, so little is wasted for a 4-action, 10-parameter tool.

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 and 10 parameters, the description does the needed work: it sketches what list and get return (newest-first images, state/version/tags/size/error/log lines) and covers the destructive semantics of tag and delete. It stops short of full return-shape or pagination-limit detail, but is complete enough to call 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 40%, so the description must compensate, and it does: it documents which parameters belong to each action (list: cursor/limit/state/name, get: id/logsAfter, tag: id/tag/remove), explains cursor round-tripping via nextCursor, and clarifies remove=true detaches a tag. Only idempotencyKey handling is left to the schema, which already documents it.

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 set of verbs (list, read, tag, delete) on a specific resource (the images sandboxes start from), and explicitly names the sibling responsible for creation: 'runtime_images_build makes them'. An agent can distinguish this from runtime_images_build and runtime_images_registries 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?

Each action is scoped with its own signature and behavior, and runtime_images_build is named as the alternative for building. It implies when each action applies (list to browse, get for a version's state/logs, tag to move a pointer, delete to remove) but does not state explicit when-not-to-use conditions or route to other siblings besides build.

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?

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 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 safety profile is carried by structured data. The description adds genuine behavioral context beyond that: header values 'are never shown back' (a write-only/redaction trait) and the default signals behavior. It does not explain what delete destroys or the auth specifics, so it is adequate but not rich.

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

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

Two sentences, front-loaded with what the resource is, then the create and flush specifics. Dense but efficient, and each clause carries information. Slightly terse given the tool's complexity.

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 six-action, seven-parameter management tool with no output schema and no annotation coverage of the CRUD lifecycle. The description addresses only create and flush and omits list/get/update/delete entirely, so it is not complete enough for an agent to safely operate all actions.

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 57%, so the schema does part of the work but the description should compensate more. It adds meaning for endpoint (OTLP base URL), headers, and the 'both by default' behavior for signals, but says nothing about id, enabled, action semantics, or idempotencyKey. Marginal value over the already-documented 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 a specific resource (OpenTelemetry exports pushing sandbox OTLP logs and CPU/memory metrics) and explains the create/flush semantics. However, it frames the tool only around create and flush, leaving the multiplexed list/get/update/delete actions of the action enum effectively unstated, so an agent cannot fully tell what the tool manages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when create is used (takes endpoint, headers, signals) and when flush is used ('flush pushes now'), but gives no guidance for list/get/update/delete actions, no when-not conditions, and no alternatives among siblings. Usage is largely left to inference from the action enum.

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?

Annotations (destructiveHint=true, openWorldHint=true, readOnlyHint=false) set the safety profile, and the description adds real behavioral context beyond them: first start installs Chromium and takes about a minute, stop ends the browser, get issues a fresh cdpUrl, and the in-sandbox endpoint is http://127.0.0.1:9222. 'stop ends it' also concretizes what the destructive hint means in practice.

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, then action semantics, then the install-latency caveat and the internal address. It is dense and telegraphic, with essentially no filler, though the run-on grouping of actions makes it slightly harder to scan than a bulleted breakdown 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 return values (start returns cdpUrl, get returns state plus fresh cdpUrl) and the first-call install delay, which is exactly what an agent needs before invoking. The unqualified 'id' parameter is the remaining incompleteness.

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%; the description compensates by explaining the action enum values and the headless flag's real-world effect (visible window on the sandbox desktop with live view), while width/height retain their schema defaults. The main gap is that 'id' is never qualified as the sandbox identifier, leaving one required parameter unanchored.

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 concrete verb+resource ('Chromium in a sandbox for browsing agents') and then enumerates the three actions (start/get/stop) with what each does, so an agent can tell this apart from siblings like runtime_sandboxes_exec or runtime_sandboxes_desktop_screenshot 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?

Clearly signals the use case: obtaining a cdpUrl to hand to Playwright connectOverCDP, Puppeteer, browser-use or Stagehand, plus when to use headless=false (live desktop view). It lacks any explicit when-not or comparison against the desktop_* siblings, so it's context-rich but not fully 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 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?

Annotations declare destructive/openWorld/not-readOnly, and the description adds substantial non-obvious behavior: the 16,000-char truncation rule with outputCut and file fallback, waiting on a starting sandbox, timeout returning timedOut with partial output, and background returning a processId. It also discloses the execution identity (sandbox user with passwordless sudo, HOME=/workspace) — exactly the context that matters for a destructive exec 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?

Front-loaded with the core action, then dense behavior notes with no filler — each sentence carries distinct information (truncation, waiting, timeout, background, privileges, env). Slightly run-on and long, but nothing is redundant or 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 takes on the return-value burden and covers it: exitCode, stdout, stderr, timedOut, processId, outputCut. Combined with truncation, timeout and background semantics, an agent has everything needed to invoke and interpret this 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 90%, so the schema carries most parameter documentation and baseline 3 applies. The description still adds cross-parameter meaning the schema doesn't: env keeps secrets off the command line, and background yields a processId consumed by runtime_sandboxes_process. This is value beyond the field-level 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?

States a specific verb and resource — run a shell command or argv in a sandbox — and immediately names the sibling that handles the background case (runtime_sandboxes_process). An agent can distinguish this from runtime_sandboxes_interpreter_run or runtime_sandboxes_process 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?

Gives clear context for the background flag ('servers, watchers and interactive programs') and routes to the controlling sibling tool. It also tells the agent it can wait on a starting sandbox. It lacks an explicit when-not clause (e.g. foreground vs interpreter_run), but the conditional guidance is well above average.

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?

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/read-only/idempotent flags, and the description adds substantial context on top: which state is destroyed vs retained per action, billing implications (compute charges, paused storage), that snapshots survive delete, that switch-image is transactional and rolls back on failure, and that env values are never shown again. This is rich disclosure beyond 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?

The 'action: effect' prefix pattern imposes order on a dense multi-action tool, and little is wasted given ten behaviors must be covered. It is a single long run-on block rather than clearly delimited sections, which slightly hurts 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?

For a 14-parameter, ten-action tool with nested objects and no output schema, the description covers each action's side effects and the wait/idempotency mechanics, which is largely enough. It does not hint at return shape or failure modes, a minor gap given the absence of an output schema.

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 79%, and the description maps parameters to the actions that consume them (seconds for wake vs extend, days for retention, policy for persist, env/name/labels/autoWake/idlePauseSeconds for update), clarifying cross-action ambiguity the flat schema does not. It adds meaning over the schema but does not fill every remaining 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?

Each of the ten actions is stated with a concrete verb and its resource effect (stop keeps disk, delete revokes previews and ports, switch-image keeps only /workspace), so the tool's scope is unambiguous. It never names the sibling that handles the adjacent task (create/fork/inspect), so differentiation from those is left implicit rather than explicit.

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-by-action semantics effectively encode when to choose one over another: pause keeps memory and disk with no compute charge, stop keeps only disk as billed paused storage, delete is permanent. It stops short of explicit when-not rules or naming alternative tools, so the agent must infer selection from the contrasts.

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/open-world/non-read-only, so the bar is lowered, but the description adds real behavior: start returns a URL plus Authorization header, secret settings map to Runtime secrets so the sandbox never holds the raw value, and servers honor sandbox network rules. This is useful beyond 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?

The purpose leads, followed by a compact per-action breakdown and a closing note on secrets and networking. It is dense but every sentence contributes, and the most important information is 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?

With no output schema, the description helpfully summarizes what start and get return and how secrets resolve. It is fairly complete for a multi-action tool, though it never addresses the undocumented port/replace parameters or the constraints of the nested servers configuration.

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 20%, so the description carries the compensation burden. It explains the `secrets` placeholder/egress-proxy semantics and implies `id` usage, but `port`, `replace`, and `options` are left completely undocumented in both schema and description, leaving significant gaps.

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: "Run well-known MCP servers in a sandbox," and then decomposes that into the four concrete operations (catalog/start/get/stop). It is clearly distinct from siblings like runtime_sandboxes_exec or runtime_sandboxes_create, though it does not name them to sharpen the contrast.

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 context: catalog lists servers and their hosts, start returns URLs and Authorization headers, get shows state and fresh URLs, stop ends them. That effectively guides action selection, but there is no explicit when-not or alternative-tool routing (e.g. vs runtime_sandboxes_create).

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, destructiveHint=false, and closed-world, so safety is covered. The description adds meaningful behavior: the default range (1h when omitted), inclusion of a latest reading, the definition of waiting as measured wall-time percentage, and the null case when the host lacks complete same-run readings.

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 what is measured before the range and use cases. It is slightly run-on, but nearly 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 no output schema, the description does the work of describing returned fields (CPU, memory, wait, stalls, latest reading) and the null condition. Combined with annotations covering the safety profile, an agent has enough to call it correctly; only the id parameter remains purely schema-defined.

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 load. It documents the range enum values and the 1h default (which the schema does not state), but says nothing about the required id beyond what the schema's uuid format implies. 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?

The description names the exact resource (a sandbox's measured CPU as percent of vCPUs and cores, resident memory, CPU wait, memory stalls) and the retrieval granularity. It is clearly distinguishable from siblings like runtime_sandboxes_inspect or runtime_sandboxes_process, which are not metrics-focused.

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 three concrete use cases: sizing a sandbox, telling whether a process is busy or waiting, and finding what drove a bill. No alternatives are named explicitly, so it stops short of a 5, but the when-to-use 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 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?

Beyond the annotations (destructiveHint=true, openWorldHint=true), the description discloses the private token header requirement, the public-visibility top-up prerequisite and one-time browser warning, WebSocket support, idempotency per port, and that rotate invalidates old tokens while session tokens are shown once. These are exactly the operationally risky behaviours an agent needs before calling a destructive, open-world 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?

Front-loaded with the address format, then one clause per action, with no filler sentences. It is a single dense run-on paragraph with seven embedded actions, which hurts scanability but every clause earns its place.

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

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

For a 10-parameter, no-output-schema tool this covers the action set, token lifetimes, embedding restrictions and partial return semantics (list 'with a fresh token', session_list 'without tokens'). Gaps remain on the 'origins' parameter and on how a session token is subsequently used.

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 largely restates schema-documented fields (visibility default/semantics, expiresAt, ttlSeconds, embedOrigins). It does add the header name and urlWithToken alternative for private previews, but it leaves 'origins' (session_create) unexplained, which is one of the undocumented parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening line states a specific resource ('HTTPS addresses for ports inside a sandbox') and the per-action clauses make clear this tool manages preview exposure and browser sessions rather than listing ports. It never names the obvious siblings (runtime_ports, runtime_sandboxes_network) to distinguish scope, which keeps it from 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 carries its own reason for use – rotate 'as when a link leaked', delete to 'stop sharing the port', session_create for 'a web page's token for this sandbox's commands, files and previews'. What is missing is tool-level routing: nothing tells the agent when to reach for this tool instead of runtime_ports or runtime_sandboxes_network.

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?

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.

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

Adds substantial behavior beyond the annotations: delete 'refused while a sandbox holds it' and destroys 'all its data' while backups persist for their retention; one sandbox mounts read-write at a time; daily off-host backup unless turned off; backedUp true only once a checked copy is off host. These are exactly the destructive/prerequisite details an agent needs and annotations alone do not carry.

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 structured action-by-action in a compact form with no filler sentences. The action(...): value notation is dense enough to occasionally slow parsing, but every clause earns its place.

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

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

No output schema exists, so the description appropriately describes returns: get yields 'state, size, space used, attachments and backups', list returns 'each as get gives it' newest-first, and backedUp is explained. Missing only coverage of the state enum and idempotencyKey retry semantics for a 10-parameter 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?

With only 30% schema description coverage, the description carries the load and does so for the key params: sizeMiB and fromBackup semantics, name/region on create, cursor/nextCursor pagination, and the id used by get/delete. Gaps remain for state (enum values), idempotencyKey, and limit despite their importance for list.

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 the resource concretely ('persistent disks that outlive sandboxes') and enumerates the four supported actions (create/list/get/delete) with per-action semantics. It is clear what the tool does, but it never names or routes to the sibling runtime_volumes_backup even though backups feature heavily in the text, so sibling differentiation is incomplete.

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 actionable context per action: provide 'sizeMiB, or fromBackup to restore one', 'Pass nextCursor back as cursor', and notes creation-side attachment via 'volumes: [{volumeId, path}]' on sandbox create. It stops short of stating when this tool should be preferred over runtime_volumes_backup or the sandbox mount 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 readOnlyHint=false, so the safety profile is partly covered. The description adds materially: crash-consistency, storage location off-host, the default 7-day retention, an explicit latency note (waits up to a minute), and that delete removes both the metadata and the stored copy. It does not distinguish which of the five actions are safe reads versus mutations, a notable gap for a multi-action tool, keeping it at 4.

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 one-line scope statement is front-loaded, followed by a compact per-action breakdown that mirrors the enum. The telegraphic style (e.g. 'kept retentionDays', 'each as get gives it') packs a lot in without filler, though it demands careful reading and the sentences are dense rather than crisp.

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 so — get returns state, size, stored bytes and expiry, and list returns items shaped the same way. All five actions and most parameters are addressed. Missing pieces are minor: the destructive/read distinction per action and limit/state semantics, both partly covered by the schema.

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 40%, so the description must compensate, and it largely does: it explains name?, retentionDays (defaults to the volume's retention, 7), cursor usage (pass nextCursor back), volumeId scoping, daily on/off, and what id identifies. It adds real meaning over the bare schema. limit is left to the schema and state is only implied as a filter, which prevents 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?

The opening states a specific resource and scope — crash-consistent backups of a volume kept off its host — and enumerates all five actions (create, list, get, policy, delete) with what each does. It also distinguishes itself from the runtime_volumes sibling by naming the restore path (runtime_volumes action create with fromBackup), so an agent can route correctly 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?

Each action carries contextual guidance: create for an immediate backup (waits up to a minute), list for browsing your backups newest-first, policy for enabling/disabling daily backups, and delete for removal. The restore alternative is explicitly named and routed to runtime_volumes. It lacks explicit when-not guidance or prerequisites (e.g. the volume must exist), 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.