EQVPS — VPS and code sandboxes for AI agents

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

With no annotations, the description carries the full burden and does well: it discloses the auth requirement (signed in as the invited email), the effect (grants operator access to your own account), and a key side effect (no new token is returned). It omits idempotency/error behavior and reversibility details.

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 sentence is front-loaded and short, but the tail repeats itself: 'signed in as the invited email address' is restated as 'token of the invited email,' and the token's source is mentioned twice.

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 mutation tool with no annotations and no output schema, the description covers the essentials: auth prerequisite, token source, resulting access, and the fact that no new token is returned. Minor gaps around error/failure behavior remain.

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 token parameter, so the description must compensate. It adds meaningful semantics: the token comes from the invite link and must belong to the invited email, which goes beyond the bare string type 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?

States a specific verb and resource (accept a delegation invitation) and clarifies the input source (token from the invite link), which distinguishes it from revoke_delegation and list_delegations. It does not explicitly name those siblings as alternatives, 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?

Gives a clear usage condition: you must be signed in as the invited email address, and the token must come from the invite link. It does not state when-not to use it or name alternative tools, so it stops short of explicit 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?

No annotations are provided, so the description carries the full burden and does: it discloses that immediate permanently and irreversibly destroys VM and data, that end_of_period causes no data loss now, that refunds flow to account balance, and that auth (token) plus confirm=hostname are required.

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 default behavior and reasonably dense, with every sentence carrying operational value. It is slightly run-on and emphasis-heavy, but there is little genuine 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?

Despite no output schema, it explains the relevant response fields (refund_amount, cancellation {type, cancel_at, can_undo}) and full prerequisite/error handling. An agent has everything needed to call it correctly and recover from the common failure.

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

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

Schema coverage is only 50%, and the description more than compensates: it explains the meaning/danger of each `type` enum value and clarifies that `confirm` must equal the exact server hostname. This adds meaning well beyond the bare enum and undocumented `confirm` field.

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 ('Cancel a VPS') and immediately differentiates its two operating modes. It names siblings (undo_cancel, get_vps_status) so an agent can distinguish it from adjacent tools without opening schemas.

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

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

Explicitly says 'Use end_of_period unless you explicitly intend to wipe the server now', and covers the already-scheduled case with the exact remediation path (undo_cancel, or re-call with type=immediate + confirm). The 409 cancellation_already_scheduled error path is spelled out with the alternative to take.

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 full burden, and it delivers: one reboot (~1 min), immediate prorated charge from prepaid balance, 402 with needed/balance shortfall, refund of unused difference for convert_to_nat, and new renewal price. This is exactly the side-effect disclosure a mutation tool needs.

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

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

Front-loaded with the core action and its side effects, and nearly every sentence carries operational value (reboot, charge, errors). The closing 'Requires: token + balance + confirm: true' partially restates earlier content, which is the only 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?

With no output schema and no annotations, the description still covers prerequisites, mutation semantics, error codes and recovery, and downstream billing effects. An agent has everything needed to invoke this correctly.

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

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

Schema coverage is already 100%, so baseline is 3, but the description adds provenance for target_plan ('product_id from get_upgrade_options') and reinforces that confirm must be true. Minor confusion: it references 'convert_to_nat' as if it were an input, though it is not a parameter of this schema.

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

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

States a specific verb+resource with scope: 'Switch a VPS to another plan IN PLACE — files and the OS are kept'. It distinguishes it from get_upgrade_options (which only lists options) and makes clear this is the mutation counterpart.

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 the agent: target_plan comes from get_upgrade_options, and a 422 means 'not an upgrade (pick from get_upgrade_options)'. It also prescribes the recovery path for 402 (top up and retry), so usage conditions are fully covered.

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 usefully discloses the auth requirement ('Requires: token') and that rating/comment are optional, but says nothing about whether closing is reversible, what happens on close, or side effects for a mutation 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?

Three short sentences, front-loaded with the core action, and every clause adds usable information. No padding or repetition of the title.

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

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

For a simple 3-param mutation with no annotations and no output schema, the description covers params and token but omits any statement about irreversibility or the result of closing. Adequate but with a clear behavioral 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 0%, so the description must compensate. It documents the rating range (1-5), that comment is a free string, and where ticket_code comes from — covering all three parameters with meaningful semantics beyond the raw schema types.

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 ('Close one of your tickets') that clearly distinguishes it from read siblings like get_ticket and list_tickets. It doesn't explicitly name what it is not, but the action is unambiguous.

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

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

Gives clear context for use: close a ticket, with the ticket code sourced from create_ticket/list_tickets. It clarifies that rating/comment are optional, removing a common point of hesitation. No explicit 'when-not' or alternative tool is given, so it falls short of a 5.

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

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: readiness (~1 s), billing model per mode, minimum 60 s, idle_timeout auto-deletion, ttl caps, pause/snapshot/resume semantics, 14-day snapshot deletion, capacity 503 with Retry-After, and the full trial-account restriction set (402 trial=email_unverified, 403 trial_tariff/trial_persistent, 429 trial_limit, 2-concurrent/20-min/14-day limits). This is unusually complete behavioral disclosure for a mutation tool.

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

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

The core facts are front-loaded, but the description is a single sprawling paragraph dense with nested parentheticals, and the full tariff pricing table duplicates the sibling sandbox_pricing tool. Several sentences (pricing tiers, balance mechanics) could be deferred to that sibling. It reads as over-sized for a create call even though much of the content is genuinely useful.

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

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

No output schema exists, yet the description specifies the response shape ('state: running', 'ready: true', or 'starting'), and it covers the nested env object's storage/encryption behavior and limits. Given the tool's complexity (5 params, nested object, no annotations), an agent has everything needed to call it correctly and 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 coverage is 80%, but the description adds meaning the schema lacks — mode's enum has no schema description yet is fully defined here (ephemeral vs persistent, billing, survival across maintenance, differing ttl caps), and tariff's enum is expanded into vCPU/RAM/disk/pricing guidance plus a sizing recommendation. idle_timeout's 0 = none (persistent only) nuance is also supplied. Value is added well beyond the structured fields.

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

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

Opens with a specific verb+resource: 'Start an isolated Firecracker microVM sandbox', immediately identifying this as the creation tool among siblings create_*/get_sandbox/list_sandboxes/kill_sandbox. The runtime contents (Python 3.12, Node 22, bash, git, curl) and network posture make the resource concrete rather than generic. An agent can distinguish it from every sibling without opening a schema.

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

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

Gives explicit routing: call get_sandbox after 1-2 s if state is 'starting', 'Always kill_sandbox when done', topup_balance on 402, and 'retry or choose a smaller tariff' on 503. It also states when to pick each mode and tariff (e.g. 'pick plus or bigger for heavy pip installs', headless browsers need standard+). Alternatives and conditions are named rather than 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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose two valuable traits: the auth requirement ("Requires: token") and the fact that the response returns a `code` needed by other tools. It does not cover failure behavior, rate limits, or whether a created ticket is editable/deletable via close_ticket.

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 clauses, no filler: action, required/optional params, downstream workflow, and auth prerequisite. The follow-up tool chain is front-loaded right after the parameter summary, which is exactly what an agent needs next.

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 3-param creation tool with no annotations and no output schema, it covers auth, required inputs, and the key return value (the ticket code). The only gap is the absence of information about what a ticket looks like or how service_id mismatches are handled.

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

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

With schema coverage at 33%, the description must compensate, and it does: it labels `subject` and `message` as required and explains that `service_id` is optional and links the ticket to a specific VPS. The schema supplies the service code format example, so the pair together is nearly complete.

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 (open a support ticket) with the provider named, and it distinguishes itself from siblings by naming get_ticket, reply_ticket, and close_ticket as the downstream lifecycle tools. An agent can place this tool in the ticket workflow without opening any schema.

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

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

It states the required fields and that optional service_id ties the ticket to a VPS, and it explicitly routes the agent onward using the returned code. There is no explicit when-not-to-use or alternative (e.g., list_tickets for reading existing tickets), but the usage context is clear and actionable.

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

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

With no annotations, the description carries the full burden and does well: it enumerates exactly what the delegate can do (power/reinstall/console/hostname/rdns) and what they cannot (renew, cancel, change billing), plus the invitation-with-accept-link flow and owner-token requirement. It omits revocation semantics and rate limits, but the permission boundary disclosure is unusually rich.

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

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

Front-loaded with the core action and scope, then permissions, mechanism, and preconditions in quick succession. The parenthetical permission list is dense but earns its place; there is no filler or repetition.

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

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

For a 3-param mutation tool with no annotations and no output schema, the description covers action, permission boundaries, invitation flow, and authorization requirement. An agent has enough to call it correctly; only return-value expectations and post-invitation lifecycle are left implicit.

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

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

Schema coverage is only 33% (only service_id is documented), so the description must compensate and largely does: it clarifies email is the invitee's address, and that expires_days yields time-limited access. service_id is left entirely to the schema, but the description still adds meaningful semantics for the other two parameters.

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

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

Specific verb (Grant) plus resource (OPERATOR access to one of YOUR VPS) plus the mechanism (email invitation with accept link). An agent can immediately distinguish this from accept_delegation, revoke_delegation, and list_delegations 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?

States the precondition clearly: "Owner-only. Requires: token (owner)." It implies the use case (sharing VPS control without billing authority), though it doesn't explicitly name sibling tools like revoke_delegation or accept_delegation as alternatives or 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?

With no annotations the description carries the full burden and does well: it discloses the return value (`content` UTF-8 by default vs `content_base64`), the auth/runtime prerequisite, the 5 MB cap, and the context-bloat tradeoff of pulling base64. It doesn't cover failure modes (missing file, dead sandbox) but the core behavior is transparent.

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

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

Front-loaded with the core action and size constraint. Slightly repetitive, restating 'max 5 MB' and the get_download_url redirect twice, but the redundancy reinforces the key boundary and wastes little.

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

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

No output schema exists, so the description rightly explains the return shape (`content` vs `content_base64`). Combined with size limits, auth requirements, and the sibling alternative, an agent has everything needed to call this correctly.

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

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

Schema coverage is only 33%, so the description must compensate, and it does: it clarifies `path` must be absolute and that `as_text: false` returns `content_base64` while text is the default, plus names sandbox_id and its liveness requirement. This adds real meaning beyond the schema patterns.

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

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

States a specific verb and resource: read a SMALL file from the sandbox into the conversation. It draws an explicit boundary against the get_download_url sibling for large/binary files, so an agent can distinguish them without opening either schema.

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

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

Gives explicit when-to-use conditions (small files under 5 MB) and when-not (build artifacts, archives, binaries, anything big) with the named alternative (get_download_url). Prerequisite is stated: token + live sandbox_id.

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 entire behavioral burden and does so thoroughly: runs as root, shell operators are never filtered, synchronous timeout capped at 55 s, background returns a task_id killable via kill_task, and 404 means the sandbox expired. It even warns that a malformed JSON body yields a -32700 parse error rather than a firewall block.

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

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

Dense and front-loaded: purpose and return shape lead, followed by operational caveats and error recovery. Every sentence earns its place, though the multi-clause sentences and embedded troubleshooting make it heavier than strictly necessary.

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

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

There is no output schema, but the description spells out the return object (exit_code, stdout, stderr, timed_out, truncated, duration_ms) and the background task_id flow, covering both call modes end to end. Prerequisites, failure modes, and async polling 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 50%, and the description compensates with defaults not in the schema: cwd defaults to /root, timeout defaults to 30 s with a 55 s synchronous cap, and background switches the timeout semantics and return value. Only env is left to the schema, where it is already fully documented.

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 precise verb+resource (execute a shell command via bash -lc in a sandbox) and even names the exact return shape, so the agent knows exactly what it does. It does not differentiate from the sibling run_code, which also executes code in a sandbox, 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?

Strong operational guidance: use background: true for commands over 55 s and poll get_task, repeat with background on timed_out, and treat 404 as an expired sandbox to be recreated. It also states prerequisites (token + live sandbox_id). It never explicitly routes the agent between this and the sibling run_code, which is the one clear exclusion missing.

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 auth requirement ('Requires: token') and the meaningful behavioral linkage that order_vps draws down this balance automatically, which is genuinely useful context. It stops short of stating the return shape or any rate/pagination behavior, so it is adequate but not rich.

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

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

Two tightly written sentences with zero filler, front-loading what is returned before the dependency and auth note. Every clause earns its place.

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

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

For a zero-parameter read with no output schema, the description covers what is returned (balance and currency), the auth requirement, and the cross-tool dependency. The only minor gap is that the exact return shape isn't specified, but this is a low-complexity tool where that omission is acceptable.

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 schema to document and no parameter semantics to add. Baseline 4 applies; no description compensation is needed.

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: 'Return the account's prepaid credit balance and currency.' An agent can immediately tell this is a read of the balance, distinct from the write-oriented sibling topup_balance, without opening any schema.

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

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

It gives useful relational context by noting that `order_vps` spends from this balance automatically when sufficient, which hints at why an agent would check it. However, it never states explicit when-to-use/when-not conditions or names alternatives such as topup_balance, leaving usage largely 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 the description carries the full load, and it does so well: ttl default 15 min (60-3600 s), 2 GB ceiling, link is secret, scoped to one path, and dies with the sandbox. It omits error/failure behavior, which keeps it just short of exceptional.

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 what is returned, followed by how to use it, then constraints and expiry. Every sentence adds a distinct operational fact with no filler.

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

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

No output schema exists, yet the description explains what is returned (the URL), how to consume it (curl), and its lifetime/scope constraints. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is only 33%, so the description must compensate; it adds the ttl default and range and the path scoping constraint ('only for that path'). The path format (leading-slash pattern) is left to the schema, but the semantic meaning of each parameter is conveyed.

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

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

States a specific verb (Get), an exact artifact (a short-lived HTTPS link), and scope (streams ONE file from the sandbox), with concrete examples (build artifact, archive). This clearly separates it from siblings like download_file and get_upload_url.

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 strong context: requires token + live sandbox_id, the link only works while the sandbox runs, and it shows the exact curl invocation. It does not explicitly contrast with the download_file sibling, so routing is inferred 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?

With no annotations, the description carries the burden and does disclose real behavior: it is a status/usage read, it names the conditional fields only present for paused sandboxes (pause_reason, delete_after), and it states the token requirement. It stops short of covering error cases (unknown/expired sandbox) or freshness of the metrics.

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

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

A single dense sentence that front-loads the core purpose, then the return contents, then the prerequisite. Every clause carries information; the field lists are long but each item is a genuine return value rather than filler.

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

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

No output schema exists, so the description must describe returns and it does so thoroughly, covering both status fields and usage/billing fields. For a one-parameter read tool this is nearly complete, with only error/edge behavior 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?

There is a single parameter at 100% schema coverage, so the schema already documents sandbox_id including its pattern and an example. The description adds no format or semantic detail beyond implying 'one sandbox', 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 and resource ('Status of one sandbox') and scopes it to a single sandbox, which cleanly separates it from the plural sibling list_sandboxes and from mutation siblings like kill_sandbox/create_sandbox. It also enumerates the concrete fields returned, so an agent knows exactly what it gets.

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: you call it to inspect one sandbox's state and cost, and it names the prerequisite ('Requires: token'). It never states when to prefer it over list_sandboxes or how it relates to sandbox_pricing, so the agent must infer the routing.

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

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

With no annotations, the description carries the full burden and discharges it: it discloses the single human-gated step (crypto checkout_url), the auth model (one account, reusable token), that common errors come with fixes, that limits are documented, and the conditional behavior of `you_are_here` (only populated when authenticated). It also documents the cross-tool contract that every response carries `next_steps` and every error carries `error.fix`/`error.next` — information an agent cannot get from structured fields.

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

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

Front-loaded with the directive 'Call this FIRST', which is the highest-value information. The middle is one dense, dash-chained sentence, and the closing 'Requires: nothing. Call this first.' repeats the opening — mild redundancy, but each content clause adds a distinct fact.

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

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

No output schema exists, so the description must describe the return payload — and it does, naming the tool ordering, checkout URL, auth rules, error fixes, limits, and `you_are_here` fields. For a zero-parameter entry-point tool with no annotations, nothing an agent needs to call it correctly is missing.

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

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

Zero parameters, so there is nothing to disambiguate and the baseline is 4. The description correctly makes no parameter claims, avoiding noise.

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 and resource ('Returns the whole flow in one response') and enumerates what the payload contains: tool ordering for VPS rental and sandbox code execution, the crypto checkout step, auth rules, error fixes, limits, and the `you_are_here` block. No sibling tool in the list does anything comparable, so it is trivially distinguishable.

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?

'Call this FIRST' is stated up front and repeated, and 'Requires: nothing' removes any prerequisite ambiguity. The alternative path is implicit but unambiguous: this is the entry point, and every other tool is what you call afterwards.

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 does so well: it enumerates the state machine (running | done | failed | killed | timeout), defines the done flag, discloses the 8 MiB retention cap with older output dropped and reported in *_dropped, notes the token requirement, and advises polling cadence.

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?

Densely front-loaded: the return shape leads, followed by the offset protocol, then polling advice, retention, and auth. Every sentence carries actionable information with no filler.

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

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

There is no output schema, so the description must describe return values and it does (state, exit_code, stdout/stderr, done, dropped output). Combined with the schema's id patterns and the usage protocol, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 50% (task_id and sandbox_id documented, the two offset params are not), but the description compensates by explaining offset semantics — begin at 0 and advance using the next-offset values from the prior response. Minor friction: it names output fields (stdout_next_offset) rather than the input param names (stdout_offset).

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

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

States a specific verb+resource ('Status and NEW output of a background task') and immediately enumerates the returned fields (state, exit_code, stdout/stderr). This cleanly distinguishes it from siblings like kill_task, run_code, and exec_command.

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 usage context: start with offsets 0, then pass stdout_next_offset/stderr_next_offset, and poll every few seconds since each call is quick. It doesn't state explicit exclusions (e.g., when to stop polling or use kill_task instead), but the when/how-to-use guidance is clear.

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

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

With no annotations the description carries the full burden and does well: it discloses the return shape (full message thread), the meaning of the `author` field values (`you` vs `staff`), polling semantics, and the auth requirement ('Requires: token'). It omits error behavior for an invalid code and any rate-limit notes, so not 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?

Four short sentences, front-loaded with the core action and return content before the usage and provenance notes. Efficient, though the back half reads as a set of terse fragments rather than a flowing 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?

No output schema exists, so the description rightly describes what comes back (thread, author values) and the token requirement. It is nearly sufficient for a simple one-param read tool, with only error/invalid-code behavior left uncovered.

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 there is one required parameter, so the description must compensate. It adds provenance ('ticket code comes from create_ticket / list_tickets') but never specifies the code's format or example, leaving the schema to imply the string shape.

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

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

States a specific verb and resource — 'Read one ticket and its full message thread' — and the singular 'one ticket' distinguishes it from the sibling list_tickets. An agent can tell it apart from reply_ticket and list_tickets 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 says 'Poll this to see new answers,' giving a clear use context, and points to create_ticket / list_tickets as the source of the required code. It lacks an explicit when-not-to-use or a direct contrast with list_tickets, so it stops short of a 5.

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

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

With no annotations, the description carries the full burden and does so well: it explains that data is kept, that convert adds a public IP, that convert_to_nat drops the IP and refunds the unused difference, that shrink is impossible for vCPU/RAM/disk, and that the server must be active. It also previews the returned fields and what prorated_topup means.

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

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

Dense but front-loaded, with the core purpose first and the modes/output/constraints following. Heavy parenthetical use makes it a single run-on paragraph rather than scannable structure, but every sentence carries useful 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?

Without an output schema, the description still lists the returned fields (product_id, name, monthly, prorated_topup, mode) and explains the prorated charge semantics. Constraints and preconditions are all present, so an agent has everything needed to call and interpret this tool.

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

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

Only one parameter exists and schema description coverage is 100%, so the schema already documents service_id thoroughly. The description adds no syntax or format detail beyond the 'server must be active' precondition, making the baseline 3 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 a precise resource ('the plans this VPS can switch to IN PLACE with its data kept'), and names the three switch modes (resize, convert, convert_to_nat) that define the scope. This distinguishes it from list_plans (all plans) and change_plan (performs the switch) without needing their schemas.

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

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

Clearly says when the tool applies: the server must be active, options are in-place with data retained, and shrinking is explicitly not possible. It does not name change_plan as the follow-up action nor state alternative tools for other cases, but the context 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?

With no annotations, the description carries the full behavioral burden and delivers substantially: short-lived link, 2 GB ceiling, 95 MB per-request limit, offset-based chunking, response `next_offset`, the destructive 'offset 0 overwrites' behavior, and prerequisites (token + live sandbox_id). Gaps remain around TTL/link expiry semantics and failure modes, which keeps it from 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?

Purpose is front-loaded and the operational details are dense and mostly earned, but the trailing '≤95 MB per PUT; use ?offset for more' restates the earlier 'One request carries at most 95 MB' and the offset instruction, adding redundancy to an already long single paragraph.

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

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

For a multi-step chunked-upload tool with no output schema and no annotations, the definition covers the mechanics unusually well, including the `next_offset` return signal. Missing pieces are minor: the ttl parameter's meaning and what an expired or failed link yields are not addressed.

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

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

Schema coverage is only 25% (just sandbox_id), so the description must compensate. It explains `path` implicitly, maps 'up to 2 GB' onto max_bytes, and clarifies upload semantics, but `ttl` is only hinted at by 'short-lived' and never defined, and the 60–3600 range is undocumented in either place.

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 clause states a specific verb and resource: 'Get a short-lived HTTPS link to PUT ONE file into the sandbox at `path` (up to 2 GB)'. Scope and size bound are explicit, so the agent immediately knows this returns a URL for out-of-band upload rather than uploading content itself. It never names the sibling `upload_file` or any alternative, so it stops short of full sibling differentiation.

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 rich operational how-to (curl -fT, 95 MB chunks, ?offset ordering, offset 0 overwrites) which tells the agent *how* to consume the URL, and 'No base64 through this conversation' hints at the intended out-of-band scenario. However, it never states when to pick this over `upload_file` or any other transfer path, so alternative selection 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 carries the full behavioral burden. It discloses one useful trait — 'Requires: token' — but says nothing about rate limits, retention windows, whether the call is read-only, or how much data is returned. For an un-annotated read tool this is thin.

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

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

Two tight sentences, front-loaded with the resource and return categories, followed by the one constraint the schema doesn't carry. No filler and nothing that restates 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?

With no output schema and no annotations, the description is the only source for return shape and constraints. It names the metric families and the token requirement, which is helpful, but does not indicate whether `service_id` is effectively required despite the schema marking nothing required, nor what the response objects look 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?

Schema coverage is 50%: `service_id` is documented in the schema but `timeframe` only has an enum with no description. The description compensates by restating the enum values and, more importantly, supplying the default (hour), which the schema omits. That is real added value, so it holds at the baseline.

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 and enumerates exactly what it returns: time-series resource metrics (CPU %, memory, network, disk) for a VPS. This is clearly distinguished from the sibling get_vps_status, which reports state rather than time-series metrics, so an agent can tell them apart 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?

No when-to-use guidance, no alternatives, no exclusions. It mentions the default for `timeframe` (hour), but that is parameter semantics, not usage direction. An agent is left to infer that this is the tool for historic resource sampling versus get_vps_status for current state.

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 so richly: password shown ONCE, guaranteed to work only after boot completes, password_pending means call again, and the one-time reveal is not spent until a password is actually returned. It also explains ssh_ready/rdp_ready as live probes with 1-5 minute first-boot delay and the NAT internal-vs-external port firewall trap.

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

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

Purpose is front-loaded and nearly every sentence adds non-obvious operational detail, so little is filler. However it is a very long single block that mixes access, password, boot-timing, and firewall concerns without breaks, making it dense to parse.

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

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

With no output schema and no annotations, the description still defines the meaning of most return fields (password_pending, password_available, ssh_ready, internal_port, ready_note, retry_after_seconds, firewall_note) and the token requirement, leaving no material gap for correct invocation.

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

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

At 50% schema coverage the description must compensate, and it fully documents the undocumented `reveal` parameter: what it does, its side effects, and the distinction from password_available. service_id is covered by the schema, and the description reinforces that a plain numeric id is accepted.

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 ('Get full detail for one VPS') and enumerates exactly what comes back: status, specs, live VM state/uptime, and access info. It differentiates itself from siblings by naming list_vps, order_vps, get_vps_metrics and reset_password, so an agent can route correctly without opening another 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?

Explicit routing: poll this after order_vps to watch provisioning reach `active`; use reveal=true only to fetch the password; use reset_password ONLY if the password is lost. It also states when NOT to act ('do not reset, reboot or reinstall during that window') and what a typical non-error result looks like.

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 provided, the description carries the full burden and delivers: irreversibility, exactly what is destroyed (files, packages, background tasks, memory), billing consequences (per-second with 60 s minimum for ephemeral, per-started-hour for persistent), and the auth prerequisite ('Requires: 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?

The critical warning is front-loaded with strong emphasis, and every clause is information-bearing. The billing parenthetical is slightly dense, but it earns its place for a destructive operation.

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 no output schema, the description covers safety, data loss, billing, prerequisite action, and auth — nothing an agent needs before invoking it 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 sole sandbox_id parameter is fully documented in the schema, including its pattern and provenance. The description adds no parameter-level detail, 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?

The description states a specific verb (Delete) and resource (sandbox), and immediately scopes it ('running or paused'), letting an agent distinguish it from siblings like create_sandbox, get_sandbox, or kill_task 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?

It gives explicit actionable guidance ('download_file anything you need first') and states the tool applies to both running and paused sandboxes. It stops short of naming alternatives or a when-not-to-use condition (e.g., versus cancel_service), but the destructive-selection context is clear.

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

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

With no annotations, the description carries the full burden and does real work: it discloses the destruction scope (the task plus all processes it spawned), the blast-radius boundary (sandbox survives), the return value ("final state (killed)"), and the auth requirement. It omits irreversibility and error behavior for already-terminated tasks, which keeps it from a 5.

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

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

Three short sentences, front-loaded with the action and scope boundary, then the return value, then the requirement. No filler and every sentence carries distinct information.

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

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

With no output schema, the description supplies the return value ("final state (killed)") and the survival boundary, which is what an agent most needs before calling it. It stops short of stating failure modes or whether in-flight output is lost, a minor gap for a destructive two-param 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 100% and both parameters carry descriptive text with patterns and origin references, so the schema does the heavy lifting. The description adds only an auth note ("Requires: token") that is not actually a declared parameter, adding no semantic detail about task_id or sandbox_id.

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

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

States a specific verb and resource ("Stop a running background task and all processes it started") and immediately scopes it against the adjacent sibling by clarifying "The sandbox itself keeps running," which separates it from kill_sandbox.

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 clear context for when this applies (stopping a running background task) and implicitly rules out sandbox teardown, plus states the precondition "Requires: token." It does not, however, name an alternative tool explicitly or say what to do if the task is already finished.

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 behavioral burden. It usefully states 'Requires: token' and clarifies the nature of the access, but omits details such as pagination, return format, or explicit read-only safety. For a simple list tool, this is adequate but not rich.

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

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

One front-loaded sentence defines the resource and scope, followed by a compact requirements note. Every element earns its place with no filler.

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

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

Given zero parameters, no output schema, and no annotations, the description covers the essential purpose and auth requirement. It could optionally mention return format or ordering, but for a simple list call it is largely complete.

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

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

The tool takes zero parameters, so the baseline of 4 applies per the rubric. The description appropriately does not add parameter information that would be redundant or impossible.

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 (services delegated to you by other owners), and distinguishes itself from sibling list_delegations by emphasizing inbound delegation ('other owners have delegated operator access to you — the VPS you can operate but don't own'). An agent can tell this apart from tools that list delegations you created.

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

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

The description implies the tool's use case but provides no explicit when-to-use or when-not-to-use guidance. It doesn't mention alternatives like list_delegations or accept_delegation, leaving the agent to infer routing.

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

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

With no annotations, the description carries the full burden and does disclose the key behavioral facts: this is a read-style listing ("List"), it requires a token, and the result covers who has operator access plus delegation status. It omits secondary traits such as pagination or whether revoked delegations are included, which keeps it out of the top band.

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

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

A single front-loaded sentence covering scope, subject, and payload, followed by a compact auth requirement. No filler or repetition.

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

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

For a zero-param, read-only list with no output schema, the description covers scope, direction, returned content, and the auth prerequisite. The only gap is pagination/result-boundary 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?

The tool takes zero parameters with 100% schema coverage, so the baseline is 4 and there is no parameter detail the description could usefully 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?

States a specific verb (List) and resource (delegations) and pins the direction with 'outgoing ... you (the owner) have granted on your services', which cleanly separates it from the sibling list_delegated_to_me without needing the schema. It also previews the payload (who has operator access, status).

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 'outgoing / you (the owner)' framing gives clear context for when this tool applies and implicitly excludes the incoming-delegations case. It stops short of explicitly naming list_delegated_to_me as the alternative, so it is clear context rather than an explicit when/when-not 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?

With no annotations present, the description carries the full burden and does so well: it discloses the no-auth requirement, the BYOL licensing model for Windows, RDP/port specs, the response shape (plans[], plans[].promo, meta.promotions), and detailed promo mechanics including auto-application, renewal-at-regular-price, and which plans are excluded.

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 usage are front-loaded and efficient, but the closing PROMO block is dense with dates, dollar figures, slugs, and edge-case exclusions that read more like marketing copy than selection guidance. It is not wasteful enough to be a 2, but it exceeds what an agent needs to choose and call the tool.

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

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

With no output schema and no parameters, the description compensates by explaining the returned structure (plans[], plan_id for monthly/annual, promo fields, meta.promotions). Nothing an agent needs to invoke and interpret the tool 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 the baseline is 4 and there is nothing to disambiguate. The description correctly adds no parameter guidance because none is needed.

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 all available VPS plans (catalog) with pricing, specs and the OS images') and enumerates the two plan families (Linux NAT/dedicated IPv4, Windows Server 2022 BYOL). It is immediately distinguishable from siblings like list_vps (instances) and order_vps (purchase).

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 'Use this first to pick a `product` slug and an `os_id` for `order_vps`', naming the downstream tool and the reason to call this one first. It also states 'No authentication needed' / 'Requires: nothing', removing ambiguity about prerequisites.

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 provided, so the description carries the behavioral burden. It discloses that both running and paused sandboxes are returned, includes mode, tariff, state, and expiry fields, and states the token requirement. However, it does not cover pagination, rate limits, or what happens for accounts without sandboxes. For a read-only list tool, this is adequate but not rich.

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

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

Single sentence, front-loaded with the core action and scope. No waste. The auth note is short and placed at the end.

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 annotations and no output schema, the description should do more to help the agent understand the return shape or when to prefer this over get_sandbox. It mentions the listed fields, which partially compensates. For a simple list tool it is minimally complete, but misses behavioural context like pagination.

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?

Parameter count is 0, so by the rubric the baseline is 4. The description adds no parameter info because there are none. It does note the token requirement, which is meta-behavior rather than a schema parameter, so it doesn't lower the score.

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), the resource (sandboxes), and adds useful scope details — running and paused, mode, tariff, state, expiry. Differentiates from get_sandbox (single) by listing all. Lacks explicit distinction from siblings like list_vps or list_plans, but the resource name makes that clear.

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 tool versus get_sandbox, create_sandbox, or other list tools. The 'Requires: token' is an auth note, not a usage guideline. The agent has to infer the scenario.

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 usefully discloses the auth prerequisite ('Requires: token') and explains the meaning of the last_message_author value, which is real behavioral context. It stops short of pagination, ordering, or result-size behavior for a listing 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 compact sentences front-load the resource and scope, followed by a terse prerequisite. Nothing is wasted, though the 'Requires: token' fragment is clipped enough to read as a note rather than prose.

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 list tool with no output schema or annotations, the description covers the core return shape (status, last-message info, author semantics) and the auth requirement. Missing only pagination/result-count behavior, which is a minor gap at this complexity.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to clarify and it does not mislead about inputs. No additional parameter meaning is needed.

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 your support tickets') and previews the returned fields (status, last-message info), so the agent knows exactly what this retrieves. It does not explicitly distinguish itself from get_ticket, but list-vs-single-fetch 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?

Usage is implied by the verb 'list' rather than stated: there is no guidance on when to use this instead of get_ticket, nor any mention of filtering or paging behavior. An agent can infer the use case, but nothing is made 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?

With no annotations, the description carries the full burden and does well: it discloses the filter semantics (which statuses appear), the auth prerequisite ('Requires: token'), and the downstream contract (the returned `id` feeds management tools). It does not say anything about ordering or pagination, but for a small account-scoped list with no parameters that is a minor omission.

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, zero waste, and the most decision-relevant information (what is included, and what to do with the results) is front-loaded. The negative rule about missing servers is placed exactly where it prevents a mistaken follow-up call.

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 exist, so the description must stand alone; it covers scope, exclusions, auth, and downstream usage of the returned identifier. It stops short of describing the shape of each list entry (hostname, status, plan), which an agent building a follow-up call might want, but nothing required 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 the baseline is 4. The description does usefully clarify that the `id` field in the response maps to the `service_id` parameter of the management tools, which is the only parameter-related meaning an agent needs here.

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 (the account's ACTIVE VPS services) and then enumerates the exact statuses included (active, provisioning, suspended) and excluded (deleted/cancelled). This distinguishes it cleanly from siblings like get_vps_status, which operates on a single server rather than enumerating the account's fleet.

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 the result ('Use the `id` as `service_id` for the management tools') and gives a negative rule ('If a server is missing from this list it has been deleted — do not query its status or try to manage it'). This is genuine when-to-use/when-not-to-use guidance, not 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?

With no annotations, the description carries the full burden and does so: it discloses the return value (bearer token), its lifetime and default (1 year, or token_ttl_days), session-scoped caching behavior, the required precondition, and a typical failure mode (401 invalid credentials). This is substantially more than the structured fields provide.

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

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

Front-loads the core action and return value before prerequisites, which is good ordering. However, the register_account/no-password caveat is stated twice (in the NOTE and again in the 'Typical error' sentence), which is mild 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?

No output schema or annotations exist, yet the description still conveys the return token, its expiry semantics, the prerequisite, and the failure case. Nothing essential 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?

Schema coverage is only 33% (token_ttl_days alone is documented). The description compensates by explaining token_ttl_days' default of 1 year and by clarifying that password must have been established via set_password, adding meaning beyond the bare schema. email and password remain self-evident from their types.

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 (log in) plus the credential resource, and clearly differentiates itself from register_account, set_password, and refresh_token in the sibling set. An agent can select it without ambiguity.

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 covers the when-not case (register_account accounts have no password, so keep using the register token) and names the alternative action (call set_password while authenticated to enable later logins). The 'Requires: a password set earlier' line states the precondition directly.

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 so richly: it discloses the balance-vs-invoice behavior, the 409 location_unavailable outcome (nothing charged, `available` populated), 422 semantics, the Windows-plan quirks (fixed image, ignored ssh_key, RDP/BYOL), and the automatic promo application. These are non-obvious behavioral traits an agent could not infer from the schema.

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

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

Front-loaded with the core action and logically segmented with parameter notes and a bulleted response branch. It is long, though, and the PROMO block is verbose promotional detail that reads as tangential to correct invocation, slightly diluting the otherwise tight structure.

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

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

There is no output schema, so the description must explain returns, and it does: paid_from_balance, invoice.id, checkout_url, promo, and the resulting status flow. Combined with error handling and prerequisites, an agent has everything needed to call and follow up 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 only 14%, so the description must compensate, and it does: it defines product (plan slug from list_plans), os_id (image id for that plan), ssh_key (public key, key-based root login), location (de/fi, auto-placement if omitted), period (default month vs year), and plan_id. Every parameter gains meaning beyond the bare schema types.

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 ('Order a VPS') and immediately differentiates itself from siblings by pointing at list_plans, get_vps_status, pay_invoice, and topup_balance for the related steps. An agent can tell this is the provisioning entry point versus the status/payment tools 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 covers when to use it and what to do next via response branching (paid_from_balance true → poll get_vps_status; false → pay_invoice OR topup_balance then re-order). It even names the prerequisite (token + balance) and the fallback path when balance is insufficient.

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 deliver real behavioral context: it returns a checkout_url, settlement and VPS provisioning happen asynchronously after on-chain confirmation, and a human must complete payment. It omits idempotency/expiry behavior and what happens if the invoice is already paid, which keeps it from a 5.

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

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

Three dense sentences with zero filler; the core action and the returned checkout_url are front-loaded, and the async-settlement detail follows logically.

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

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

There is no output schema, and the description compensates by explaining the return value (checkout_url) and the downstream effect (invoice settles, VPS provisions). Gaps remain around error cases and repeat invocations, but the essentials for correct invocation are 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 description coverage is 100% and the schema already states the exact-format rule and the '2RUAWV4' example, so the description's restatement of that guidance adds little beyond the structured field. Baseline 3 is appropriate where 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?

States a specific verb and resource ('Initiate payment for an owned, unpaid invoice') and narrows the scope with two qualifiers (owned, unpaid), which rules out most misuse. It does not name a sibling such as topup_balance or order_vps to contrast against, 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?

The precondition 'owned, unpaid invoice' and the requirement 'Requires: token' give clear context for when this tool applies, and the human-pays-checkout_url note clarifies the manual step. There is no explicit statement of when NOT to use it or which sibling to reach for instead.

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

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

No annotations exist, so the description carries the full burden. It does add genuinely useful behavior: the 'Requires: token' auth prerequisite and the concrete 409-during-first-boot failure mode with a wait-and-retry remedy. However, it omits the disruptive nature of stop/reboot and any reversibility or confirmation guidance for a mutation tool.

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

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

Two short sentences, front-loaded with the action set followed by the auth requirement and the single most likely failure mode. No filler or restated boilerplate.

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-output-schema mutation tool the description covers the action vocabulary, auth requirement, and a known error path, but it leaves open whether service_id is needed despite being non-required in the schema and what state changes stop/reboot cause. Adequate but with gaps an agent would notice at call time.

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%, so the schema documents service_id (including its format and the numeric-id fallback) but not the action enum. The description restates the three action values, which matches the schema enum rather than extending it, and adds no semantics for service_id or for why it appears optional in the schema when it is practically required.

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

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

States a specific verb and resource ('Power-control a VPS') and enumerates the exact operations (start/stop/reboot), which is more than the title's generic 'Power control'. An agent can immediately tell this apart from read-only siblings like get_vps_status or get_vps_metrics.

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

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

Usage is implied by the enumerated actions, but there is no explicit when-to-use vs. when-not guidance and no sibling named as an alternative (e.g. reinstall_vps for a full rebuild). The 409-retry hint is operationally useful but is error handling, not usage routing.

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

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

With no annotations present, the description carries the full burden and does so richly: the old token is REVOKED immediately, default lifetime is 1 year, the new token is auto-applied inside the MCP session but must be saved for raw HTTP, and the X-Token-Expires-At header plus 30-day warning are documented. It also states the precondition (a valid, non-expired 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?

Front-loaded with the core exchange action and mostly dense, but the revocation fact is stated twice ('REVOKES the old token immediately' and again 'The old token is revoked'), which is redundant.

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

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

With no annotations and no output schema, the description covers return values (token + token_expires_at), preconditions, session behavior, and error path. An agent has everything needed to call it correctly.

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

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

Schema coverage is 0%, so the description must compensate, and it does: it gives expires_in_days its default (1 year) and valid range (1-1825), which the bare integer schema with only min/max does not convey in prose.

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

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

States a specific verb+resource: 'Exchange the CURRENT bearer token for a new one'. It distinguishes itself from the nearest sibling by naming 'login' as the fallback path for expired tokens, so an agent can tell it apart without opening either schema.

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

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

Explicit when-to-use ('before it expires'), when-not ('An already expired token cannot be refreshed'), and the alternative ('log in again (login) or create a token in the cabinet'). Nothing about 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?

With no annotations, the description carries the full burden and does so well: it discloses the return value (a bearer token), its lifecycle (reusable until token_expires_at, 1 year default, not single-use), session-internal auto-remembering, raw-HTTP persistence caveats, prerequisites (nothing), and a typical error (422). This is rich behavioral context beyond a bare 'create account'.

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

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

Front-loaded with the core action and inputs, then token-handling guidance. It is longer than average but most sentences earn their place (token reuse, curl persistence, error recovery). Minor redundancy around the token not being single-use 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?

For a registration tool with no annotations and no output schema, the description covers the crucial account-creation semantics, token lifecycle, session behavior, and error recovery paths. An agent has everything needed to call it correctly and handle the aftermath.

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

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

Schema coverage is only 25% (only token_ttl_days documented), so the description must compensate; it names the three required fields and adds real meaning to email (must be a controlled, non-reserved address) and reinforces token_ttl_days range (1-1825, default 365). It could say more about first/last name constraints, but it meaningfully supplements the sparse 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 ('Create a NEW EQVPS customer account') and names the inputs (first_name, last_name, email). It is clearly distinguishable from siblings like login, refresh_token, and set_password, which it references directly.

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

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

Explicitly says when NOT to use it ('Never call register_account again to "get a new token": that creates another, empty account') and routes the agent to alternatives (refresh_token before expiry, login/saved token on 422 email already registered). The when-to-use-vs-alternative guidance is unusually thorough.

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 delivers: irreversible data loss, mandatory human confirmation, the confirm-token protocol, required auth (token), and asynchronous provisioning with a polling instruction. This is exactly the behavioral context an agent needs before invoking a destructive tool.

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

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

The critical warning is correctly front-loaded, but the description is repetitive: 'all data is lost' and 'Destroys all data' bookend the text, and confirm/token requirements are stated twice. Trimming the duplication would tighten it without losing information.

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

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

For a destructive, async, no-output-schema tool with zero annotations, the description covers safety, prerequisites, input sourcing, and the polling follow-up. It could note what the async kickoff returns (e.g., a task id for get_vps_status), but overall it is complete enough to call correctly.

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

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

Schema coverage is only 33% (only service_id is described in-schema), so the description must compensate. It explains os_id's source (list_plans) and confirm's accepted values (exact hostname from get_vps_status or 'DELETE'), covering both undocumented required params meaningfully.

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 and outcome: 'Wipes and reinstalls the VPS with the given OS image.' It also distinguishes scope (full OS reinstall vs. other service operations) clearly enough that an agent won't confuse it with change_plan or power_vps.

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 strong precondition guidance: confirm must be the exact hostname or 'DELETE' and the agent must explicitly confirm with the human before calling. It also routes input sourcing (os_id from list_plans, hostname from get_vps_status). It does not name alternative tools for non-destructive paths, so it stops short of a 5.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the auth requirement ('Requires: token'), which is a small credit, but says nothing about visibility of the reply (customer-facing vs internal note), notification side effects, or whether the ticket must be open. For a write operation with zero annotation coverage this is thin.

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

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

Two short sentences, zero waste, with the core action front-loaded and constraints following. Nothing is padded or repeated.

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?

A mutation tool with no annotations, no output schema, and 0% parameter description coverage. The description omits what success/failure looks like, whether an open ticket is required, and the nature of the reply — gaps an agent would need to guess at.

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. It explains where ticket_code comes from (create_ticket / list_tickets / list_tickets), adding real meaning, but the message parameter (format, length, whether markdown is allowed) is left entirely undocumented.

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

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

States a specific verb+resource ('Post a reply on one of your tickets'), which is clearly distinct from siblings like get_ticket, close_ticket, and create_ticket. It does not explicitly name those siblings as alternatives, but the action is unambiguous.

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

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

'Use the ticket code from create_ticket / list_tickets' tells the agent where the required identifier comes from, which is genuinely useful routing. However, there is no when-to-use vs when-not guidance (e.g., replying to a closed ticket, or reply vs. close), so usage 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, the description carries the full burden and does so well: it discloses that the change applies immediately via guest-agent with no reboot, takes ~10-30s, invalidates the OLD password, and that the new password is NOT in the response and must be read once via get_vps_status (also emailed). It also states the required confirm gate. This is unusually rich behavioral context.

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

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

Front-loaded with the core action and effect, then constraints. However, the closing "Requires: token + confirm (hostname or DELETE). Only if the password is lost." restates the confirm requirement and the only-if-lost rule already established earlier, adding mild 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 destructive mutation with no output schema, the description covers the safety gate, effect timing, and where the resulting credential appears. Nothing an agent needs in order to call it correctly and recover the new password 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 50% (confirm is undocumented in schema), and the description compensates by defining confirm as the exact hostname (from get_vps_status) or 'DELETE'. service_id is already documented in the schema with an example, so the description adds the one missing piece without redundant detail.

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 ("Rotate the root password") and immediately scopes the effect on the LIVE VM. It also implicitly distinguishes itself from the sibling set_password by framing this as the lost-password recovery path. An agent can tell what it does and when it differs from alternatives.

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 to use it ONLY if the password was lost, and gives a concrete negative case (a fresh order where SSH is slow — instead poll get_vps_status with reveal:true). It also states the human-confirmation prerequisite and the confirm-value requirement. When/when-not/alternative are all present.

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

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

With no annotations, the description carries the full burden, and it does disclose meaningful behavior: the other side is notified (a side effect), a token is required (auth), and both privileged callers are named. It omits error behavior and whether revocation is reversible or idempotent, so it is strong but not exhaustive.

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 with the core action front-loaded, then side effect, then id sourcing and auth. Every sentence carries distinct information and nothing is padded.

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

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

For a one-parameter mutation tool with no annotations and no output schema, the description covers who may invoke it, the required auth, the notification side effect, and how to find the id. The remaining gap is failure/idempotency behavior, which an agent would need for full confidence.

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 delegation_id parameter is undocumented in the schema, but the description explains that it is the delegation's id and tells the agent where to source it (the list tools). That adds genuine meaning beyond the bare integer type, though it gives no format or validity nuance beyond exclusiveMinimum.

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 (delegation) scoped by id, and clarifies the two authorization modes (owner revoking access vs. delegate declining). This distinguishes it clearly from siblings like accept_delegation and delegate_service.

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 the agent to list_delegations / list_delegated_to_me to obtain the required id, which is real usage guidance rather than pointer-free text. It does not state when not to use it or how it differs from accept_delegation beyond the inherent opposite action, so it stops short of 5.

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

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

With no annotations, the description carries the full burden and does so richly: code is passed on stdin so it cannot read stdin, per-stream output cap of 1 MiB, files and installed state persist within a sandbox, billing continues while a background task runs, and token + live sandbox_id are required. These are exactly the behavioral traits an agent cannot infer from the schema.

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 return shape, then parameters, then the LONGER JOBS escape hatch, then constraints and prerequisites. It is long but every clause adds actionable information, and the 'Typical:' line gives a compact remedy for the most common failure.

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?

A six-parameter mutation-like tool with no output schema and no annotations is fully covered: return values, background lifecycle, persistence, billing, limits, and auth prerequisites are all stated. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 50%, and the description compensates by mapping language values to versions (Python 3.12, Node.js 22, bash) and explaining timeout's default/max split between sync and background modes, plus the stdin constraint on code. env is left to the schema, which documents it, so this is strong but not exhaustive.

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

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

States a specific verb+resource ('Run a code snippet inside a sandbox') and immediately names the return shape {exit_code, stdout, stderr, timed_out, truncated, duration_ms}. It distinguishes itself from siblings by pointing to exec_command for package installs and get_task/kill_task for background polling.

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?

Explicit routing: install packages with exec_command first, use get_task with returned offsets to poll, kill_task to stop, and re-run with background: true when a job hits the 55 s synchronous ceiling. Includes the concrete 'timed_out after 55 s' trigger that selects the alternative.

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 provided, the description carries the full burden and does disclose auth behavior ('No authentication needed', 'Requires: nothing'), operational limits (55 s synchronous exec, 5 MB transfers), and supported runtimes. It does not mention whether results are static/cached or what the response shape is, but for a public reference tool this is solid disclosure.

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

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

The content is a single dense run-on sentence crammed with per-tier CPU/RAM/disk figures and a trailing SDK advertisement. The tier table is data the tool itself should return, so much of the text does not 'earn its place' in a description, though it is front-loaded with the core tiers.

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, no-output-schema informational tool, the description adequately conveys what the agent will get back: tier specs, pricing model, billing cadence, and execution limits. It is reasonably complete, with the only redundancy being tier data that likely duplicates the tool's own output.

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

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

The tool takes zero parameters, so the baseline of 4 applies; there is no parameter surface that the description needs to explain 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?

The description makes clear this is an informational pricing/limits lookup for the sandbox service, enumerating the tiers and resource specs it covers. However, with many sandbox siblings (create_sandbox, get_sandbox, list_sandboxes, exec_command), it never explicitly distinguishes itself as the read-only pricing reference rather than an action on a sandbox.

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 guidance on when to call this versus alternatives like list_plans or get_started, and no conditions or exclusions are stated. The only usage-adjacent note is 'Requires: nothing,' which describes prerequisites but not invocation context.

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

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

With no annotations, the description carries the full burden and delivers: it explains the mechanism (guest agent; hostnamectl + 127.0.1.1 line on Linux; rename on Windows), the delayed Windows effect with the `reboot_required: true` response field, the atomic failure mode (409 changes nothing), and an explicit non-impact list (password, SSH host keys, files untouched). This is exactly the behavioral context an agent needs before mutating a host.

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

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

Information-dense and reasonably front-loaded, leading with the action and format before mechanism and failure modes. The parenthetical platform detail is long but each clause carries distinct operational meaning, so little is wasted.

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

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

There is no output schema, yet the description still discloses the one return field that matters (`reboot_required: true` on Windows) and covers prerequisites, failure codes, and side-effect boundaries. Nothing material an agent needs to call this correctly is missing.

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

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

Schema coverage is 50%; the undocumented parameter is the required `hostname`, and the description compensates by stating it must be 'a valid DNS name'. The other parameter (service_id) is already documented in the schema, so the description adds the one piece of semantics the schema omits.

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 ('Set the VPS hostname') and immediately qualifies the required format ('valid DNS name'). No sibling tool touches hostnames, so the purpose is unambiguous 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?

Gives explicit prerequisites ('server must be running with its guest agent active', 'Requires: token, server running') and the failure condition plus remediation (409 agent_unavailable → start the server / wait for boot). It never names an alternative tool, but none exists for this operation, so the gap is minor.

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 well: it discloses the auth requirement ('Requires: token'), the one-shot nature, the lack of a current-password requirement on first use, and the 409 error on repeat invocation. It falls short of 5 because it cites a 'change-password' tool that does not appear in the sibling set, and it does not say whether setting a password affects the existing bearer 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?

Dense and front-loaded: the target account and the core purpose come first, followed by constraints and errors. The 409 condition is stated twice (mid-description and again as 'Typical error'), which is mild redundancy that costs a point.

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

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

For a one-parameter mutation with no output schema and no annotations, the description covers auth, error behavior, constraints, and the recovery rationale. Minor omissions remain around the fate of the existing token and the missing 'change-password' sibling, but nothing essential to invoking it correctly is absent.

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

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

Schema coverage is 0% and the single parameter has no description, so the description must compensate. It does so by adding a composition rule not present in the schema ('min 8 chars, letters+numbers') and by clarifying that no current password is needed. It could go further by stating format expectations (e.g. hashing, allowed character set), so 4 rather than 5.

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

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

States a specific verb+resource ('Set a password for THIS account') and immediately scopes the target by credential ('the one your bearer token belongs to'). It is clearly distinguishable from sibling tools like login, reset_password, and register_account, which the description explicitly references.

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 explicit when-to-use ('Call this ONCE to enable email+password login as a recovery method'), when-not ('If a password was already set, this returns 409 (use change-password instead)'), and an alternative path. The agent does not need to infer the trigger condition.

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

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

With no annotations present, the description carries the full burden and delivers: the balance is credited asynchronously only after on-chain confirmation, min/max are enforced server-side, only one unpaid top-up may exist concurrently, and token auth is required. These are exactly the non-obvious behaviors an agent could not infer from the schema.

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 opening is well front-loaded, but the sentence 'The balance is credited automatically once the on-chain payment confirms' is restated at the end as 'the balance is credited automatically after confirmation' — a redundant sentence that dilutes an otherwise tight 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?

For a single-parameter, no-output-schema tool, the description supplies everything needed to call it correctly: the input's units, the auth requirement, the human-in-the-loop payment step, and the async crediting outcome that substitutes for a return-value contract.

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% (only 'number, exclusiveMinimum 0'), and the description compensates by specifying that amount is in account currency (USD) and that bounds are enforced server-side. It does not state the actual min/max values, but the units and validation semantics are a genuine addition 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+resource ('Create a top-up invoice') and names the concrete artifact returned ('checkout_url', PayRam crypto checkout), which separates it cleanly from siblings like get_balance, pay_invoice, and order_vps.

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 real operating conditions: a HUMAN must pay the checkout_url in crypto, only one unpaid top-up may exist at a time, and a token is required. It never explicitly compares itself to alternatives such as get_balance or pay_invoice, so the routing guidance is implicit 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?

No annotations, so the description carries the full behavioral burden. It discloses that no money moves, that an immediate cancellation is irreversible, the authentication/prerequisite requirements, and the typical 409 nothing_to_undo error.

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

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

Front-loads the core effect ('Keep a VPS...') and then layers in the exact scope, side-effect behavior, prerequisite, and error in a compact paragraph. Every sentence contributes relevant operational detail.

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

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

Given no annotations, no output schema, and full schema coverage for the lone parameter, the description supplies everything an agent needs: scope, prerequisites, irreversibility boundary, state-check tool, and failure mode.

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 (service_id), and schema description coverage is 100%; the schema already explains the accepted service code format and numeric-id fallback. The description adds no parameter-level semantics beyond that.

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 (undo) and resource (scheduled end_of_period cancellation), and distinguishes itself from cancel_service by describing the opposite operation and the exact cancellation type it applies to. An agent can tell it apart from siblings without opening schemas.

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

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

Explicitly states when it works (scheduled end_of_period cancellation) and when it cannot (immediate cancellation, VM destroyed at once). It also points to get_vps_status as the way to check can_undo, leaving little 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?

With no annotations, the description carries the full burden and does disclose key traits: parent directories are auto-created, there is a hard 5 MB inline limit, and a token plus live sandbox_id are required. It does not say whether an existing file is overwritten or what is returned, which leaves a real gap for a write 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?

Dense, imperative and front-loaded: the core action, the alternative-parameter rule, the limit and the fallback path all appear in the first three clauses. The 5 MB cap is stated twice ('Limit 5 MB per file inline' and trailing 'Max 5 MB'), a small 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 5-param write tool with no output schema and no annotations, the definition covers prerequisites, size limits, encoding choice and the escalation path. The main omission is the return value / overwrite behavior, which matters for confirming a successful upload.

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 20%, so the description must compensate, and it largely does: content vs content_base64 is disambiguated by encoding, path is described as absolute (matching the ^\/ pattern), and mode is exemplified as '755'. Only sandbox_id semantics are left to the schema description.

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

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

States a specific verb and resource ('Write a file into the sandbox at an absolute path') and pins down the scope (inline, 5 MB cap). It also names the sibling get_upload_url as the route for larger files, so an agent can separate it from download_file/get_upload_url 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?

Explicit when-to-use routing: use this for files up to 5 MB, and 'for bigger files call get_upload_url and PUT the bytes to the link'. Prerequisites are stated ('Requires: token + live sandbox_id'), and the 'no base64 through this chat' note excludes a misuse path.

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 it does disclose the auth requirement ('Requires: token') and the read-only nature implied by 'Return.' It does not state what happens on an invalid/expired token, which is the most likely failure mode for a verification tool.

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

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

Three short sentences with no waste, front-loaded with the core action and its return shape, then the use case, then the prerequisite.

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

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

No output schema exists, and the description compensates by enumerating the returned fields. For a zero-param read tool it is nearly complete, but it omits error/expiry behavior that matters for its stated token-verification purpose.

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

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

Zero parameters, so the baseline is 4. The parenthetical (id, name, email) describes return fields rather than inputs, but there is nothing input-side to document.

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 ('Return the authenticated account profile') and enumerates the returned fields (id, name, email). An agent can distinguish this from siblings like login, register_account, or refresh_token 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?

Gives an explicit use case: 'Use to verify the bearer token is valid.' This tells the agent when to reach for it, though it names no alternative (e.g., refresh_token) or exclusions for when this is the wrong choice.

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