EQVPS — VPS and code sandboxes for AI agents

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

Annotations declare readOnly=false, idempotent=true, destructive=false, and the description is consistent with these while adding real context: the auth requirement as the invited email, the resulting operator access, and the important note that no new token is returned so the caller keeps its own. It doesn't cover reversibility or rate limits, keeping it below 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?

The action is front-loaded and the sentences are short, but the closing 'Requires: token of the invited email' restates the opening sentence, 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 single-parameter tool with full schema coverage, existing annotations, and no output schema, the description supplies the preconditions, effect, and token-rotation behavior an agent needs. Nothing critical is missing, though it could note reversibility or error conditions.

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 token parameter is documented in detail in the schema (long random string after `token=`). The description reiterates 'token of the invited email' but adds no syntax or format meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (accept) and resource (delegation invitation) and explains the effect: it grants operator access to your own account. This clearly distinguishes it from sibling tools like delegate_service, list_delegations, and revoke_delegation.

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 precondition ('Requires being signed in as the invited email address') and identifies the required input source (the token from the invite link). It does not explicitly name alternatives or when-not-to-use, 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?

Annotations already flag destructiveHint=true, but the description goes well beyond them: it explains that immediate permanently destroys the VM and all data, that end_of_period causes no data loss now, that immediate requires confirm=hostname, and that unused paid time is refunded. It omits only details like whether the refund is automatic vs. queued and any latency before destruction takes effect.

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?

Safety-critical information is front-loaded and every sentence carries real instruction. It is dense with parentheticals and back-references ('refund as above', 'see refund_amount'), which slows scanning slightly for an otherwise high-value block of text.

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, irreversible operation with no output schema, the description supplies prerequisites (token + reason, plus confirm for immediate), the refund behavior and where to read it in the response, the state check via get_vps_status, and the recovery paths. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds relational meaning the schema cannot: that confirm is only meaningful together with type=immediate, that its value must be the exact server hostname sourced from get_vps_status, and that the response carries refund_amount. This is genuine value beyond the field-level descriptions.

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

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

States a specific verb (cancel) on a specific resource (a VPS) and immediately distinguishes the two modes, end_of_period vs immediate. It also names sibling tools it interacts with (get_vps_status, undo_cancel), so an agent can tell it apart from those 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?

Gives an explicit default recommendation ('Use end_of_period unless you explicitly intend to wipe the server now'), names the alternative tool for reversing a scheduled cancellation (undo_cancel), and even prescribes the handling for the typical 409 cancellation_already_scheduled response.

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

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

Annotations only give destructiveHint/idempotentHint; the description goes far beyond by disclosing the in-place semantics, the single ~1 min reboot, immediate prorated charging from prepaid balance, refund behavior for convert_to_nat, and the full 402/409/422/202 error and queueing model with a 24h fulfillment window. This is exactly the behavioral context an agent needs for a destructive, non-idempotent 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?

Front-loaded with the core action, but the 202 queued behavior is explained twice in near-identical wording ('If the server's host has no free room... 202 with queued: true' then 'No room on the server's host → 202 queued (paid, applied automatically, usually within 24 hours)'). That duplication pads an otherwise dense but single-topic 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 mutation tool with no output schema, the description covers charges, refunds, reboot count, queue fallback, the response fields (charged, unused_credit, new_cost), and all typical error codes. Nothing material an agent needs 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 100%, so the baseline is 3; the description adds genuine meaning by tying `target_plan` to get_upgrade_options' options[] and by explaining the charging/refund semantics attached to `confirm` and the convert_to_nat variant. It does not add syntax details beyond the schema, so it stays below a 5.

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

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

States a specific verb and resource with scope ('Switch a VPS to another plan IN PLACE — files and the OS are kept'). It is clearly distinguishable from siblings like get_upgrade_options (which supplies the target), reinstall_vps, 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?

Explicitly routes the agent to get_upgrade_options for `target_plan`, names convert_to_nat as a variant behavior, and states the failure conditions (422 not an upgrade, 409 upgrade_queued). When-to-use and prerequisites (token + balance + confirm) are all spelled out.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the mutation/idempotency profile is covered structurally. The description adds one genuinely new fact beyond the annotations — "Requires: token" — but says nothing about whether closing is reversible or terminal.

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 the optionality caveat is placed before the code-sourcing hint. Efficient, though the inline backticks and em-dash aside make it slightly choppier than it needs to be.

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

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

For a low-complexity, single-object mutation with a fully documented schema and annotations covering safety and idempotency, the description is nearly complete. The one remaining gap is what the agent should expect after closing (terminal state, whether the ticket can be reopened).

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

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

Schema description coverage is 100%, so the schema already documents all three parameters including the 1–5 rating range, optionality and the 2000-character comment limit. The description only restates the optionality of rating/comment, adding no new syntactic or semantic detail; 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+resource ("Close one of your tickets") that an agent can clearly distinguish from get_ticket, reply_ticket and list_tickets. However, it never explicitly contrasts itself with those siblings, so it stops short of the 5-level 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?

Gives clear context: it tells the agent where the ticket code comes from (create_ticket / list_tickets) and clarifies that closing does not require a rating. It does not, however, state any when-not-to-use condition or name a fallback 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?

Annotations only say destructive/non-idempotent/non-readonly; the description goes far beyond by disclosing billing models per mode, the 60 s minimum, auto-deletion after idle_timeout, persistent pause-on-empty-balance with 14-day snapshot retention, capacity failures, and auth/balance prerequisites. That is exactly the lifecycle and cost context an agent needs before committing.

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 the sandbox is, then mode, then tariff, then failure handling – a sensible order with no filler. It loses a point for repetition: the price floor, minimum 60 s, prepaid-balance note and 402 error are each stated twice, and the trailing 'Requires/Typical errors' recap duplicates earlier sentences.

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

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

No output schema exists, yet the description explains the response shape (state/ready and the 'starting' case), all error paths, cost implications and cleanup obligations. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is already 100%, so 3 is the baseline, but the description adds real semantics: per-second vs per-hour billing, ttl caps by mode, idle_timeout defaults and its persistent-only exemption, and a full tariff table with vCPU/RAM/disk and hourly prices tied to workload types. This meaningfully exceeds the schema text.

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

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

Opens with a specific verb and resource: 'Start an isolated Firecracker microVM sandbox', plus runtime contents (Linux, Python 3.12, Node 22, git, curl) and network posture. It is unmistakably distinct from get_sandbox, list_sandboxes, kill_sandbox and run_code.

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 follow-up routing: call get_sandbox if state is 'starting', 'Always kill_sandbox when done', topup_balance on 402, retry-or-smaller-tariff on 503 capacity. It also advises which tariff to pick for heavy pip installs and headless browsers, though it never explicitly states when not to create a sandbox (e.g. versus reusing an existing one).

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false. Beyond those, the description adds two things the annotations do not: the auth requirement ('Requires: token') and the fact that the response carries a ticket `code`. It does not warn that repeated calls create duplicate tickets (relevant given idempotentHint=false), 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 tight sentences: what it does, what is required/optional, what comes back and where to use it. Front-loaded with purpose, and every clause carries information the agent needs.

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

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

With no output schema, the description helpfully names the returned `code`, and it flags the token requirement, so an agent has enough to call and chain the tool. Minor gaps remain (error/permission failure cases, whether service_id must belong to the caller), but nothing blocking.

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

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

Schema description coverage is 100%, so subject/message/service_id are already fully documented with lengths, format and examples in the schema. The description only restates required vs optional status, adding no new syntax or constraint detail. Baseline 3 applies.

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

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

The description states a specific verb+resource ('Open a support ticket with EQVPS') and immediately differentiates itself from the read/mutate siblings by naming the follow-on tools (get_ticket / reply_ticket / close_ticket). An agent can distinguish it from list_tickets or get_ticket 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 clear workflow context: the returned `code` is the handle to use with get_ticket / reply_ticket / close_ticket, which tells the agent where this tool sits in the lifecycle. It does not explicitly state when NOT to use it (e.g. to reply to an existing ticket use reply_ticket), so it falls short of the full 5.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), it discloses the actual permission envelope granted (power/reinstall/console/hostname/rdns but not renew/cancel/billing), that an invitation email with an accept link is sent, and that access is time-limited only if expires_days is supplied. This is the auth and effect-scope context an agent needs for a delegation mutation.

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 action and its scope are front-loaded in the first clause, with the permission boundary immediately after. It is dense but nearly every clause earns its place, though 'Owner-only' and 'Requires: token (owner)' are mildly 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?

For a no-output-schema, 3-parameter mutation, the description covers the actor, effect, invitation flow, expiry, and auth requirement. The main omission is what the call returns (e.g. a delegation id) and what happens if the same email is delegated twice, which the non-idempotent annotation implies is possible.

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

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

Schema description coverage is 100%, so email, service_id, and expires_days are already fully documented in the schema. The description restates expires_days as optional time-limited access but adds no syntax or constraint meaning beyond that, so the baseline 3 applies.

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

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

The description gives a precise verb (grant) and resource (OPERATOR access to one of YOUR VPS) plus the target (another person by email). It distinguishes itself cleanly from siblings like revoke_delegation, list_delegations, and accept_delegation, which handle the other stages of the same lifecycle.

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 prerequisite explicitly (owner-only, requires an owner token) and enumerates exactly what the delegatee may and may not do, which tells the agent when this tool is appropriate. It does not, however, route the agent to the counterpart tools (revoke_delegation to undo, list_delegations to audit), so the when-not side is only implicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds substantial behavioral context beyond annotations: the 5 MB size cap, the default UTF-8 output and the base64 fallback via as_text, and the auth requirements (token + live sandbox_id). This prevents misuse for large payloads.

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

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

The description is a single dense paragraph that front-loads the core purpose, then the alternative, then the requirements. It is well-structured, though it slightly repeats 'max 5 MB' and 'get_download_url' at the end, which is minor redundancy.

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

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

For a simple read tool with full schema coverage, no output schema, and safety annotations already in place, the description covers everything an agent needs: scope, size limit, output format, auth prerequisites, and the correct alternative for larger files.

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

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

Schema description coverage is 100%, so the schema already fully documents path, sandbox_id, and as_text, including the base64 behavior and the absolute-path constraint. The description mostly repeats that information without adding new syntax or edge-case meaning, 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?

The description states a specific verb and resource: reading a small file from a sandbox into the conversation, with the output representation (UTF-8 vs base64). It explicitly distinguishes itself from the sibling get_download_url for large files, so an agent can route correctly without opening schemas.

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

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

It gives explicit when-to-use (small files, max 5 MB) and when-not (build artifacts, archives, binaries, anything big) and names the alternative (get_download_url) with the reason (short-lived link, avoid base64 in context). Prerequisites (token + live sandbox_id) are also stated.

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

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

Annotations already convey the safety profile (destructive, non-idempotent, open-world), and the description correctly aligns with it. It adds real value: root execution, unfiltered shell operators, and the raw-HTTP/curl gotcha where a malformed JSON body yields a -32700 parse error rather than a firewall block. With annotations covering much of the safety context, a 3 is appropriate for the incremental 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?

Front-loaded with purpose and return shape, then packs constraints and error branches efficiently into a single dense paragraph. It is long but nearly every clause (background flow, timeout ceiling, curl caveat) carries actionable information, 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?

For a 6-parameter open-world tool with no output schema, the description supplies the return fields, the sync-vs-background split, the timeout ceiling, the auth requirement (token + live sandbox_id), and error-code semantics. 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 description coverage is 100%, so the schema already documents cwd (default /root), timeout (max 55), background (returns task_id), and env. The description mostly restates these, adding only the default 30 s timeout, which earns baseline 3 rather than more.

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

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

States a specific verb (execute) and resource (shell command) with the exact execution context: bash -lc, as root, in a sandbox. It also names the return shape {exit_code, stdout, stderr, timed_out, truncated, duration_ms}, letting an agent distinguish it from the sibling run_code without opening the schema.

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

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

Gives concrete routing: long commands (>55 s) should set background:true and then poll get_task, kill_task stops it, a timed_out result should be retried with background:true, and a 404 means the sandbox expired so create a new one. Alternatives (get_task, kill_task, create_sandbox) are named with the conditions that select them.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context: the auth requirement ('Requires: token') and the behavioral fact that order_vps draws on this balance automatically when sufficient, which helps an agent interpret the number.

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 each carrying distinct information (return values, cross-tool behavior, 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?

With no output schema, the description does describe what comes back (credit balance plus currency) and states the token requirement, which is enough for a zero-parameter read tool. It stops just short of details like balance units or whether the value includes pending charges.

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 parameter-wise to clarify, and the description instead spends its words on the return payload (balance and currency), which is appropriate.

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

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

The description states a specific verb and resource ('Return the account's prepaid credit balance and currency'), so an agent immediately knows this is a read of account credit. It does not explicitly name the sibling it contrasts with (topup_balance), relying on the resource name to do the differentiating.

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

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

Usage is only implied: the note that `order_vps` spends from the balance tells the agent why the balance matters, but there is no explicit 'use this when... / not when...' guidance or pointer to topup_balance for adding funds. Context exists but selection criteria must be inferred.

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

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

Goes well beyond the annotations: ttl default and range, 2 GB size ceiling, 'only works while the sandbox runs and only for that path', 'treat it as a secret', and that the link dies with the sandbox. The annotations only give generic hints (readOnlyHint false, openWorldHint false), so this behavioral detail is genuinely additive.

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?

Tightly front-loaded: what the link is, its lifetime, then the curl usage and constraints. Minor redundancy — 'only works while the sandbox runs' is restated at the end as 'dies with the sandbox' — keeps it just short of 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?

No output schema, so the description must explain the returned value, and it does: a short-lived secret URL that streams one file. Lifetime, size limit, usage recipe, and the token/sandbox precondition are all covered, leaving nothing an agent needs in order 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 description coverage is 100%, so ttl range/default and the absolute-path requirement are already documented in the schema; the description repeats the ttl default and range without adding syntax. The only extra semantic is the 2 GB max file size, which is not expressible in the schema. Baseline 3 is appropriate.

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

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

States a specific verb ('Get'), a precise artifact ('short-lived HTTPS link') and a bounded resource ('streams ONE file from the sandbox — e.g. a build artifact or archive'). The phrase 'without base64 in this conversation' implicitly distinguishes it from the sibling download_file, so an agent can route correctly without opening the schema.

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

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

Gives clear operating context — call it when you want a link you can pull with `curl -fL -o <name> <url>` from wherever you work, requiring token + live sandbox_id. It implies the alternative (inline base64 download) but never names download_file or get_upload_url, so the when-not-to-use side is only inferred.

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

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

Annotations already mark it read-only and closed-world, but the description adds substantial behavior beyond them: orders are never refused for capacity (queued, usually within 24h, see queue_note), and it discloses auth behavior ("works without a token"; with a token the limit is account-scoped). This is exactly the kind of context annotations cannot carry.

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

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

The purpose and constraint are front-loaded in the first clause, and nearly every sentence carries information (limits, add-ons, queue policy, response fields). It is dense with parentheticals and slightly heavy, but there is little dead weight.

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

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

With no output schema, the description takes on the burden of describing returns and does so fully (months, term_price, terms with quick picks, addons.*, queue_note). An agent has everything needed to call it 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 100%, so parameters are documented, but the description adds meaning beyond the schema by tying product/months to the subsequent order call and explaining max_quantity = 50 as a typo guard. This goes past the baseline 3 by supplying usage semantics the schema lacks.

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?

It states a specific resource (per-order max quantity, limit_reason, and plan add-on pricing) with an explicit relationship to the sibling order_vps, which an agent can use to distinguish this lookup from the actual ordering tool 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?

"Before order_vps" names the trigger condition and the sibling it precedes, and the instruction to pass the same product/months you will order tells the agent exactly how to use it in the ordering flow. No ambiguity about when this tool is appropriate.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful context beyond that: it requires a token, and it discloses that paused sandboxes expose pause_reason and delete_after, which previews conditional behavior of the payload.

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, front-loaded with the status fields before the usage/billing fields. Every clause earns its place, though the run-on length makes it slightly harder to scan than a short bulleted list would be.

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

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

There is no output schema, so the agent must otherwise guess the return shape; the description compensates by enumerating the state, mode, and cost fields. Combined with annotations covering the read-only profile, this is nearly complete, missing only guidance on when to call it versus sibling status tools.

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, and schema description coverage is 100% with a pattern and an example id format, so the schema fully carries the semantics. The description adds nothing about sandbox_id itself; the 'Requires: token' note refers to auth, not a parameter.

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

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

States a specific verb+resource ('Status of one sandbox') and enumerates the exact fields returned (state, mode, tariff, expires_at, usage metrics). The singular 'one sandbox' + required sandbox_id clearly distinguishes it from the sibling list_sandboxes.

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 naming and the sandbox_id requirement, but the description never states when to reach for this over siblings like list_sandboxes, get_vps_status, or sandbox_pricing, nor any exclusions or prerequisites beyond auth.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the description's marginal value is in disclosing that no auth is required, that the response varies with authentication state (balance/servers only if authenticated), and the cross-cutting conventions (`next_steps` on all responses, `error.fix` + `error.next` on all errors). It does not describe size, pagination, or caching behavior, so a 4 rather than a 5.

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

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

Front-loaded with the imperative 'Call this FIRST,' then enumerates the returned payload in a single dense sentence. Every clause carries information (flow, human step, auth rule, error fixes, limits, personalization), though the run-on em-dash construction and the repeated 'Call this first' could be tightened slightly.

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

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

With no output schema, the description carries the full burden of describing the return value, and it does: the response contents are enumerated, including the conditional `you_are_here` block. It also states prerequisites (none), the single human step (crypto checkout_url), and the conventions governing sibling tools, leaving nothing material unstated for a zero-parameter entry point.

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, which is the baseline-4 case per the scoring rules. The description correctly reinforces this by stating 'Requires: nothing' rather than inventing parameter detail, and the example arguments it mentions belong to the downstream tools, not to this call's 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 deliverable: it 'returns the whole flow in one response' — the exact tool order for renting a VPS and running code, auth rules, error fixes, limits, and a personalized `you_are_here` block. This is unmistakably an onboarding/orientation tool, distinguishable from every sibling like login, order_vps, or run_code, which perform the actual operations.

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 prescribes the sequence: 'Call this FIRST' at both the opening and the closing line, plus the precondition 'Requires: nothing.' An agent knows exactly when to invoke it (before anything else) and that it needs no credentials. It also explains the alternative pattern — every other tool response carries `next_steps` and every error carries `error.fix`/`error.next` — so the agent knows when a follow-up call to this tool is unnecessary.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, and the description adds genuinely useful context beyond them: an 8 MiB per-stream retention cap with older output dropped and reported in *_dropped, the token requirement, and the low per-call cost. It stops short of explaining behavior for invalid offsets or already-collected tasks.

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 dense paragraph that front-loads what the tool returns and follows with the polling procedure, retention limit, and auth note. Every clause carries information, though the offset instructions partially duplicate the schema wording.

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 carry the return shape — and it does, naming state values, exit_code, done, the stdout/stderr payloads, and the *_dropped fields. Combined with the offset protocol and retention cap, an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100%, and the schema already documents offset defaults ≥ 0 and the next_offset handoff pattern, so the description largely restates what is structured. It adds only marginal framing (the 0-start convention and the ordering of poll iterations), so baseline 3 is appropriate.

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

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

States a specific verb+resource ('Status and NEW output of a background task') and immediately scopes it with the field list it returns (state, exit_code, stdout/stderr). This distinguishes it cleanly from kill_task (terminates), exec_command/run_code (start work), and get_sandbox (sandbox-level 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?

Gives concrete operational guidance: start with offsets 0, then feed back stdout_next_offset/stderr_next_offset, and poll every few seconds. It does not name sibling alternatives (e.g. kill_task for cancellation) or state what happens when polling a task that already finished, so it falls just short of explicit when-not guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real value beyond that: it exposes the auth requirement ('Requires: token') and explains the message-thread shape, including that a `staff` author denotes a support reply.

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, zero filler, with the core operation front-loaded and the auth note last. 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 partially compensates by describing the returned thread and the `author` semantics. For a single read-only parameter tool this is nearly complete, though it does not mention pagination or thread size limits.

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 documents ticket_code with an example and its origin. The description repeats the create_ticket/list_tickets source but adds no format or syntax detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource with scope: 'Read one ticket and its full message thread.' The singular 'one ticket' plus 'full message thread' distinguishes it from the sibling list_tickets 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 tells the agent to 'Poll this to see new answers' and routes to the source of the identifier ('The ticket code comes from create_ticket / list_tickets'). No explicit when-not-to-use or named alternative like 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?

Annotations already mark it read-only and non-open-world, yet the description adds substantial operational depth: how capacity_now/wait_reason affect ordering, that queued upgrades apply automatically within ~24h and never move hosts, that pending_upgrade suppresses options, and how refunds/credits work. This goes well beyond what the annotations convey.

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

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

Purpose is front-loaded in the first clause, and every subsequent sentence carries distinct information (modes, option fields, constraints, capacity semantics, math). It is dense and could be split for readability, but 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?

Despite having no output schema, the description enumerates the returned fields (product_id, name, monthly, prorated_topup, mode, line, capacity_now, wait_reason, pending_upgrade, options, unused_credit, new_cost) and explains their meaning and interactions. It is complete enough for an agent to interpret results and reason about a follow-up change_plan call.

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 and schema coverage is 100%, with the schema already explaining the service_id format. The description mentions required auth ('token') but adds nothing about service_id semantics, so the structured field carries the burden — the correct baseline of 3.

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 (plans this VPS can switch to IN PLACE), and names the three operation modes (resize, convert, convert_to_nat) with their effects. It is clearly distinguishable from list_plans (generic catalog) and change_plan (executes the change).

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 preconditions ('The server must be active') and hard exclusions ('Shrinking vCPU/RAM/disk is not possible'), and ties the result to the follow-up action change_plan. It stops short of explicitly routing against sibling tools like list_plans, so it is strong but not a full when/when-not/alternatives statement.

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

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

Beyond the annotations (readOnly=false, idempotent=false), it discloses material behavior: the link is short-lived, each PUT carries at most 95 MB, larger files must be chunked in order via ?offset, each response returns `next_offset`, and offset 0 overwrites prior content. This is exactly the kind of operational context an agent cannot get from the annotations alone.

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

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

The core purpose is front-loaded in the first clause and the body is dense but readable. The trailing 'Requires: token + live sandbox_id. ≤95 MB per PUT; use ?offset for more.' restates content already established, which is a minor redundancy and the only thing keeping this 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 chunked-upload tool with no output schema, the description covers TTL, size limits, offset chaining, and the `next_offset` field well. It stops short of describing the rest of the returned payload (e.g. the URL field name or link expiry), but an agent has enough to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description reinforces max_bytes ('up to 2 GB') and adds semantics not present in the schema, notably the overwrite-at-offset-0 behavior on `path` and the chunked-upload offset mechanic that governs how the returned URL is used.

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

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

The description gives a specific verb and resource: returning a short-lived HTTPS link to PUT one file into a sandbox at `path`. The 'ONE file'/'up to 2 GB' scoping and the 'No base64 through this conversation' remark implicitly route the agent away from upload_file, but no sibling is named, so differentiation is inferential rather than explicit.

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

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

It states the prerequisites ('Requires: token + live sandbox_id') and the operative workflow (one PUT ≤95 MB, chunked PUTs via ?offset for larger files). What is missing is an explicit 'use this instead of upload_file/get_download_url when…' condition, leaving the alternative-selection rule to be inferred.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds a genuine behavioral fact beyond annotations: an explicit auth requirement ('Requires: token'). It still omits return format/pagination context, but that is a real addition.

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-loaded with the metrics scope and followed by the parameter constraint and auth note. No filler; the enum notation is tight.

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 some return-value explanation is useful; the description covers this by naming the four metric categories returned. Combined with annotations covering safety and schema covering params, it is nearly complete, though return format/pagination is still unspecified.

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

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

Schema description coverage is 100%, so both parameters (including the enum and default for timeframe) are fully documented in the schema. The description only restates the enum/default, adding no syntax or behavior beyond it; 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 operation (time-series resource metrics), the resource (a VPS), and enumerates the covered signal types (CPU %, memory, network, disk). This scope detail readily distinguishes it from the nearby status/list siblings without opening the schema.

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

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

The purpose implies a monitoring use case and the timeframe/default is noted, but there is no explicit when-to-use, when-not, or alternative (e.g., get_vps_status vs get_vps_metrics) guidance. Usage is left to inference.

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

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

Goes well beyond the readOnlyHint annotation: it pins the READ-ONLY guarantee to a version (1.9.1) and explains it is safe to poll, discloses that ssh_ready/rdp_ready are live probes with a 1-5 minute post-boot delay, warns that ready commands are withheld while false, and documents the NAT/firewall trap (allow internal port, not the DNAT port). This is unusually rich operational context.

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

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

The purpose is correctly front-loaded, but the body is a dense wall of parenthetical clauses (port mapping, ufw advice, retry semantics) that is hard to parse and partly tangential to a status read. It is information-rich but not economically structured.

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

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

With no output schema, the description carries the burden of explaining return values and does so thoroughly — password_available, access.method, ssh_ready/rdp_ready, ready_note, retry_after_seconds, internal_port, firewall_note. 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 100%, so baseline is 3, but the description adds interpretation — that the legacy `reveal: true` argument is still accepted but only redirects the caller to reveal_password, and that service_id comes from list_vps/order_vps. That clarifies intent rather than merely restating 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 ('Get full detail for one VPS') and enumerates the returned facets: status, specs, live VM state/uptime, and access info. It is clearly distinguishable from siblings like list_vps (enumeration) and get_vps_metrics (metrics-only).

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 routing: poll after order_vps to watch provisioning reach 'active'; read a pending password once via reveal_password; use reset_password ONLY if the password is lost. It also states a clear when-NOT-to-act condition — don't reset/reboot/reinstall while ssh_ready is false.

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

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

Annotations only assert destructive/idempotent/no-read; the description adds far more: exactly what is destroyed (files, packages, background tasks, memory), irreversibility, billing semantics (stops, final partial period billed, per-second with 60 s minimum for ephemeral, per-started-hour for persistent), and the token requirement.

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

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

Front-loaded with the destructive consequence, then the recovery caveat (download_file first), then billing, then auth requirement. Every clause carries operational weight; nothing is padding.

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

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

No output schema exists, and none is needed for a delete. Between the description and annotations, an agent knows the safety profile, the scope of data loss, the billing effect, and the auth prerequisite — everything needed to invoke 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?

There is a single parameter and schema coverage is 100%, with the schema itself documenting the id pattern and example. The description's only parameter-adjacent line ('Requires: token') concerns auth, not sandbox_id, so it adds no semantic detail beyond the schema.

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

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

Opens with a specific verb+resource+mode: 'Delete a sandbox IMMEDIATELY and IRREVERSIBLY (running or paused)'. That phrasing separates it from the read-only siblings get_sandbox/list_sandboxes and from kill_task, which targets a task rather than the sandbox itself.

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

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

Gives a clear pre-condition: 'download_file anything you need first', which tells the agent the ordering constraint before invoking. It does not explicitly name an alternative path (e.g. pause or cancel_service) or state when deletion is unnecessary, so it falls short of full when/when-not guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the kill cascades to all child processes started by the task, the final state is returned as 'killed', and the surrounding sandbox survives. Only the auth requirement and return surface are lightly covered.

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

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

Four short, declarative sentences with zero waste, and the primary action is front-loaded before the scope caveat and the return/requirement notes. Every sentence carries information the agent needs.

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

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

With no output schema present, the description compensates by stating the returned final state ('killed'), and it clarifies the blast radius (child processes) and the non-effect on the sandbox. For a two-parameter mutation with full annotation coverage, nothing essential is missing.

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

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

Schema description coverage is 100%, so task_id and sandbox_id are already fully documented with their id formats and provenance. The description adds nothing parameter-specific, so the baseline of 3 is appropriate.

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

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

States a specific verb (Stop) and resource (a running background task and all processes it started), and explicitly narrows scope with 'The sandbox itself keeps running', which distinguishes it from the sibling kill_sandbox. An agent can tell what it does and what it does not do without opening the schema.

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

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

Context is implied: this is the per-task stop operation, contrasted implicitly against kill_sandbox by the 'sandbox keeps running' note. However, it never says when to prefer this over get_task, cancel_service, or kill_sandbox, and lists no prerequisites beyond the auth token. Usage is inferable but not stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, covering the safety profile. The description adds the auth prerequisite ('Requires: token'), which is real behavioral context, but says nothing about result shape, volume, or pagination for what could be a long list.

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

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

A single tight sentence followed by a short auth note; the scoping definition is front-loaded and nothing is redundant. The trailing 'Requires: token.' fragment is slightly tacked-on but small.

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 adequately characterizes the returned set (services you have operator access to but do not own). Minor gap: no mention of ordering or whether the list can be paginated, which matters for an unbounded list 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?

Zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. No parameter-level detail is missing or 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?

Specific verb (List) plus resource (services delegated to me) with explicit directionality — 'other owners have delegated operator access to you' — which cleanly separates it from siblings like list_delegations, delegate_service, and list_vps. An agent can pick this tool without opening a schema.

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

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

The clause 'the VPS you can operate but don't own' implies the use case well, but no explicit when/when-not guidance or named alternative (e.g. list_delegations for delegations you granted) is given. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral content by disclosing what the listing contains ('who has operator access to what, and its status') and noting the auth requirement, which goes beyond the annotations.

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

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

A single front-loaded sentence states the resource, the scope, the return content, and the auth note with no filler. 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 parameterless read tool with no output schema, the description supplies the essential context: directionality (outgoing), what the result shows, and the token requirement. It stops short of describing pagination or result ordering, but nothing critical 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?

There are zero parameters, so there is no parameter semantics to explain; the baseline for a parameterless tool is 4. Nothing in the description misrepresents or omits an input.

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

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

The description states a specific verb (list) and resource (delegations) and scopes it precisely to outgoing grants 'you (the owner) have granted on your services.' This directionality clearly separates it from the sibling list_delegated_to_me, though it never names that sibling explicitly.

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

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

The phrase 'outgoing delegations you (the owner) have granted' implies the usage context (auditing who has access to your services), but there is no explicit when-to-use, when-not-to-use, or named alternative such as list_delegated_to_me. Usage is inferable rather than stated.

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

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

Annotations already cover readOnlyHint and openWorldHint, so the description goes beyond them usefully: no-auth access, flat catalog scope, BYOL licensing semantics for Windows, and that automatic offers surface in `plans[].promo` and `meta.promotions`. It stops short of describing pagination or whether plan availability is regional, but the safety/behavior profile is well covered.

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

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

Front-loaded with the resource and scope, then prerequisites and usage. The price points and port speed are mildly decorative but arguably help an agent sanity-check catalog expectations; still, it's a dense single block rather than tightly structured.

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

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

With no output schema, the description carries return-shape duty and does so (`plans[]`, `plan_id` cadence, `promo`, `meta.promotions`). Combined with zero parameters and annotations covering the safety profile, an agent has everything needed to call it 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?

The tool takes zero parameters, so there is nothing to disambiguate and the baseline is 4. The description instead documents the response shape (`plans[]` with monthly and annual `plan_id`, `promo`, `meta.promotions`), which is bonus value rather than parameter guidance.

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 (list the VPS plan catalog), explicitly scoped to pricing, specs and bootable OS images, with the two catalog segments (Linux NAT/dedicated, Windows BYOL) called out. That 'catalog vs. existing instances' framing separates it from list_vps without needing to open 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?

States the exact next action — 'Use this first to pick a `product` slug and an `os_id` for `order_vps`' — which routes the agent to the correct follow-up tool. It also declares prerequisites ('Requires: nothing', 'No authentication needed'), removing any need for a login-then-list inference.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds useful behavioral detail beyond them: the result set includes both running AND paused sandboxes, and it names the returned attributes (mode, tariff, state, expiry). The 'Requires: token' note flags the auth dependency that the empty parameter schema leaves unexplained.

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

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

Two short clauses, front-loaded with the action and scope, with the auth requirement appended. No filler, though 'Requires: token' is terse enough to be slightly ambiguous about where the token is sourced given no token parameter exists.

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

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

With no output schema, the description usefully enumerates the returned fields and the included states, and annotations carry the read-only safety profile. A minor gap remains around pagination/ordering, but 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?

There are zero input parameters, so the baseline is 4. The description appropriately adds no parameter detail and instead documents the shape of what comes back, which is the more relevant information for a no-arg tool.

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 sandboxes') and narrows scope to running and paused instances. It clearly contrasts with the singular sibling get_sandbox by implication, though it never names that sibling explicitly.

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

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

Usage is implicitly clear (query the account's sandbox inventory), and it discloses the auth prerequisite 'Requires: token'. However, it gives no explicit when-to-use-vs-alternatives guidance, e.g. when to reach for get_sandbox, sandbox_pricing, or create_sandbox instead.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds a real auth requirement ('Requires: token') plus an interpretation of the returned field semantics for last_message_author. It does not discuss pagination or result size, keeping it short of a 5.

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

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

Three short sentences, purpose front-loaded, with the auth requirement trailing. Efficient overall, though the inline last_message_author snippet is slightly cryptic without surrounding context.

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 list tool, the description supplies purpose, auth requirement, and value-field meaning, which is essentially all an agent needs to select and call it. Only the get_ticket routing distinction is 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?

The tool takes no parameters, so the baseline is 4. There is nothing further for the description to document, and it correctly avoids inventing filter options.

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') plus the salient fields returned (status, last-message info). It implicitly distinguishes itself from the singular get_ticket sibling, but never names that sibling to make the distinction explicit.

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

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

Usage is only implied: 'list your support tickets' suggests a broad retrieval step, and the last_message_author note hints at a monitoring use case. There is no explicit when-to-use vs get_ticket or when-not guidance.

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

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

Annotations only cover readOnlyHint and openWorldHint, so the description usefully adds the inclusion/exclusion semantics and an auth requirement ('Requires: token'). It does not describe the response payload or ordering, but for a no-arg list tool this is solid added context rather than a gap.

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

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

Three tight sentences, state/scope first, then the identity mapping, then the negative guidance. Every sentence carries distinct, 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?

For a no-param, no-output-schema list tool, the description covers scope, the key returned field, and the auth prerequisite. Only minor things like result ordering or size are unstated, which is acceptable 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?

Zero parameters, so the baseline is 4. The description still adds cross-tool semantics by explaining that the returned `id` is the `service_id` consumed by management tools, which is meaning beyond the empty schema.

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

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

Specific verb (List) plus resource (account's VPS services) with an explicit scope definition: active, provisioning, suspended included; deleted/cancelled excluded. This clearly separates it from siblings like get_vps_status and list_sandboxes.

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 both positive routing ('Use the `id` as `service_id` for the management tools') and an explicit when-not case ('If a server is missing from this list it has been deleted — do not query its status or try to manage it'). This prevents the agent from wasting calls on deleted resources.

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

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

Goes well beyond the annotations (which only cover read-only/idempotency safety) by disclosing token lifetime semantics (default 1 year, configurable via token_ttl_days), session-scoped reuse, the 401 invalid-credentials failure mode, and the register_account-has-no-password gotcha. No contradictions with the annotation set.

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 return value, then caveats. Slightly dense and mildly redundant (the 'register_account accounts have no password' point is stated twice), but every sentence carries actionable information.

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

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

With no output schema, the description still tells the agent what comes back (the token) and how long it lasts, and it covers the main error and the account-state prerequisite. Nothing essential to calling this correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all three parameters; the description still adds value by explaining what token_ttl_days controls (the token's usable lifetime and the 365-day default) and reinforcing the password prerequisite. It stops short of adding format/syntax detail beyond the schema.

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

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

States a precise verb (log in) and the exact inputs (email + password) plus what it produces (a reusable bearer token). It is clearly distinguishable from siblings like register_account, set_password, and refresh_token, which it references by name.

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 gives the prerequisite (a password must have been set with set_password), the alternative path (keep using your register token), and the fix (call set_password while still authenticated) for accounts created via register_account. The agent knows both when to use this and what to do instead if it can't.

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

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

Beyond the annotations, it explains capacity queue behavior, billing term semantics, promo application, Windows plan constraints, add-on availability, idempotency_key retry behavior, and typical errors. These are substantial behavioral details an agent would not get from the annotations or schema alone.

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

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

The description is front-loaded and uses bullets for response branching, but it is very long and repeats the capacity-queue behavior multiple times ('never refused for capacity', 'usually within 24 hours'). Much of the detail is useful, but the repetition and density make it less concise than ideal.

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

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

For an 11-parameter financial/provisioning tool with no output schema, it covers prerequisites, payment flow, response fields, error cases, queuing, and add-on constraints thoroughly. An agent has enough information to call it correctly and interpret the main outcomes.

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?

Although schema coverage is already 100%, the description adds real semantic value: product and os_id source relationships, months precedence and billing consequences, location omission behavior, quantity batching, add-on billing, and ssh_key/Windows exceptions. This is more than restating 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 first sentence states a specific verb and resource: 'Order a VPS.' The description immediately distinguishes the core action from sibling reads like list_plans and get_vps_status, which it references as inputs/status checks rather than 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?

It gives clear context for when ordering applies, including required inputs and the payment/queue outcomes, plus response branching to pay_invoice or topup_balance. It does not explicitly say when not to use this tool or contrast it with siblings such as create_sandbox or change_plan.

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

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

Goes well beyond the annotations (destructiveHint=true, idempotentHint=false) by explaining exactly what money moves, what happens when the balance is insufficient (nothing charged, checkout_url returned), the automatic server-creation side effect, and retry behavior returning 409 'Invoice is already paid'. The retry claim is in mild tension with idempotentHint=false, but is defensible because a repeat call returns an error rather than the original result, so it is not flagged as a contradiction.

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 two things that matter most — what it does and that it SPENDS MONEY. It is dense with parenthetical asides rather than wasteful, but the single paragraph packs several branches together, which slows scanning slightly compared to a bulleted split.

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 fully compensates by naming every returned field (paid_from_balance, status, balance, checkout_url) and the 409 failure case. Nothing an agent needs to call this safely or interpret the result is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description reinforces the format requirement ('pass invoice_id exactly as returned, a code like "2RUAWV4"') and notes it originates from order_vps / topup_balance. It adds modest but real value about where the identifier comes from.

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

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

States a specific verb and resource with scope qualifiers: 'Pay an owned, unpaid invoice.' An agent can immediately distinguish it from the sibling mutators that create invoices (order_vps, topup_balance) and from read-only tools like get_balance.

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 preconditions and branches: confirm with the human first, invoice must be owned and unpaid, and balance top-up invoices must go through crypto rather than this path's balance branch. It also routes the agent to list_vps to observe the downstream effect, which is the correct follow-up tool.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description goes beyond them by disclosing the auth requirement and a concrete failure mode—a 409 during first boot when setup is still running—plus the wait-and-retry remedy, which is genuinely useful operational context.

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

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

Two short, front-loaded sentences: the operation and its actions come first, then prerequisites and the error case. No padding or redundant restatement.

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

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

For a 2-parameter tool with no output schema and annotations that already cover the destructive profile, the description supplies the missing operational details (auth, first-boot 409 retry). It could still clarify whether stop/reboot are asynchronous or how the optional service_id behaves when omitted.

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 enum is fully documented in the schema itself, so the baseline of 3 applies. The description's enumeration of start/stop/reboot duplicates the schema's enum rather than adding format or constraint details the schema lacks.

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 ('Power-control') and resource ('a VPS') and enumerates the three concrete actions, so an agent instantly distinguishes it from read-oriented siblings like get_vps_status or reinstall_vps. It stops short of explicitly naming those siblings or stating the boundary between power cycling and reinstalling.

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 (start/stop/reboot), and the 'Requires: token' note gives an auth prerequisite. However, there is no explicit when-to-use guidance or alternative routing (e.g. check get_vps_status first, or prefer reinstall_vps when the OS is broken).

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, and the description adds the crucial concrete consequence: the old token is revoked immediately and the caller must save the new one when using raw HTTP. It also documents the X-Token-Expires-At header and the 30-day warning, well beyond what structured fields convey.

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

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

Front-loads the core exchange-and-revoke behavior and keeps supporting detail (header, session behavior, alternatives) compact. Slight redundancy: 'REVOKES the old token immediately' and the closing 'The old token is revoked' say the same thing 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?

No output schema exists, and the description compensates by naming the returned fields (token, token_expires_at), the default lifetime, and the session-level consumption behavior. An agent has everything needed to call and consume 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 description coverage is 100% and the schema already states range 1-1825 and default 365 for expires_in_days; the description restates the same range and only marginally clarifies that the lifetime applies to the NEW token. Baseline 3 is appropriate since the schema carries the parameter meaning.

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

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

States a specific verb and resource ('Exchange the CURRENT bearer token for a new one') and immediately disentangles itself from siblings like login and get_started by describing what it does versus what they do when the token is already expired.

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 gives the when (before expiry, within the 30-day warning window), the when-not (already expired tokens cannot be refreshed), and names the alternatives for that case ('log in again (login) or create a token in the cabinet').

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

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

Annotations already declare the safety profile (not read-only, not destructive, not idempotent), and the description adds substantial non-obvious context: token is reusable and single-use=false, 1-year default lifetime, auto-remembered inside the MCP session, must be persisted manually over raw HTTP/curl, and the 422 already-registered behavior.

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

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

Dense and front-loaded: the core action and the token's reusability lead, with operational caveats after. It is long, but nearly every clause carries an actionable instruction; the only mild redundancy is the email advice and the repeated 'don't register again' warning, which overlaps the 422 note.

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

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

No output schema exists, so the description carries the return burden and does so fully, explaining the bearer token, its lifetime, the token_ttl_days control, and the refresh path. For a mutation tool with side effects (empty account on repeat), 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 description coverage is 100%, so the schema already documents all four parameters including the email constraint and token_ttl_days range. The description largely restates the email advice ('no recovery, no notifications') and the TTL bound already present in the schema, adding rationale but little new syntax.

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: 'Create a NEW EQVPS customer account', naming the required fields. It also distinguishes itself from siblings (login, set_password, refresh_token) by explaining that re-calling it creates an empty account, so an agent can route correctly 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 states when-not-to-use it (never re-register for a new token; use login if the email is already registered), names alternatives (refresh_token before expiry; set_password + login as backup), and gives the precondition 'Requires: nothing'. The 422 branch is documented with the corrective action.

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

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

Goes well beyond the destructiveHint annotation: it states all data is lost, specifies the exact confirmation mechanism (hostname or DELETE), mandates human confirmation before the call, and discloses that provisioning is asynchronous and must be polled via get_vps_status. That is rich behavioral context an agent cannot infer from annotations.

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

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

Front-loads the DESTRUCTIVE warning, which is the right priority, but repeats itself ('all data is lost' vs 'Destroys all data', and the confirm requirement twice), so a small amount of the text 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?

For a destructive, no-output-schema mutation tool this covers everything an agent needs: the safety gate, the confirmation format, the source of os_id, and the post-call polling behavior. Nothing material is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates confirm's allowed values and os_id's source, largely duplicating the schema rather than adding format or edge-case detail for os_id or service_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 (wipes and reinstalls) and resource (the VPS with a given OS image), and distinguishes itself from siblings like power_vps or change_plan. The destructive scope and cross-references to list_plans make the intent unmistakable.

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: this is destructive, requires explicit human confirmation, and the confirm value must match the exact hostname or 'DELETE'. It does not explicitly contrast against alternatives such as power_vps or change_plan, but the precondition-driven framing is strong.

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

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

Annotations already declare it as a non-readOnly, non-idempotent, non-destructive write, so the safety profile is covered. The description adds the auth requirement ('Requires: token'), which is genuine behavioral context, but says nothing about duplicate replies despite idempotentHint=false, nor about visibility to the ticket owner.

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

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

Three short, front-loaded sentences with no filler; the core action leads and the prerequisites follow. Efficient, though slightly terse rather than maximally informative.

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

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

For a simple two-parameter write with no output schema, the definition covers action, identifier source, and auth requirement. It lacks only edge-case behavior (duplicate replies, length failure handling), which is minor 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?

Schema description coverage is 100%, so both parameters (ticket_code, message with its 5000-char limit) are already fully documented in the schema. The description only reinforces the ticket_code source, adding little beyond what the schema provides — the baseline 3 applies.

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

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

States a specific verb+resource ('Post a reply on one of your tickets'), which cleanly separates it from get_ticket, create_ticket, and close_ticket. However it does not explicitly name any sibling it excludes, so differentiation is implied by the verb rather than stated.

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 usefully points the agent at the workflow source for the key identifier ('Use the ticket code from create_ticket / list_tickets'), which is real usage guidance. But it gives no when-to-use vs when-not conditions and no prerequisites beyond the token, so the guidance is implied rather than explicit.

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

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

Goes well beyond the annotations: the change lands on the LIVE VM via guest-agent with no reboot, takes effect in ~10-30s, the OLD password stops working, and the new password is NOT returned here (retrieve once via reveal_password; also emailed). This is exactly the operational context annotations cannot convey.

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

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

Purpose is front-loaded and the safety step is prominent, but the tail is repetitive: 'Requires: token + confirm (hostname or DELETE)' and 'Only if the password is lost' restate points already made earlier in the same description.

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

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

For a destructive, non-idempotent mutation with no output schema, the description covers everything an agent needs: where the password is delivered, timing, prerequisites, and the human-confirm gate, all consistent with the annotations.

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

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

Schema coverage is 100% and the schema already documents confirm (exact hostname or 'DELETE', ask human first) and service_id. The description restates the confirm requirement but adds no new syntax or format guidance, so the baseline 3 applies.

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

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

States a specific verb+resource ('Rotate the root password') and immediately scopes it as a live, no-reboot rotation of the root credential. An agent can distinguish it from siblings like set_password and reveal_password 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 ('ONLY if the password was lost') and when-not-to-use ('NOT because SSH was not instant on a fresh order'), with the correct alternative path spelled out (poll get_vps_status, then reveal_password). It also states the required human-confirmation step before calling.

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

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

Annotations declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds crucial context beyond annotations: the one-time reveal is not spent until a password is returned, pending state behavior, timing, and that the response matches get_vps_status plus the password. No contradiction with annotations.

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

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

The description is front-loaded with the core behavior and well-organized, but it is somewhat verbose and repeats key points (e.g., 'call again in 30-60 s' and 'reset_password') in both the main text and the typical-scenario summary. Every sentence adds value, but trimming would improve conciseness.

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

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

Given no output schema and the complexity of a one-time secret reveal, the description is complete: it covers prerequisites (token, keyless VPS), return format (same as get_vps_status plus password), pending state, and recovery via reset_password.

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% for the single optional service_id parameter. The description does not add any parameter-specific meaning beyond what the schema already provides, 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 and resource: 'Read the root (Windows: Administrator) password of a keyless VPS'. It distinguishes the tool from siblings like reset_password and set_password by explaining the one-time reveal nature and the keyless requirement.

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 guidance is given: call again in 30-60s if password_pending, use reset_password if the password is lost, and no password is needed if an SSH key was ordered. Alternatives and exclusions are clearly named.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, so safety and repeat-call behavior are covered. The description adds value beyond them by disclosing a non-obvious side effect (the other side is notified) and the auth requirement ('Requires: token'), which the annotations do not convey.

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

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

Three short, front-loaded sentences with zero filler: action first, actor roles second, id discovery and auth last. Every sentence carries information the agent needs.

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

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

For a single-parameter, no-output-schema mutation whose safety profile is fully covered by annotations, the description supplies the actor semantics, the id source, the auth prerequisite, and the notification side effect. Nothing needed 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 description coverage is 100% and the single parameter's type, requiredness, and source are already documented in the schema, so the baseline is 3. The description adds the lookup path for the id, which is mildly useful but largely redundant with the schema. No syntax, format, or boundary details (e.g. the exclusiveMinimum) are added.

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 (a delegation), and clarifies the two legitimate actor roles: owner revoking access or a delegate declining their own delegation. An agent can distinguish this from sibling tools like accept_delegation or list_delegations without inspecting 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 routes the agent to list_delegations / list_delegated_to_me to obtain the required id, and states the two conditions under which revocation applies. It stops short of naming the inverse/alternative action (accept_delegation) or stating when revocation is inappropriate, so it is strong context rather than full when/when-not guidance.

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

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

Annotations already declare destructive/openWorld/non-idempotent, so the bar is lower, yet the description adds genuinely new behavioral facts: code is delivered on stdin so the program cannot read stdin, 1 MiB per-stream output cap for synchronous calls, sandbox keeps billing and is not idle-deleted while a task runs, and files/installed state persist across calls. It could still note whether concurrent runs in one sandbox are allowed, but coverage is strong.

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 language, then the escalation path, then behavioral caveats. Despite its length, every clause carries an actionable fact (defaults, caps, persistence, quirks) and none restates the schema verbatim.

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 compensates by enumerating the exact return fields and the alternate task_id return path. Combined with requirements ('token + live sandbox_id'), timeout limits, and the background polling workflow, an agent has everything needed to call this correctly on the first attempt.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds semantics the schema lacks: timeout defaults to 30 (schema states no default), background changes the timeout ceiling to the sandbox's remaining lifetime, env overrides apply to this run only, and the stdin constraint bounds how `code` may be written.

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 ('Run a code snippet inside a sandbox') and immediately names the return shape and supported languages, which distinguishes it from the many sandbox-management siblings. An agent can tell this is the execution tool, not a lifecycle tool like create_sandbox or 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?

Explicitly routes installs to exec_command, explains when to escalate to background: true, and gives a concrete failure-recovery rule ('timed_out after 55 s → repeat with background: true'). It also names the follow-up tools (get_task, kill_task) needed to consume a background job, leaving no routing decision to inference.

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

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

Annotations already establish that this is a safe read (readOnlyHint=true) and not open-world, so the safety profile is covered. The description adds that no authentication is needed and enumerates operational limits (55s sync exec, 5 MB transfers), but it is mostly a content dump rather than behavioral disclosure about the tool's own operation.

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

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

The key pricing table is front-loaded and information-dense, and every spec has some value. However the description is very long, and the SDK-install paragraph is essentially promotional material rather than something needed to select or invoke the tool, so it dilutes the signal.

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

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

With no output schema, the description must convey what the tool returns, and it does so thoroughly: full tariff specs, per-second/hour/month pricing, billing model, execution and file-size limits, and supported runtimes. Nothing an agent needs to call or interpret this zero-parameter 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 per the baseline this dimension starts at 4. The description correctly conveys that nothing is required ('Requires: nothing'), which is consistent with the empty input 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 identifies a specific resource (sandbox tariffs, pricing, and limits) with enough detail (instance sizes, runtimes) that it is unmistakable against siblings like list_plans or get_order_limits. It never states an explicit verb ('returns'/'lists') and does not name a sibling it differs from, so it falls short of the top tier.

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

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

Usage is only implied: the pricing context suggests calling it before choosing a sandbox tier, and 'Requires: nothing' plus the SDK note hints at an alternative path for coders. It does not say when to prefer this over list_plans/get_order_limits or state any exclusion, leaving the agent to infer the timing.

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?

Far exceeds the annotations: it discloses the guest-agent mechanism, immediate application on Linux vs reboot-required on Windows, the 409 agent_unavailable atomic-failure guarantee, and reassures that password/SSH keys/files are untouched. This is exactly the behavioral context an agent needs before a mutation.

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 dense paragraph front-loaded with the action, then mechanism, preconditions, safety and error. Every clause earns its place, though the stacked parentheticals make it slightly heavy to scan.

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

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

With no output schema, the description still surfaces the key response field (reboot_required: true) and covers prerequisites, failure modes and non-destructive scope. 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 description coverage is 100% and the hostname parameter already documents the DNS-name format, length limit and an example, so the description adds little parameter meaning. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource (set the VPS hostname) and immediately qualifies it with the expected format (valid DNS name). An agent can distinguish it from siblings like reset_password or reinstall_vps 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 preconditions (server running, guest agent active) and a remediation path for the typical failure (409 agent_unavailable → start the server / wait for boot). It does not need to name an alternative since no sibling performs this operation, which keeps it short of a 5 but genuinely helpful.

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

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

Goes well beyond the annotations by disclosing the 409-on-second-call behavior, the token requirement, and that no current password is needed the first time. One minor tension: idempotentHint=true while the description says a repeat call errors with 409, which the text never reconciles (state is unchanged, but the call is not a silent no-op).

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

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

Dense but well front-loaded: the account scope and the one-time nature land in the first two sentences. Slightly over-specified at the tail, where the 409 error is stated twice ('returns 409' and again 'Typical error: 409 password already set'), which is mild redundancy rather than filler.

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

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

With annotations covering the safety profile, a fully described single parameter, and no output schema to explain, the description supplies everything needed: auth requirement, first-call-only semantics, password constraints, and the error-to-action mapping. Nothing an agent needs 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 100% and the single param is already fully documented ('at least 8 characters with letters and numbers'). The description adds the useful clarification that there is no current-password parameter on the first call, but otherwise mirrors the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource with tight scope: 'Set a password for THIS account (the one your bearer token belongs to).' It distinguishes itself from nearby siblings (register_account, login) by explaining the account's default no-password state and the credential model, so an agent can place it without opening the schema.

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

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

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'), and the alternative ('use change-password instead'). This is the exact when/when-not/alternative structure a routing agent needs.

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

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

Goes well beyond the annotations by disclosing the asynchronous credit flow (balance credited only after on-chain confirmation), the single-unpaid-invoice invariant, the auth requirement, and the human-in-the-loop crypto payment step. These are exactly the behavioral traits an agent could not infer from readOnlyHint=false / idempotentHint=false alone.

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

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

Front-loaded with purpose and return value, and generally tight. The automatic-credit behavior is stated twice (once mid-description, once in the final sentence), which is mild redundancy but not harmful.

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

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

With no output schema, the description correctly supplies the return value (`checkout_url`) and explains what happens after the call. Required token, amount semantics, and the async confirmation path are all covered.

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 already documents the 3–10000 range, but the description adds that the amount is in account currency (USD) and that bounds are enforced server-side, clarifying failure modes not stated 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+resource (create a top-up invoice) and the concrete artifact returned (`checkout_url`), which cleanly separates it from read-only siblings like get_balance and from pay_invoice. An agent knows immediately what this does and what it produces.

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 preconditions and constraints: amount in account currency, server-side min/max, one unpaid top-up at a time, requires token, and a human must complete payment. It doesn't name sibling alternatives (e.g., pay_invoice vs. this), so routing guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, but the description adds important behavioral context: no money moves, end_of_period never refunds, immediate cancellations are irreversible, and a 409 nothing_to_undo error is typical. These details go well beyond the annotations and are consistent with them.

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

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

The description is tightly structured and front-loads the core action before consequences, constraints, prerequisite state, and error handling. Every sentence adds distinct value, and 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 mutation tool with clear annotations and a fully documented schema, the description supplies the remaining context an agent needs: applicability conditions, financial behavior, irreversibility of the alternative, required state, and expected error. No output schema is present, and return values are not needed for correct invocation.

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

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

Schema description coverage is 100%, and the single optional service_id parameter is fully documented in the schema. The description does not add syntax, format, or behavioral detail about service_id beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

Clearly states the action: undo a scheduled cancellation for a VPS whose cancellation type is end_of_period, keeping the server active. It distinguishes scheduled cancellations from immediate ones, which is the key boundary. An agent can identify the tool's purpose and scope without opening the schema.

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

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

Specifies exactly when the tool applies (scheduled end_of_period cancellation), when it does not (immediate cancellation cannot be undone), and what state to check first via get_vps_status. It also names a required condition and a typical error, leaving little to inference.

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

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

Annotations flag destructiveHint=true and idempotentHint=true, and the description adds meaningful context: parent directories are auto-created, an inline size ceiling, and a required auth/sandbox-liveness precondition. It stops short of warning that an existing file at `path` is overwritten, which is exactly what the destructive hint implies and matters for a write 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?

Dense and front-loaded: purpose, then content choice, then size limit, then permissions, then prerequisites. Slightly redundant — 'Limit 5 MB per file inline' is restated as 'Max 5 MB' at the end, and sandbox_id is re-listed as a requirement despite being a required schema field.

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 should cover behavior, limits and prerequisites, and it does. The remaining gap is overwrite/return semantics: it never says whether an existing file is replaced or what identifier/result comes back from the write.

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

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

Schema coverage is 100%, so the baseline is 3; the description nonetheless adds the inline 5 MB cap (not stated in the schema for `content`), reinforces the content/content_base64 mutual exclusivity, and gives a concrete `mode` example. It does not add path syntax beyond what the schema already documents.

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 immediately scopes it with parent-directory creation and the writable targets. It also distinguishes itself from the sibling get_upload_url, so an agent can separate it from download_file/run_code without opening a schema.

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

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

Explicitly routes between inline vs out-of-band upload: 'Limit 5 MB per file inline — for bigger files call get_upload_url and PUT the bytes to the link (no base64 through this chat).' It also states the content vs content_base64 selection rule and the prerequisites ('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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the non-obvious behavioral detail that a bearer token is required and implies failure when it is invalid, plus lists the returned shape in the absence of an output 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?

Three short sentences with zero filler; the purpose, the usage hint, and the auth prerequisite are all front-loaded and each 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 read-only identity probe with no output schema, the description covers purpose, trigger condition, prerequisite, and the returned field set. It could note error behavior on an invalid token, but nothing essential is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description mentions only the token requirement, which is a transport-level concern rather than a schema parameter, and nothing further 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 authenticated account profile') and enumerates the fields returned (id, name, email). No sibling tool returns account identity, so an agent can route to it unambiguously.

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

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

'Use to verify the bearer token is valid' gives a concrete caller-side scenario, which is more than most siblings offer. It does not name exclusions or alternatives, but none of the sibling tools overlap with identity verification, so there is little to exclude.

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