Celesto Computer

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

Beyond the annotations (which already flag destructiveHint=true and readOnlyHint=false), it discloses retention limits (first 4 MiB per stream), the fact that disconnecting this tool does not stop execution, that expired output cannot be recovered by retrying, and how to interpret an unknown state with cancel_requested=true. These are exactly the operational facts an agent cannot infer from the annotations.

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

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

Purpose and the start-tool relationship are front-loaded, and nearly every clause carries distinct information (retention, cancel semantics, expiry, disconnect behavior). It is dense — several clauses are packed into single sentences and the word 'previews' is left vague — but there is little outright waste.

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 7-parameter, multi-action tool with an output schema already present, the description covers what an agent needs before calling: action selection, stream/offset continuation, size retention, cancellation caveats, and irrecoverable expiry. Return-value detail is correctly left to the output schema.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds real meaning: search returns up to 10 literal UTF-8 byte offsets and should be continued via next_offset, and offset is interpreted against retained output. Those semantics go beyond the enum and integer descriptions in the schema.

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

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

Opens with a specific verb+resource ('Inspect a command_id from cloud_computer_command_start') and immediately scopes it against the sibling that produces the handle ('without executing again'), so an agent can tell it apart from cloud_computer_exec or cloud_computer_command_start without reading either schema.

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

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

It maps each action value to a concrete intent (status polls and previews, read returns text, search finds offsets, cancel requests termination), which tells the agent which mode to pick. It stops short of explicit when-not-to-use guidance or naming alternative tools for the read/cancel split, so it is clear context rather than a full routing rule.

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

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

Goes well beyond the annotations: discloses ~1s return latency, the state enum, nullable exit_code, bounded head/tail previews, retention limits (1 hour, 4 MiB per stream), capacity eviction with discarded-byte metadata, and that results survive agent restart but not host loss or migration. It also flags the guest-image prerequisite. The destructive/openWorld/idempotent hints are consistent with the described mutation and retry 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?

Front-loads the primary purpose and the return shape, then layers recovery, delegation, and retention constraints in descending priority. Every sentence carries distinct operational information with no restatement of the name or title.

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

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

Covers prerequisites (guest image), lifecycle (restart vs. host loss), output bounds, and the recovery path for a lost response. Although an output schema exists, the inline summary of return fields is consistent with it and does not substitute for it, so nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real value on top by explaining the recovery contract for idempotency_key ('reuse the SAME idempotency_key, command and timeout') and by tying output behavior to the command's size. It does not elaborate on the name resolution or timeout bounds 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 ('shell execution tool for scripts, builds and commands') and scopes it to large-output workloads, which implicitly separates it from cloud_computer_exec. It also names the companion tool cloud_computer_command_inspect for follow-up operations, so an agent can place it in the toolset without opening a schema.

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

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

Explicitly routes polling, byte-range reads, search, and cancellation to cloud_computer_command_inspect, and explains the idempotency-key recovery pattern for lost replies. It does not explicitly say when to prefer the sibling cloud_computer_exec (e.g. small/fast commands), leaving that comparison to the 'Preferred' framing.

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

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

Adds real behavior beyond the annotations: the call is refused and enumerates account sizes when size_id is missing, and the response is returned only after the computer reaches running (blocking semantics). The idempotency guidance partially restates the schema description, and no auth/permission or quota behavior is described.

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, front-loaded sentences, each carrying distinct information: purpose, idempotency discipline, prerequisite/error behavior, and return plus follow-on usage. There is no filler or restatement 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 an output schema present, the description need not enumerate return fields, yet it usefully flags the blocking-until-running behavior and the meaning of the returned name. Prerequisite, idempotency, and follow-on workflow are all covered, so an agent has everything needed to invoke correctly.

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

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

Schema coverage is 100% with enums documented, so the baseline is 3; the description still adds procedural meaning by telling the agent to obtain size_id from the user before calling and how to treat the idempotency key across retries. The key-reuse rule largely duplicates the schema's own wording, capping this at 4.

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

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

The first sentence states a specific verb and resource ('Create a persistent Cloud computer') and the term 'persistent' distinguishes it from transient or in-session work. Against siblings like cloud_computer_start, cloud_computer_list, and cloud_computer_delete, an agent can immediately tell this is the provisioning entry point.

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

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

Gives concrete pre-call guidance ('Ask the user which size_id to use before calling') and describes the fallback when omitted (refused call that lists available sizes). It also routes to downstream usage ('use that name in subsequent computer tools'), but never states when not to create one or points to cloud_computer_list/info as an alternative for existing machines.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds real substance: files are removed, running work is stopped, public routes are dropped, the action is irreversible, and it returns name/provider/state=deleted. These are consequences an agent cannot read off the annotations.

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

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

Three short sentences, each doing distinct work: effect, warning, return value. The destructive consequence is front-loaded where it matters most.

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 full annotation coverage and an output schema, this covers everything an agent needs: what is destroyed, irreversibility, and what the call returns.

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

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

Schema coverage is 100% and the single 'name' parameter is already documented with accepted formats (id or display name). The description adds no additional parameter meaning, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Permanently delete a Celesto Cloud computer and its files') plus the collateral effects (stops running work, removes public routes). The word 'permanently' cleanly separates it from the reversible cloud_computer_stop sibling.

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

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

Gives clear usage context: it is irreversible and the agent should copy out data beforehand. It does not explicitly name cloud_computer_stop as the alternative for temporary shutdown, so the when-not comparison 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?

Annotations already flag destructive=true, non-idempotent, open-world, so the bar is lower, yet the description adds real behavioral facts: repeat calls re-execute the command, output may be truncated as signaled by stdout_truncated/stderr_truncated, and a timed-out MCP request may leave the command running with unrecoverable output. These are exactly the failure modes an agent needs.

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

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

Content is front-loaded with purpose and return values, then hazards; every sentence carries distinct information. It runs slightly long and the 'The command is the program or shell expression...' sentence partly duplicates the schema, keeping 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?

For an open-world, destructive, non-idempotent exec tool, the description covers mutation risk, truncation signaling, and timeout semantics, and an output schema exists so return values need no further explanation. Nothing an agent needs to invoke it safely is missing.

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

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

Schema description coverage is 100%, so name, command, and timeout are already documented with a default; the description largely restates the command parameter and adds no syntax, quoting, or timeout-selection detail beyond the schema. Baseline 3 applies.

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

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

States a concrete verb+resource ('Run a shell command on a running Celesto Cloud computer') and names the return payload (stdout, stderr, exit_code), which cleanly separates it from the create/delete/list/info/port/start/stop 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 phrase 'on a running ... computer' establishes the prerequisite state and 'for work on its guest filesystem and processes' scopes the intended use. It also warns to check state before retrying after a timeout. It stops short of naming an explicit alternative or a when-not condition, but no exec-like sibling exists to route against.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description's remaining content is a return-field enumeration that duplicates the output schema and adds no new behavioral context such as error behavior for an unknown name or 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?

Two sentences, front-loaded with purpose and then usage. The field list is somewhat redundant against the output schema but is compactly written; nothing is padded or buried.

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 an output schema, annotations, and a single fully-documented parameter, the description supplies ample context for correct invocation. It could be marginally stronger by noting failure behavior for an unknown or deleted computer, but that is a minor gap.

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

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

Schema description coverage is 100% and the single 'name' parameter is fully documented as 'Computer id from create or list, or its display name from info.' The description adds nothing about the parameter, 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?

States a specific verb and resource ('Inspect a Celesto Cloud computer's state and resource configuration') and clearly separates itself from siblings by naming cloud_computer_list as the source of the computer reference. An agent can distinguish this read/inspect tool from create, exec, start, or stop without opening any schema.

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

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

Explicitly says when to reach for it: 'Use this to check readiness or inspect a computer returned by cloud_computer_list.' That names a concrete scenario and a sibling, though it stops short of stating when not to use it (e.g., when create/exec are the right follow-ups).

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

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

Annotations already cover read-only, idempotency and safety, but the description adds behavior the annotations cannot convey: the server does not count all computers, so possibly_truncated is always true and the result never proves completeness. That is a genuinely important caveat for an agent deciding how to page or whether to trust the list.

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 scope and the truncation caveat, which are the highest-value facts. Slightly over-long: enumerating returned fields (provider, computers, applied limit, possibly_truncated) duplicates the output schema that already exists.

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 a single optional parameter, an output schema, and full annotation coverage, the description leaves nothing an agent needs unanswered: scope, exclusions, paging caveat, and how results feed downstream tools are all present.

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

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

Schema coverage is 100%, so limit is already documented structurally. The description adds the intent behind it — bounding how many candidates the agent inspects at once — which layers in query/paging semantics beyond the field definition.

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

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

States a specific verb and resource with scope: 'List non-deleted Celesto Cloud computers in the authenticated organization.' It further narrows scope by excluding GitHub CI runner machines, which is critical disambiguation among compute-listing tools.

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

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

Explicitly tells the agent what to do with results ('pass a returned computer_id to the other computer tools') and names the alternative for a specific need ('Use cloud_computer_info for names and resource details'). Routing between siblings is unambiguous.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description only needs to add context. It does so by disclosing that suspended routes and publication changes are included and by explaining status/enabled semantics and the meaning of an empty ports array.

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

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

Three sentences, front-loaded with the core purpose, then return shape, then status semantics; nothing is wasted. The enumerated return fields slightly duplicate what the output schema already provides, keeping it just below 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 an output schema present and full annotation coverage, the description need not explain return values, yet it supplies the semantic layer the schema cannot (status meaning, empty-array interpretation). Nothing needed to invoke this read-only list correctly is missing.

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

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

Schema description coverage is 100% and the single parameter is fully documented in the schema ('Computer id from create or list, or its display name from info'). The description adds no additional parameter meaning, so the baseline 3 applies.

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

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

The description names a specific verb and resource ('List public HTTP routes for a Celesto Cloud computer') and adds scope detail ('including suspended routes and publication changes'). It does not explicitly differentiate itself from the sibling route-mutating tools (port_publish/port_unpublish), so it falls 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?

It gives useful operational guidance on interpreting results ('check status before using a URL: only published routes are enabled, and the application must be listening') and explains the empty-array case. However, it never states when to call this tool versus alternatives such as cloud_computer_info or port_publish, so usage selection 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?

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true; the description reinforces these with 'reuses an already-published one' (idempotency), 'anyone with the URL can send requests' (open-world exposure) and a security warning. It does not explain what the destructiveHint actually destroys (existing route removal on unpublish, or exposure risk), which is the one meaningful gap left.

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?

Well front-loaded: purpose first, then prerequisites, then behavior, then return shape. Slightly long, and the trailing sentence enumerating the response fields ('Returns name, provider, route id, ...') duplicates an existing output schema, so it does not fully earn its place.

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

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

For a mutation tool with an output schema, the description covers the prerequisites, the idempotent reuse behavior, the public-exposure security implication, and what the URL/status mean. An agent has everything needed to decide to call it and to interpret the result.

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

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

Schema description coverage is 100%, so the schema already documents both parameters, including that 'name' accepts an id or display name and that 'port' selects the route. The description adds no format, range, or selection semantics beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

Specific verb+resource+mechanism: 'Expose an HTTP application on a running Celesto Cloud computer through a public URL.' It is clearly distinguishable from siblings cloud_computer_port_list and cloud_computer_port_unpublish, which operate on the same route concept but do not create one.

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?

States prerequisites explicitly (computer must be running, guest image must support public ports, application must listen on the guest port) and gives a usage constraint ('Only publish endpoints intended for public traffic'). It never names port_unpublish as the inverse action, so the routing between the two 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?

Annotations already declare destructive, idempotent, non-read-only and open-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: the removal is queued, the returned status may be a transitional 'unpublishing' state, and the URL only stops forwarding once removal completes. That asynchronous, eventually-consistent semantics is exactly what an agent needs and is not in the annotations.

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

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

Three tight sentences with the core action front-loaded, followed by the async behavior and then the edge case. Every sentence carries information an agent needs; nothing is redundant with the title.

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

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

Although an output schema exists, the description still usefully previews the status values and the no-route edge case, and it discloses the async completion model for a destructive operation. Combined with the annotations covering safety, nothing needed to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already explains both 'name' and 'port' fully, including that port selects the route. The description adds no syntax, format, or validation detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Remove a public HTTP route from a Celesto Cloud computer') and immediately scopes it against the closest sibling, cloud_computer_port_publish, by naming the inverse operation. An agent can distinguish this from stop, delete, and port_publish without opening any schema.

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

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

Clearly frames the operation as the inverse of publishing and draws the important boundary that it 'does not stop the application inside the computer,' which prevents confusion with cloud_computer_stop. It also notes the no-op case when no active route exists. It stops short of explicitly naming cloud_computer_port_publish as the alternative, so it is clear context rather than full routing guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the safety profile is covered structurally. The description adds real value beyond that by signaling that startup is a blocking/awaited operation ("after startup completes") and that state becomes running. It does not state permission requirements or what happens on a failed start.

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

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

Two sentences, fully front-loaded: the action and precondition come first, the completion semantics second. No filler, no repetition of the schema.

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

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

With a rich output schema and annotation coverage, the description needn't explain returns, yet it does repeat the returned fields (name, provider, state=running), which is mildly redundant. For a single-parameter, low-complexity tool it is otherwise sufficient to call correctly.

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

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

Schema description coverage is 100% and the single parameter already documents that it accepts an id from create/list or a display name from info. The description adds nothing about the name argument beyond echoing that it is returned, so the baseline 3 applies.

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

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

"Resume a stopped Celesto Cloud computer" gives a specific verb (resume/start), resource (Cloud computer), and precondition (stopped), which separates it cleanly from siblings like delete, exec, or create. It stops short of naming an alternative or edge case (e.g., already-running computers), so it lands at clear-but-not-exemplary.

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 "stopped" implies the usage context, but the description never states explicitly when to call start versus stop, create, or exec, nor what happens if the computer is already running. Usage is inferred from a single adjective 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?

Annotations only tell us this is non-read-only, idempotent and non-destructive; the description adds the real behavioral payload: running processes are interrupted, files survive, public ports are suspended while stopped, and the machine reaches state=stopped. That is exactly the consequence-level detail an agent needs before calling a stop 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?

Four short sentences, front-loaded with the action and its key side effect, with no filler or repetition. The final return-value sentence is largely redundant given an output schema exists, which is the only slight bloat.

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 stop tool with an output schema and annotation coverage of the safety profile, the description supplies everything remaining: the precondition to save work, what is retained versus interrupted, port behavior, and the resulting state. 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?

Only one parameter exists and schema description coverage is 100%, with the schema already explaining that "name" accepts a computer id from create/list or a display name from info. The description merely says "the supplied name" and adds no format or disambiguation value beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("Stop a running Celesto Cloud computer") and immediately delimits it from the destructive sibling by noting it interrupts processes "while retaining its files." An agent can distinguish this from cloud_computer_delete or cloud_computer_exec without opening any schema.

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

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

"Save in-memory work first" gives a clear precondition for use, and the file-retention and port-suspension notes communicate the stopping state an agent should expect. It stops short of naming the alternative explicitly (e.g., "use cloud_computer_delete to remove permanently"), so it is clear context without exclusions.

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