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

With no annotations, the description carries the full burden and does so: it discloses that the container is recreated, that a running sandbox restarts with apps unreachable for a few seconds, that asleep and deep-sleep sandboxes behave differently, and that a missing host folder is a Docker error rather than an auto-created folder. It also states the ownership outcome for the sandbox owner.

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 and access constraint, then side effects and error behavior. It is dense but nearly every sentence adds operational value; the parenthetical about the sandbox's own Docker is slightly tangential.

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 four-parameter mutation with no annotations and no output schema, the description covers access prerequisites, side effects, restart semantics, and error behavior. It omits what the call returns and what readonly actually controls, which keeps it short of 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 50%: host and target are already documented in the schema, and the description largely restates them. The required 'name' parameter and the 'readonly' flag go unexplained in both schema and description, so the description does not 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 ('Mount a host folder into the sandbox') and the sibling remove_sandbox_mount makes the direction unambiguous. An agent knows exactly what changes and on which resource.

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

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

Explicitly gates usage: 'Admin only, with HOST_MOUNT_ROOTS set' and notes the host path must be at or under one of those roots. It does not compare against other path-exposing siblings such as project_dir_link, so it falls short of full when/when-not guidance.

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

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

No annotations are present, so the description carries the full behavioral burden. It does disclose a significant trait the schema cannot express: the key grants root access across all sandboxes. It stops short of stating required permissions/auth scope, what happens on duplicate keys, or whether the operation is idempotent.

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

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

Two short clauses, front-loaded with the action and its consequence. The trailing 'HTTP POST /ssh-keys' is endpoint leakage that adds little for an agent, though it does not harm readability.

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

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

For a mutation tool with no annotations and no output schema, the description covers purpose and effect but omits permissions needed, duplicate/replace behavior, and what the response returns. Adequate but with clear gaps for a write operation with security impact.

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%: `name` is described in the schema ('Defaults to the key's comment') and `key` carries a format example, so the structured fields do most of the work. The description only says it is a public key, adding no format, encoding, or constraint detail beyond the schema.

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

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

States a specific verb and resource ('Add an SSH public key') and immediately qualifies the effect: root SSH access to all sandboxes. That scope statement cleanly separates it from siblings like generate_sandbox_ssh_key or get_sandbox_ssh_key, which operate on a single sandbox's key.

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 use case is implied by 'it lets you into all your sandboxes with SSH as root,' so an agent can infer when this is wanted. However, there is no explicit when-to-use vs when-not guidance and no mention of the alternatives (e.g. generate_sandbox_ssh_key for a per-sandbox key), so half the routing work is left 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?

Goes well past destructiveHint=true by naming exactly what is destroyed (containers, volumes, sandbox directory), what is preserved and where (tar.gz volumes and config under opt/archive/<owner>/), and the all-or-nothing guarantee 'Nothing is removed if archiving fails'. The HTTP verb/path is a bonus 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?

Three short sentences, front-loaded with the action and its destructive outcome, then the preservation path, then the failure guarantee. No filler and nothing repeated from the schema or annotations.

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

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

For a one-parameter destructive tool with no output schema, the description covers destruction scope, archive destination, and failure atomicity. Only minor gaps remain, such as the return value or whether archives can later be restored.

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?

One parameter at 0% schema description coverage, so the description must carry it. The HTTP template DELETE /sandboxes/{name} implicitly identifies the argument as the sandbox name, but nothing clarifies naming rules, whether it accepts an id, or validation behavior.

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 and then spells out the full operation sequence (stop, tar.gz volumes + config to opt/archive/<owner>/, remove containers/volumes/directory). The destructive end-state is unambiguous, though it never names the sibling delete_sandbox it most needs to be distinguished from.

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 'archives first, removes second' framing implies you should use this instead of a plain delete when the data matters, and the sibling list does contain delete_sandbox. But the description never states that comparison or any prerequisite (ownership/permissions) explicitly, so routing is left 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?

No annotations are provided, so the description must carry the full behavioral burden. It only says this creates a sandbox via POST; it does not disclose permissions, quota/limit behavior, side effects, defaults applied from templates, or what the response contains.

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

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

The description is very short and front-loaded with the main action. However, the second line is mostly endpoint metadata and does not contribute much additional understanding for an agent.

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 mutation tool with no annotations and no output schema, the description is too thin. The schema documents most parameters well, but the description does not explain creation behavior, return value, or important side effects an agent should know before invoking it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is high at 90%, with detailed descriptions for most parameters such as cpus, memory, compose, runtime, and sleep settings. The tool description itself adds no parameter semantics, so the baseline of 3 is appropriate.

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

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

The description names a specific verb and resource ("Create sandbox") and even maps it to the HTTP endpoint. It is clear what the tool does, but it does not distinguish it from related sibling tools such as create_sandbox_folder or create_token.

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

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

The description gives no guidance on when to use this tool versus alternatives, nor does it state prerequisites, constraints, or when not to use it. The HTTP method/endpoint is implementation detail rather than usage 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?

There are no annotations, so the description carries the full burden, and it discloses little beyond the action itself. It does note parent directories are created implicitly (a genuinely useful trait), but says nothing about behavior when the path already exists, idempotency, failure modes, or required auth.

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 prose sentence is short and front-loaded, which is good. However, it is punctuated as a run-on with the raw HTTP route appended on a second line, which adds mapping value but also reads as residue from API docs rather than agent-facing guidance.

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

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

For a mutation tool with no annotations, no output schema, and an undocumented required parameter, the description is thin. It never says what is returned, whether the call is idempotent, or what error to expect if the folder already exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 50%: 'path' has an example (/srv/data) but 'name' is undocumented in both schema and description. The phrase 'the sandbox's files' weakly implies 'name' is the sandbox identifier, but this is never stated, so the description does not 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 ('Create a folder (and its parents) in the sandbox's files'), so the action is unambiguous. It does not, however, name or contrast with the nearest sibling (write_sandbox_file) or clarify scope beyond 'the sandbox's files'.

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

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

No guidance on when to use this versus write_sandbox_file or list_sandbox_files, and no mention of prerequisites such as the sandbox needing to exist or be awake. Usage must be inferred entirely from the name.

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?

No annotations exist, so the description carries the full load. "Shown once" is a genuinely valuable disclosure (the secret is not retrievable later) and the POST endpoint signals a mutating call, but it omits permissions granted, auth requirements, and whether creation is revocable.

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, front-loaded fragments with no waste. The bare "HTTP POST /tokens" line adds little for an agent but is harmless and confirms the operation is a write.

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 annotations, no output schema, and 3 params at low description coverage — this is a case where the description needed to explain the returned token shape and expiry behavior, and it does not. Only the "shown once" warning fills part of the 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 only 33% — `name` and `expires_in` are undocumented beyond an example and an enum/default, and the description adds nothing about them. Only `sandbox` carries a schema description, so the description should have compensated for the expiry and naming semantics but does not.

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

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

Specific verb+resource ("Create a personal access token") that any agent can map directly. It is clearly different in kind from the sibling list_tokens and revoke_token, though it never names them explicitly.

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

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

The description gives no when-to-use guidance, no prerequisites (auth, which account the token belongs to), and no mention of alternatives such as rotating vs. creating. The agent must infer everything from the name alone.

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 no annotations, the description carries the full burden and does disclose real behavior: containers and network go down, data is retained, and 'the next request or start rebuilds it'. That recovery semantics is genuinely useful. It still omits auth/permission needs, idempotency, and effect on runtime state, keeping it short of a 5.

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

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

Two compact lines, front-loaded with the action and its effect. The raw HTTP route is somewhat redundant with the tool name but is harmless and low-cost.

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

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

For a single-parameter mutation with no annotations or output schema, the description gives the essential state transition and rebuild behavior, which is what an agent needs to act. Only minor gaps remain (permissions, return value), so it is nearly complete for this complexity level.

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% and the single 'name' property has no description. The HTTP path segment '{name}' weakly implies a sandbox identifier, but the description adds no format, source, or validation meaning beyond that, so it does not 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?

Names a specific verb+resource ('Put a sandbox into deep sleep now') and the parenthetical clarifies the resulting state ('containers and network down, data kept'). However, it never distinguishes 'deep sleep' from the sibling sleep_sandbox, leaving the agent to infer the difference between the two.

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 word 'now' hints at immediate action but there is no explicit when-to-use, when-not-to-use, or comparison to alternatives such as sleep_sandbox, archive_sandbox, or keep_sandbox_awake. The agent gets no guidance on why to pick deep sleep over a normal sleep.

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. The description adds that folder deletion is recursive ('with everything in it'), which is meaningful extra context about blast radius. It does not mention irreversibility or auth requirements, so it modestly exceeds the annotation baseline without being 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?

One tight sentence plus the HTTP endpoint. Front-loaded with the verb and the recursive-deletion caveat; 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?

The destructive nature and recursive folder behavior are covered, but there is no output schema and the name parameter is unspecified. Enough to call it, but an agent lacks confirmation of what the response looks like and what 'name' refers to.

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%; the path parameter has a helpful exclusion note, but the name parameter is undocumented in either place. The description adds no parameter detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (delete) and resource (file or folder in sandbox files), and clarifies recursive folder deletion. It does not differentiate from siblings like delete_sandbox_image_version, but the resource is specific enough to be actionable.

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

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

No guidance on when to use this versus write_sandbox_file or create_sandbox_folder, and no prerequisites stated. The path schema gives a partial hint (what not to delete) but the description itself carries no usage direction.

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?

The destructiveHint annotation already signals that this is a destructive operation. The description adds valuable consequences: deleting an index also removes platform manifests, and space is reclaimed only at weekly garbage collection. It still omits permissions, irreversibility, and error behavior.

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

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

The deletion purpose is front-loaded and the supporting notes are compact. The HTTP path line is useful rather than wasteful, though the description could be slightly tighter.

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

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

For a destructive operation with no output schema and undocumented parameters, the description covers key cascade and cleanup behavior. It still leaves gaps around permissions, failure cases, and whether the deletion is immediate or reversible.

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 parameter semantics. It explains URL-encoding for the app parameter and maps name/app/digest through the HTTP path, but does not fully define digest format or clarify that name is the sandbox name.

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: deleting a version of a sandbox image from the registry. It is distinguishable from list_sandbox_images, but does not explicitly contrast with 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?

The deletion context is implied clearly, and the note about index manifests and garbage collection adds useful behavioral guidance. However, it does not explicitly say when to use this versus alternatives or when deletion should be avoided.

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?

destructiveHint=true already tells the agent this is a destructive operation, and the description usefully adds that access is removed immediately ('it no longer lets you in, at once'). It does not state whether deletion is permanent or recoverable, which is the key remaining behavioral fact for a destructive call.

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?

Very short and front-loaded: the action and its immediate effect come first, with the HTTP method/path as a compact trailing detail. No wasted prose, though the raw endpoint line is slightly redundant for an agent that only needs the semantic description.

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

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

For a single-parameter destructive tool with annotations covering the safety profile and no output schema, the essentials are present. What is missing is permanence/reversibility and where the id comes from, both of which materially affect 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 description coverage is 0%, so the schema gives only the bare 'id' string with no meaning. The description compensates partially by exposing the REST path template /ssh-keys/{id}, which clarifies that the id identifies the key in the path, but it never says where the id comes from (e.g., list_ssh_keys).

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

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

States a specific verb and resource ('Delete one of your SSH keys'), which cleanly separates it from add_ssh_key and list_ssh_keys in the sibling set. It stops short of explicitly naming those siblings as alternatives, but the purpose is unambiguous.

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

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

There is no guidance on when to delete versus rotate or add a key, and no prerequisites or exclusions. The possessive 'your' weakly implies scope, but an agent gets no decision criteria for choosing this over a rotate/revoke-style action.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses a precondition (the sandbox must not already have a key), but omits auth requirements, whether it returns the new key, and what happens if a key already exists — meaningful gaps for a mutation endpoint.

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

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

The definition is short and front-loads the core action and precondition. The raw HTTP verb/path is largely redundant metadata that an agent does not need, though it costs little space.

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

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

For a mutation tool with no annotations and no output schema, the description should clarify what is returned (presumably the generated key) and failure conditions; it does neither. The precondition is covered, but the ambiguous '(created with SSH)' phrasing leaves behavior only partially explained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for the single 'name' parameter. The endpoint string 'HTTP POST /sandboxes/{name}/ssh-key' implicitly tells the agent that 'name' identifies the target sandbox, adding marginal meaning, but nothing about format or constraints is supplied.

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 ('Generate the SSH key of a sandbox') and scopes it with the precondition 'that has none yet', which lets an agent separate it from get_sandbox_ssh_key. The trailing parenthetical '(created with SSH)' is ambiguous and muddies an otherwise clear purpose.

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 condition 'that has none yet' implies when this tool applies versus reading an existing key, but it never names get_sandbox_ssh_key or add_ssh_key as the alternative, nor states what to do if a key already exists. Usage is implied rather than explicit.

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?

readOnlyHint=true already tells the agent this is a safe read; the description adds nothing beyond the REST route mapping. The important behavioral caveat — that include_keys exposes Docker client certificates and private keys — appears only in the schema property, not in the description.

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 lines, front-loaded with the action and free of filler. The HTTP route line is borderline redundant for an agent but is at least compact and does convey the underlying endpoint.

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

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

For a tool that returns an unspecified bundle of 'details' with no output schema, the description leaves the agent unable to predict what comes back or how missing sandboxes are handled. The one thing that matters most here — the sensitive certificate exposure via include_keys — is undocumented in the description.

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%: include_keys is richly documented in the schema, but name has no description at all. The URL template /sandboxes/{name} partially compensates by implying that name is the sandbox identifier, but nothing is said about format, resolution, or error behavior.

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 — retrieving a sandbox by its path name — which is unambiguous on its own. It does not, however, distinguish itself from the sibling sandbox_summary, which likely overlaps in purpose, so an agent must guess between them.

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

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

There is no guidance on when to call this versus sandbox_summary, list_sandboxes, or get_sandbox_compose. The only extra text is the raw HTTP endpoint, which does not tell an agent anything about choosing this tool.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description meaningfully adds that secrets are masked in the returned compose YAML, which is real behavioral context about the response content. It does not say whether masking is permanent, what mask format is used, or what happens if no stack was deployed.

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 very short and front-loads the resource being returned, with the endpoint appended as supporting context. The 'Purgatorium' reference is unexplained noise for an agent that does not know that term, but the overall size is appropriate.

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

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

For a simple one-parameter read with no output schema, the description conveys the key fact (compose YAML with secrets masked), which is enough to call it. It still omits error behavior (missing sandbox, no stack deployed) and the exact shape/masking convention of the returned YAML, which the absent output schema would otherwise need to cover.

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% and the single parameter 'name' is undocumented in the schema. The description only indirectly clarifies it via the HTTP path '/sandboxes/{name}/compose', implying it is the sandbox name, but it never states the expected format or whether it is the sandbox name versus an ID.

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

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

The description identifies the resource (the sandbox's starter compose YAML) and the HTTP path confirms it is a retrieval of the compose file for a sandbox. However, the phrasing 'The starter stack Purgatorium deployed into the sandbox' is jargon-heavy and never uses a clean verb like 'get' or 'returns', and it gives no explicit differentiation from siblings such as get_sandbox or list_sandbox_files.

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

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

There is no guidance on when to use this tool versus get_sandbox, sandbox_summary, or list_sandbox_files, all of which an agent might reach for when inspecting a sandbox. The description states only what it is, leaving selection entirely to inference from the name.

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?

readOnlyHint=true already tells the agent this is a safe read, and the description usefully notes the returned value is a private key intended for 'ssh -i', which flags its sensitivity and format. It omits whether a key must first exist via generate_sandbox_ssh_key, which is the main behavioral gap.

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 lines, front-loaded with what is returned before the route detail. No filler, though the opening noun phrase would read better with an explicit verb.

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

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

For a simple one-parameter read tool with no output schema, the description is nearly sufficient, but it leaves open the dependency on key generation and says nothing about the returned key's format or how it is encoded.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for the single 'name' parameter, but the embedded path template '/sandboxes/{name}/ssh-key' implicitly reveals that name identifies the sandbox. That is modest added meaning over the bare string schema, not 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?

Names a specific resource (the sandbox's generated SSH private key) and reinforces it with the HTTP route 'GET /sandboxes/{name}/ssh-key', so the retrieval action and target are unambiguous. It does not explicitly differentiate itself from the sibling generate_sandbox_ssh_key, though the get/generate distinction is inferable.

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 parenthetical '(for ssh -i)' hints at the intended use case, but there is no statement of when to call this versus generate_sandbox_ssh_key or list_ssh_keys, and no prerequisites (e.g. whether a key must be generated first) are given.

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?

readOnlyHint=true already establishes this as a safe read, so the description only needs to add context. It contributes the useful nuance that the content is returned verbatim ('as written'), but says nothing about behavior for a nonexistent template or the response shape.

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 compact lines with the resource and its return semantics front-loaded. Every phrase contributes; the raw HTTP verb line is the only mildly redundant element.

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

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

For a one-parameter read tool with no output schema, the description conveys what is returned (the compose.yaml) but omits error behavior for missing templates and any hint about the return structure. 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 0% for the single 'name' parameter, so the description must compensate. The HTTP path 'GET /templates/{name}' implies the name identifies the template, but adds no format, case-sensitivity, or lookup rules beyond that inference.

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 template's compose.yaml) and clarifies the exact form returned ('as written'), which is more precise than the sibling list_templates. The verb is implicit in the name rather than stated, keeping it just short of a 5.

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

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

The parenthetical 'to show or edit before a create' implies the intended moment of use, but there is no explicit when-not guidance or named alternative (e.g., list_templates for enumeration). Usage is suggested rather than specified.

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 no annotations, the description carries the full burden and largely meets it: it explains the mechanism (one request through the sandbox's router, 'as any visit would'), the effect (sleeps a full idle timeout from now), and the key boundary (does not wake a sleeping sandbox). It omits auth requirements, error behavior for a nonexistent sandbox, and response shape, but the core behavior is well disclosed.

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 effect, then mechanism, then the important caveat, then the underlying endpoint. Four short units with no filler; the HTTP path is arguably redundant but cheap and informative.

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

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

For a simple one-parameter action with no output schema and no annotations, the description covers purpose, mechanism, side effect, and the sleeping-sandbox boundary. Missing only the return/confirmation behavior, which is minor here.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and there is one required parameter, but the description's HTTP path 'POST /sandboxes/{name}/keep-awake' implicitly conveys that 'name' identifies the sandbox. That is reasonable compensation, though it never states the parameter's semantics in words.

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 ('Start the sleep countdown over' for a sandbox) and explicitly scopes it against the sibling concern: 'Does not wake a sleeping sandbox.' An agent can distinguish it from wake_sandbox, sleep_sandbox, and deep_sleep_sandbox without reading 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?

Gives a clear condition ('For a running sandbox') and an exclusion ('Does not wake a sleeping sandbox'), which effectively routes the agent to wake_sandbox for the sleeping case. It stops short of naming that alternative explicitly, so it is clear context without full when/when-not/alternative phrasing.

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?

readOnlyHint=true already declares this as a safe read, so the description's marginal burden is low. It clarifies the domain concept (how a sandbox runs: dind, sysbox) but adds nothing about return format, auth, or the ALLOWED_RUNTIMES relationship beyond a bare mention.

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 lines, front-loaded with the purpose; the parenthetical packs in useful domain examples without padding. Slightly dense 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 no-argument, read-only list endpoint with no output schema, the description supplies everything an agent needs to call it and interpret the concept. Nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The ALLOWED_RUNTIMES mention is contextual, not a parameter.

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

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

States a specific verb (List) and resource (runtimes) plus a qualifying scope (those new sandboxes may use). No sibling covers runtimes, so an agent can route to it unambiguously.

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

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

The phrase 'runtimes new sandboxes may use' implies this is consulted when choosing a runtime for sandbox creation, but there is no explicit when/when-not guidance or named alternative. Usage is inferable rather than stated.

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?

readOnlyHint=true already tells the agent this is a safe, non-mutating operation, so the description carries little extra burden. What it does add ('HTTP GET /sandboxes') is transport detail rather than agent-relevant behavior, and it says nothing about pagination, result volume, or what a listing entry contains.

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?

Extremely short and front-loaded: the action and resource come first, followed by the endpoint. Nothing is padded, though the raw HTTP verb line is arguably redundant for an agent that already has the name and annotations.

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

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

For a zero-parameter, read-only listing tool with no output schema, the description is the minimum viable: it states what is listed but not how results are shaped or bounded (pagination, ordering, summary vs. detail). Adequate but with clear 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. The baseline for a parameterless tool is 4, and the description is consistent with the empty schema.

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

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

The description gives a clear verb+resource ('List all sandboxes'), so an agent immediately knows the operation and the object it returns. It does not, however, differentiate itself from neighboring listing tools such as sandbox_summary or list_sandbox_volumes, leaving the agent to infer the distinction from the name alone.

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

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

Usage is only implied: the name and one-line description make it obvious this is the browse-all endpoint, but there is no explicit statement of when to prefer it over sandbox_summary or get_sandbox. No prerequisites, exclusions, or alternatives are mentioned.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description only needs to add context beyond that. It notes the HTTP GET endpoint and which folders persist across a deep sleep, which is useful behavioral colour, but says nothing about pagination, result ordering, or behaviour when the path does not exist.

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 compact lines, front-loaded with the action and resource, and the HTTP endpoint is kept as a trailing implementation note. The middle parenthetical is overstuffed but not wasteful.

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 only two parameters and no output schema, the definition is nearly sufficient, but it never clarifies the return shape (file metadata vs names) or what an invalid path yields, and 'name' remains unexplained. 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 50%: 'path' is documented in the schema with a default of /root, while 'name' carries no description at all. The description partly compensates by enumerating the valid folder roots, but adds no syntax or format detail for 'name'. Baseline 3 is appropriate.

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 ('List') and resource ('a folder of the sandbox's files'), and the enumeration of /root, /home, /srv, /opt plus the pointer to list_sandbox_volumes differentiates it from the volume-listing sibling. The parenthetical is dense and slightly muddles the 'folders kept over a deep sleep' clause, but the core purpose 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 'see list_sandbox_volumes' cross-reference implies the boundary with the volumes tool, but there is no explicit statement of when to use this vs read_sandbox_file or list_sandbox_volumes, nor any prerequisites. Usage must be inferred.

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?

readOnlyHint=true already establishes the safety profile, so the description's main added value is that responses include secret-scan results and that this maps to GET /sandboxes/{name}/registry. It says nothing about ordering, pagination, empty-registry behavior, or the shape of the secret-scan data.

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 lines with no filler; the resource description comes first and the HTTP method/path follows as supporting detail. Nothing is redundant, though the endpoint line is mildly technical for an agent-facing description.

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

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

For a one-parameter read-only listing with annotation coverage and no output schema, the description covers scope, content (images plus secret-scan results), and the underlying endpoint. Only the exact return structure is missing, which is a modest gap for this complexity level.

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% and the single required parameter 'name' is undocumented in the schema. The description partially compensates by giving the endpoint /sandboxes/{name}/registry, which makes clear the name is the sandbox identifier rather than an image name — a genuinely useful disambiguation, though nothing more.

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 (the sandbox's images in the p9m registry) and a distinguishing attribute (secret-scan results), but it is a noun phrase with no verb, so the 'list' action is only inferable from the tool name. It implicitly distinguishes from delete_sandbox_image_version by being read-oriented, but never says so.

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

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

There is no statement of when to use this tool, when not to, or which sibling to prefer for image-related tasks. The agent must infer usage purely from the name and the resource phrase in the description.

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 readOnlyHint=true, the description discloses conditional behavior that annotations cannot: the 'enabled' flag reflects whether HOST_MOUNT_ROOTS is set, and administrators additionally receive 'roots' (mountable folders) while non-admins do not. That role-dependent response variation is genuinely useful context, though permissions required to call the endpoint at all are not stated.

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 field semantics, then the endpoint. Every line carries information; no filler or repetition of the tool name.

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 must convey the return shape, and it does: per-mount host path, sandbox target, readonly flag, plus the 'enabled' indicator and admin-only 'roots'. Only the auth/permission prerequisites for the endpoint are left unstated.

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% for the single 'name' parameter, so the description must carry it; the HTTP path 'GET /sandboxes/{name}/mounts' does implicitly confirm that 'name' is the sandbox name, which is real added meaning. It does not add format or validation detail beyond that, so it only partially compensates 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?

The first line names the specific resource ('Host folders mounted into the sandbox') and the body enumerates the fields returned (host path, target, readonly), making it clear this is a read/list operation over mounts. It is distinguishable from add_sandbox_mount/remove_sandbox_mount by content, though it never says 'list' explicitly and relies on the tool name for the verb.

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

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

There is no statement of when to call this versus add_sandbox_mount, remove_sandbox_mount, or list_sandbox_volumes. The only usage signal is the read-only nature implied by annotations and the path template; no alternatives or exclusions are given.

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?

readOnlyHint=true already declares the safety profile, so the bar is lower. The description adds genuine context beyond that: the volumes' files live under each volume's path and are reachable via the files tools, plus the backing HTTP endpoint. It does not disclose return shape or whether volumes are per-app or sandbox-wide beyond the brief phrase.

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

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

The definition is short and front-loads the resource, but it is a run-on sentence stitched with a semicolon and an embedded HTTP endpoint, making it less clean to parse than it could 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?

For a read-only list tool with annotations covering safety and no output schema, the description conveys the basic subject matter but omits any notion of what a returned volume entry contains or ordering/pagination behavior. Adequate but with clear 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 0% and the single 'name' parameter is undocumented in the schema. The embedded path '/sandboxes/{name}/volumes' does clarify that 'name' is the sandbox identifier, which compensates partially, but no format or constraint details are given.

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 specific resource (volumes of apps in the sandbox's own Docker), which distinguishes it from siblings like list_sandbox_images and list_sandbox_files. The verb is only implied via the tool name, and the phrasing 'The volumes of the apps in the sandbox's own Docker' is grammatically awkward, but the purpose is unambiguous.

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

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

There is no explicit when-to-use or when-not-to-use guidance. The clause 'through the files tools' weakly signals that file access is handled elsewhere, but it does not frame this as an alternative choice, so the agent gets no real routing instruction.

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, so the safe-read profile is covered. The description adds genuine context by explaining that these public keys grant root access to the caller's sandboxes, but it discloses nothing about filtering, pagination, or the returned structure beyond the raw HTTP endpoint.

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 lines with no filler; the resource and its purpose are front-loaded. The HTTP endpoint line is slightly redundant but harmless for a zero-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?

For a parameterless, read-only listing tool with annotations covering the safety profile and no output schema to explain, the description is largely sufficient. It leaves minor ambiguity about what the returned keys look like, but nothing critical for 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?

The tool takes zero parameters, so there are no parameter semantics to document; the schema is trivially complete and the description correctly adds nothing spurious.

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 identifies the resource precisely ('Your SSH public keys') and pairs it with the tool name list_ssh_keys to convey the listing action, plus a useful parenthetical explaining what the keys are for. It does not explicitly differentiate itself from the add/delete SSH-key siblings, so it stops short of a 5.

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

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

There is no statement of when to use this tool versus the closely related siblings add_ssh_key, delete_ssh_key, or get_sandbox_ssh_key. The agent must infer usage purely from the name and noun phrase.

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?

readOnlyHint=true already establishes this is a safe read, so the bar is lower. The description adds useful domain context by explaining what a template is, but discloses nothing about result ordering, pagination, or whether the list is scoped to the caller's account — details that matter for an enumeration call.

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

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

The core purpose is front-loaded in a single short sentence with a clarifying gloss. The trailing 'HTTP GET /templates' is marginally useful for endpoint mapping but is largely redundant with the tool name and consumes a line.

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

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

For a no-parameter, read-only listing with annotations covering the safety profile and no output schema, the description supplies enough for an agent to call it correctly. The main residual gap is what the returned template objects contain and whether the list is paginated or 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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The description correctly signals an unfiltered list with no arguments.

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 and resource ('List the templates') and the parenthetical clarifies that a template is the image/what runs inside a sandbox, which an agent would not otherwise know. It stops short of explicitly distinguishing itself from the sibling get_template, but 'List' vs. 'get_template' makes the plural/singular split reasonably inferable.

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

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

Usage is only implied: an agent can infer this is for enumerating available templates, presumably before create_sandbox. There is no explicit guidance to use get_template for a single template's details, nor any note on prerequisites or when listing is unnecessary.

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?

readOnlyHint=true already declares this is a safe read, so the bar is lower. The '(admin: all)' note adds a hint about required privilege, but it is cryptic and does not say whether it returns every user's tokens or only the caller's.

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 is front-loaded in a single short clause with no padding. However, 'HTTP GET /tokens' largely restates the tool name and contributes no decision-relevant 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 no-parameter, read-only list tool this is nearly complete, and the annotation covers the safety profile. The unresolved ambiguity between 'personal' tokens and the '(admin: all)' scope is the main remaining 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies.

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

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

States a specific verb and resource ('List personal access tokens'), which cleanly separates it from the create_token and revoke_token siblings by verb. The '(admin: all)' fragment is not explained, so the exact scope of what is listed is left slightly ambiguous.

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

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

No when-to-use guidance and no alternatives are named, even though create_token and revoke_token exist as obvious complements. The agent must infer that this is the read counterpart to those siblings from the name alone.

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 no annotations, the description carries the full burden and discloses key traits: the link is single-use, expires after 5 minutes, returns .p9m contents with Docker keys, and yields HTTP 410 when expired or used. It also warns against copying keys and explains Docker context handling, though it omits auth requirements and 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 critical facts are front-loaded: single-use link, 5-minute lifetime, contents, and usage command. The text is somewhat dense and the opening sentence is a fragment, but nearly every sentence provides actionable 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?

Given no output schema and no annotations, the description explains the returned link, its contents, the unpacking command, expiry behavior, and Docker context follow-up. It is complete enough to call correctly, though the parameter meaning and permission requirements remain slightly underspecified.

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 explain the single `name` parameter. It does so indirectly via 'HTTP POST /sandboxes/{name}/project-link' and references to the sandbox's Docker keys, implying `name` is the sandbox identifier, but it never explicitly defines the parameter or its format.

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

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

The description clearly identifies the resource: a single-use link to the project's .p9m folder containing Docker keys, and the HTTP endpoint. It is specific enough to distinguish from most siblings, but the opening is a noun phrase rather than an explicit verb, so the action ('returns a link') must be inferred.

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

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

The description gives detailed post-call instructions (run the curl command yourself, never copy a key, recreate the Docker context after new keys or TLS errors, ask for a new link on 410). However, it does not explain when to choose this tool over alternatives such as rotate_docker_keys or get_sandbox_ssh_key, leaving selection guidance 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 declare readOnlyHint=true, so the safety profile is covered. The description adds genuine behavioral detail beyond that: the file must be UTF-8 and no larger than 1 MB, which tells the agent when the call will fail. It does not describe error behavior or path-resolution rules, keeping it below the top mark.

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 lines, front-loaded with the verb and resource, with no filler prose. The trailing 'HTTP GET /sandboxes/{name}/files/text' is implementation detail that adds little for an agent choosing the tool, slightly diluting an otherwise efficient definition.

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

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

There is no output schema, so return values need not be explained, and annotations cover the read-only safety profile. However, for a file-read tool the description omits what happens on missing files, how binary or oversized files are handled, and how the path resolves within the sandbox, leaving meaningful 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 description coverage is 50%: 'path' has an example but 'name' has none. The phrase 'the sandbox's files' plus the endpoint /sandboxes/{name}/files/text does clarify that 'name' is the sandbox name, partially compensating. It adds only marginal meaning over the schema for the path format.

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 text file of the sandbox's files), which clearly separates it from the sibling write_sandbox_file and delete_sandbox_file. The added constraints (UTF-8, up to 1 MB) sharpen what kind of file it operates on. It stops short of explicitly naming the alternative read path (list_sandbox_files), so it is clear but not fully sibling-differentiated.

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 'text file ... up to 1 MB' constraint implies when this tool is appropriate (small UTF-8 files) and implicitly when it is not (binary or oversized files), but no alternative tool is named and no preconditions are stated. Usage is left to inference rather than spelled out.

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 destructiveHint=true, so the description carries real weight here and delivers: admin authorization requirement, the non-obvious side effect that the sandbox container is recreated, and the underlying HTTP DELETE endpoint. It stops short of saying whether data on the mount is lost, which matters for a destructive op.

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 verb and admin gate, then the side effect, then the endpoint. Compact and every line carries information; only the parenthetical '(admin)' duplicates the later 'Admin only' sentence.

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

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

For a two-parameter destructive tool with annotations and no output schema, it covers the important unknowns: authorization, container recreation, and endpoint semantics. The remaining gap is the fate of mount contents and the meaning of 'name'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50%: 'target' is documented in the schema, but 'name' has no description in either place. The description refers to 'this target' without clarifying whether 'name' is the sandbox name or the mount identifier, leaving a genuine ambiguity.

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: unmount/remove a host folder mount from a sandbox, scoped to a named target. Clear enough to separate from add_sandbox_mount, though the counterpart is not named 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?

Adds the 'Admin only' gate and a useful nuance that removal works even after HOST_MOUNT_ROOTS is unset, but gives no guidance on prerequisites (e.g. locate the mount via list_sandbox_mounts first) or how to choose between mount operations.

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 no annotations, the description carries the full behavioral burden and supplies almost none. It does not disclose that restarting destroys running processes or in-memory state, whether it requires auth, or what happens to attached volumes/files — all critical for a potentially disruptive operation.

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

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

The text is front-loaded and free of padding, which is a virtue, but the extreme brevity is under-specification rather than disciplined conciseness — the endpoint line adds little agent-facing value.

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

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

For a mutation tool with no annotations, no output schema, and an undocumented parameter, the description is too thin. An agent cannot tell what state is lost on restart, whether it blocks, or what a successful response looks like.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'name' has 0% schema description coverage, and the description only reveals it via the URL template '/sandboxes/{name}/restart'. It never states that this is the sandbox name, its format, or whether it must be unique/existing.

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 ('Restart sandbox'), so the agent knows exactly what operation runs. However, it offers no differentiation from closely related siblings like wake_sandbox, keep_sandbox_awake, or deep_sleep_sandbox, so an agent must infer the semantic boundary itself.

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

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

There is no guidance on when to use this tool versus sleep_sandbox, wake_sandbox, or keep_sandbox_awake, nor any stated prerequisites (e.g., sandbox must exist or be running). The HTTP line is a transport detail, not usage advice.

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?

destructiveHint=true already tells the agent this is an irreversible mutation, so the description's job is to add context beyond that. It instead restates the operation and gives the raw HTTP method/path (DELETE /tokens/{id}), disclosing nothing about authorization requirements, whether revocation is immediate, or what happens to sandboxes or keys already using the token.

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 lines with the purpose front-loaded and no filler prose. The HTTP endpoint line is borderline redundant but does clarify the identifier's role, so the size is appropriate if slightly thin.

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

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

For a one-parameter destructive tool the essentials are present, but given destructiveHint and no output schema, an agent still lacks the auth/irreversibility and downstream-effect context that would make this call safely. Adequate minimum, clear 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?

The single 'id' parameter has 0% schema description coverage, so the schema alone does not say what the identifier refers to. The URL template /tokens/{id} in the description implicitly clarifies that id is a token identifier, which is modest but real added meaning over the bare string type.

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 (Revoke) and resource (personal access token), which is inherently distinct from its nearest siblings list_tokens and create_token. 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?

No guidance on when to use this versus the alternatives (list_tokens, create_token) or any preconditions such as needing an existing token id. The verb implies intent but there is no explicit when-to-use or when-not-to-use statement.

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 no annotations, the description carries the burden and does meaningful work: it discloses that existing certificate exports stop working and that the sandbox will restart — both important side effects an agent should know before invoking. It omits return value and any auth/permission 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?

Front-loads the purpose, then adds the certificate details and side effects, closing with the HTTP endpoint. Efficient and well ordered, though the '(enable / rotate)' framing and raw endpoint line add minor redundancy.

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

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

For a single-parameter action tool with no output schema or annotations, the description covers the key effect (new certs) and the disruptive side effects (old exports invalidated, sandbox restart). Only the return payload and permission requirements are unaddressed, which is a modest 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?

One parameter ('name') with 0% schema description coverage, so the description must compensate. Context ('the sandbox's Docker API') makes it clear 'name' is the sandbox name, but it is never stated explicitly. Baseline 3 for the near-trivial single 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?

States a specific verb+resource: it issues new Docker access certificates (CA, server, client) for the sandbox's Docker API, naming the endpoint POST /sandboxes/{name}/docker-keys. The '(enable / rotate)' parenthetical slightly muddies whether this is one action or two, but the resource and effect are unambiguous and no sibling tool overlaps.

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?

Implies the use case (you need fresh Docker certs) and warns that earlier exports stop working, but never states explicitly when to call this versus leaving existing certs alone, nor prerequisites. Usage is inferable rather than spelled out.

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?

readOnlyHint=true already declares a safe read, but the description adds real value beyond that: it defines asleep (stopped, including failed starts), archived (deleted but retained, not quota-counted), and the free/quota semantics. It also clarifies the role-dependent output scope. Only the exact response shape is left implicit.

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 front-loads the count categories before the role/quota explanation and the HTTP endpoint. The colon-list phrasing is telegraphic but every line earns its place; minor awkwardness in formatting keeps it from a 5.

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 explaining what the summary returns (the state categories and quota-relative counts) and how scope varies by role. That is nearly complete for a zero-parameter read tool, though it doesn't describe pagination or exact field names.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the schema carries no semantic burden and the baseline is 4. The description correctly adds no parameter details because there are none to add.

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 resource (sandboxes) and verb (count/summarize) broken down by state: allowed, running, asleep, deep sleep, archived. An agent can distinguish this counting tool from list_sandboxes, which enumerates rather than aggregates. It stops short of explicitly naming the sibling, keeping it at a 4.

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 scope context (a user sees their own against quota; an admin sees the whole server and by_owner), which implies when the tool is relevant. However, it never states when to prefer this over list_sandboxes or get_sandbox, so the routing guidance is only implied.

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 no annotations present, the description carries the full burden and does substantial work: it discloses that a new idle_timeout recreates only the socat container, that a running sandbox's app is unreachable for a few seconds while an asleep one stays asleep, and that the value applies to the next request's Sablier session while deep_sleep_after applies immediately. It omits auth/permission requirements and the response shape, which keeps 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?

Front-loaded with the one-line purpose, then the parameter-level effects, then the underlying HTTP route as a trailing detail. Every sentence carries information; only the raw 'HTTP PATCH /sandboxes/{name}' line is arguably redundant for an agent.

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 zero annotations and no output schema, the description covers side effects and timing well but leaves the agent without permission requirements, return-value expectations, or guidance on the 'off'/'0' values that disable sleeping. Adequate but not complete for the annotation-free burden it carries.

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 'disk' is documented), so the description must compensate and it partially does by explaining the runtime effect and apply-timing of idle_timeout versus deep_sleep_after. It does not explain the '0'/'off' sentinel values allowed by both patterns, nor the unit conventions beyond the schema examples, so meaningful gaps remain.

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 ('Change sleep settings') and immediately names the two fields it mutates on an existing sandbox. The sibling set contains sleep_sandbox and deep_sleep_sandbox, and while the 'settings' framing implicitly separates this tool from those actions, the description never explicitly says so.

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

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

Says the fields can be changed 'and/or' on an existing sandbox, which implies a partial-update use case, and explains the differing timing of the two changes. However, it never states when to pick this over sleep_sandbox / deep_sleep_sandbox / keep_sandbox_awake, nor any prerequisites beyond 'existing sandbox'.

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 no annotations, the description carries the full behavioral burden but discloses almost nothing: not whether the sandbox state/volumes persist, whether the action is reversible (wake_sandbox exists, implying it is), cost implications, or latency. The only extra information is the raw HTTP endpoint method and path, which is structural rather than behavioral.

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 terse lines with no filler and the action front-loaded, but the brevity is under-specification rather than disciplined conciseness. The appended HTTP route is the only substantive content beyond the name restatement.

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

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

For a mutation tool with no annotations, no output schema, an undocumented parameter, and several confusable siblings (deep_sleep_sandbox, wake_sandbox, archive_sandbox), the description leaves too much unresolved. An agent cannot confidently choose or predict the effect of this call from the description alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter has 0% schema description coverage, and the description only embeds it as {name} in the URL path. That hints it is an identifier but adds no format, constraints, or meaning beyond the schema's bare string type.

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?

"Stop sandbox" names a clear verb and resource, so a reader knows the basic action. However, it is nearly a restatement of the tool name sleep_sandbox and gives no differentiation from closely related siblings such as deep_sleep_sandbox, archive_sandbox, keep_sandbox_awake, or restart_sandbox, which is exactly where an agent needs help.

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

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

There is no when-to-use guidance at all—no mention of when to sleep versus deep-sleep, keep-awake, restart, or archive. The description offers no conditions or alternatives, so the agent must infer selection purely from the name.

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?

There are no annotations, so the description carries the full burden and does disclose real behavior beyond the schema: the 409 failure mode, the `reason` field, the returned `running` sandboxes, and the workaround of sleeping another sandbox first. It does not cover auth requirements, idempotency when the sandbox is already running, or timing/async wake behavior.

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

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

Four short segments, front-loaded with the action and followed by the constraint and recovery path, with no filler. The leading 'Start sandbox' line is a near-restatement of the second sentence, a minor redundancy rather than a real cost.

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

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

With no annotations, no output schema and 0% parameter coverage, the description supplies the error contract, the escape hatch for capacity limits, and the endpoint, which is enough to call it correctly. Missing only the success return shape and auth prerequisites for a tool that mutates sandbox state.

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 compensate and largely does: `name` is located in the path (/sandboxes/{name}/start) and `sleep` is given concrete semantics — put one of the running sandboxes to sleep to free a slot — including a literal example payload. It stops short of clarifying whether `name` accepts a display name or an id.

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

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

States a specific verb and resource — 'Wakes an asleep or deep-sleeping sandbox' — and pins it to an HTTP endpoint (POST /sandboxes/{name}/start), so the agent knows exactly what action is performed. It implicitly separates itself from sleep_sandbox/restart_sandbox by naming the sleep states it wakes from, but never names those siblings 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?

Gives clear usage context: call this to wake a sandbox, and when the owner is at a limit you get a 409 with a `reason` and the list of running sandboxes. It also documents the recovery path (pass `sleep` to free a slot first). No explicit exclusion versus keep_sandbox_awake or restart_sandbox, which is the only gap.

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 readOnlyHint=true, so the safety profile is covered. The description adds essentially nothing beyond the endpoint path — no mention of what identity data is returned, auth requirements, or behavior.

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

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

Very short but not front-loaded with useful information; it's under-specified rather than concise. 'Who am I' followed by a raw endpoint line provides minimal value.

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

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

For a zero-param read tool with no output schema, the description should explain what identity information is returned (user, org, token). Neither the description nor an output schema fills this gap, leaving the return shape entirely unspecified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Zero parameters, so baseline is 4. There are no parameters to document, and the description neither misleads nor needs to compensate.

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

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

The name 'who_am_i' is restated as 'Who am I', which is tautological. The only added signal is the HTTP endpoint 'GET /me', which hints at identity retrieval but doesn't describe the resource or returned information clearly enough for standalone comprehension.

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

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

No guidance on when to use this versus alternatives. Nothing indicates it's for retrieving the current authenticated identity, nor when this is preferable to other 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?

With no annotations, the description carries the full burden. It discloses the destructive overwrite behavior and the folder precondition, which is more than nothing, but omits auth/permission requirements, size limits, and whether missing folders cause an error versus being created.

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 sentence with the key constraint (replacement) in parentheses, plus the HTTP endpoint. Every element earns its place; no filler.

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

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

No output schema and no annotations, so the description must stand alone. It covers overwrite and folder existence but leaves callers guessing on error behavior, permissions, and content-size constraints for a mutation 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 67%; body and path are already documented in the schema (path with an example). The description adds the path/folder precondition and overwrite behavior but does not clarify the undocumented 'name' parameter.

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

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

States a specific verb and resource ('Upload a file into the sandbox's files') and its effect on same-named files. It clearly distinguishes itself from read_sandbox_file, delete_sandbox_file, and list_sandbox_files by naming the write/upload action, though it doesn't explicitly call out those 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 a concrete precondition ('its folder must exist') and notes overwrite semantics, which is genuinely useful. However, it offers no explicit when-to-use guidance versus alternatives, nor does it say when not to use it.

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