gpu.nz GPU cloud

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by stating the required permission scope ('user:write') and the expected input provenance (.pub file). It does not disclose what happens on a duplicate key or duplicate name, which is the remaining behavioral gap.

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

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

Two short sentences with no filler; the core action is front-loaded and the permission requirement follows immediately. Every sentence 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 small two-parameter mutation with full schema coverage, no output schema, and annotations carrying the safety hints, the description covers action, input format and required permission. It stops short of noting duplicate-key/name behavior, which an agent handling idempotency=false would benefit from knowing.

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 (name, public_key) are already documented with examples and length bounds, making 3 the baseline. The description's 'a line from a .pub file' adds only marginal format context beyond the schema's own 'ssh-ed25519 AAAA… you@laptop' example.

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 ('Adds an SSH public key ... to the account') and even clarifies the input format ('a line from a .pub file'), so the operation is unambiguous. It never names or contrasts with its natural counterpart list_ssh_keys, so sibling differentiation is only implicit via the verb.

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

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

The description supplies a real prerequisite ('Needs user:write'), which tells the agent what authorization is required before calling. However, it gives no when-to-use framing, no exclusions, and no routing toward alternatives such as list_ssh_keys for verification, leaving usage only implied.

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

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

Adds substantial context beyond the annotations: continuous per-minute billing from creation until stop/destroy, the required instances:write scope, and the asynchronous lifecycle detail that the caller must poll get_instance until status is running (1-5 minutes). None of this is discoverable from the structured fields, which is exactly what the description should 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?

Five short sentences, front-loaded with purpose, then cost, then a safety instruction, then permission, then the post-call workflow. No filler and each sentence delivers an operational fact.

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

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

With no output schema present, the description correctly supplies the return value ('the response has the instance id') and the follow-up polling procedure. Combined with full schema coverage, an agent has everything needed to invoke and sequence this 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?

Schema description coverage is 100%, so the schema already documents all 8 parameters including enum values, ranges, defaults, and the idempotency_key retry semantics. The description adds no parameter-level syntax or constraints 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?

States a specific verb and resource ('rents the server of an offer and starts it with a template'), which cleanly separates it from the sibling start_instance (starts an existing instance) and destroy_instance. An agent can identify this as the provisioning/create operation without opening the schema.

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

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

Gives prerequisite guidance by naming the upstream tools for its required inputs (offer_id from search_offers, template from list_templates, implicitly), plus the operational rule 'confirm the price with the user first.' It does not explicitly contrast with start_instance for the case where an instance already exists, so it falls short of a full when/when-not 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?

Annotations already flag destructiveHint and readOnlyHint=false, but the description goes further: it discloses that the disk is permanently deleted, that billing stops, that the action is irreversible, and that the instances:write scope is required. Those operational consequences are not derivable from the structured fields.

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

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

Three compact clauses, front-loaded with the destructive action and immediately followed by consequences and the guardrail. No filler sentences.

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

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

A single-parameter operation with no output schema and full annotation coverage; the description supplies the permission requirement, the irreversibility warning, and the business consequence. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and instance_id is documented in the schema, so the baseline of 3 applies. The description adds no syntax, format, or constraint information about instance_id.

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

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

States a specific verb and resource ("Destroys a server") and immediately scopes the effect: the disk is deleted for good and billing stops. That effect statement distinguishes it from siblings like stop_instance without needing to name them.

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

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

Gives clear usage context: irreversible, so confirm with the user, and it requires instances:write. It does not explicitly contrast with stop_instance, which is the natural alternative for a non-destructive halt, so it stops short of naming when-not/alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. Beyond that, the description discloses two non-obvious behaviors: the no-argument listing mode and that results include which GPUs fit an estimate plus their current price. It omits error behavior (e.g., unknown model names) and any rate limits.

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

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

The purpose is front-loaded in the first clause and the discovery-mode tip closes efficiently in a second sentence. The long parenthetical listing model families is informative but slightly bloats an otherwise tight definition.

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

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

For a read-only calculator with no output schema, the description covers what the tool does, its optional-argument mode, and that results pair GPU fit with pricing. A short note on how unknown models are handled is the only material gap.

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

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

Schema description coverage is 100%, so defaults and value ranges for all four parameters are already documented in the schema. The description only gestures at 'a given precision and context length' and never mentions concurrent_requests, adding nothing beyond the structured fields. 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 ('estimate' GPU memory for an AI model) and enumerates the model families it covers, so its scope is immediately legible. It is clearly distinguishable from siblings like list_gpu_models and search_offers, which list rather than compute.

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 conditional behavior: 'Call without `model` to list the known models,' which tells the agent how to use it in discovery mode versus estimation mode. It does not name alternative tools or state when another sibling (e.g., search_offers) should be preferred 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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description goes beyond that by disclosing required auth scopes (user:read, billing:read) and specifying the returned facets (balance, burn, runway), which annotations do not carry. It stops short of units, freshness, or rate-limit 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?

Two tight sentences: the resource and its content first, the prerequisite second. No filler, no restatement of the title, and every clause carries information an agent needs.

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

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

With no parameters and no output schema, the description must convey what comes back and what is required — it does both via the balance/burn/runway enumeration and the scope requirement. Minor gaps remain (units of balance/burn/runway, whether values are current or cached), but nothing blocks a correct 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?

Zero parameters, so the schema has nothing to document and there is nothing for the description to compensate for — the specified baseline of 4 applies. No parameter guidance is needed or missing.

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

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

States a specific resource (the signed-in account) and enumerates the exact data returned (balance, hourly burn, runway). The sibling list is entirely instance/offer/SSH-key oriented, so this tool is trivially distinguishable from every neighbor 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 description implies the usage context (fetching your own account state) and gives a real prerequisite — a key with user:read and billing:read scopes — but never states when to call this versus anything else or what conditions make it inapplicable. Adequate but thin.

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=true, so the safety profile is covered. The description adds real behavioral context beyond that: the root password is withheld by default and SSH keys are pre-installed on every server, which tells the agent when the password field is actually needed.

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

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

Two tight sentences with zero filler; the return contents are front-loaded and the password caveat follows immediately. Nothing is repeated from the schema or annotations.

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

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

With no output schema, the description carries the burden of describing returns, and it does so with a concrete field list. It stops short of noting error behavior for an unknown or destroyed instance id, but for a read-only fetch of one record this is close to complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds meaning by clarifying the default behavior of include_password (password omitted unless true) and by noting the password is the root password, which the schema only labels generically.

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

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

The description names the exact resource and enumerates what the call returns (status, SSH command, app URLs, price/cost), and 'of one server' implicitly separates it from list_instances. It is clear and specific, though it never explicitly names a sibling to steer the agent away from the list-style tools.

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

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

There is no explicit when-to-use statement or exclusion; the usage is only implied by the singular 'one server'. The only conditional guidance given concerns include_password, which is parameter-level rather than a usage rule.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description usefully adds the required scope (instances:read) and the nature of the returned content, but says nothing about line limits, default tail size, or that only the tail (not the full log) is available.

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 naming the resource first, then the content, then the auth need. No filler, nothing redundant with the schema or annotations.

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

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

For a simple read-only log fetch with full schema coverage and annotations covering safety, the description is nearly sufficient: it says what the log contains and what scope is needed. An explicit note on truncation/default tail would make it complete.

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

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

Schema description coverage is 100%, so instance_id and tail (with its default 200 and max 1000) are already fully documented. The phrase 'last lines' hints at tail semantics but adds no format or limit detail beyond the schema, so the baseline 3 applies.

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

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

States the specific resource (a server's container log) and the exact content returned (last lines, boot progress, app start-up, errors), which an agent can distinguish from metadata siblings like get_instance. The verb is only implied by the name rather than spelled out, but the scope is unambiguous.

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

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

The only guidance is the permission prerequisite 'Needs instances:read.' There is no statement of when to reach for this tool versus get_instance or get_account, and no exclusions. The troubleshooting context is inferable but never 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=true, so the read-only, external-data nature is covered. The description adds that the response includes the 'current price', hinting at freshness/recomputation, but says nothing about failure modes (unknown id), auth, or rate limits.

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

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

One short sentence with the resource and scope front-loaded and zero filler. Nothing could be removed without losing information.

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

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

For a one-param read tool with annotations covering the safety profile, the description is nearly sufficient, and it names the returned content ('details and the current price'). With no output schema, 'Details' remains vague about the actual return shape, which is the only real gap.

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

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

With 100% schema description coverage and a single required param documented as 'Offer id', the schema already carries the parameter burden. The description only restates that the id selects one offer and hints at its origin; it adds no format or validation guidance beyond maxLength 64 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 (fetch details and current price of one offer by id), which is clearly a single-item lookup rather than a browse. The parenthetical 'from search_offers' implicitly separates it from the sibling that produces offer ids, though no other siblings are contrasted.

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?

'by id (from search_offers)' establishes the two-step workflow and points the agent at the alternative that yields ids. It does not state exclusions or what to do if the id is unknown, so it falls short of the explicit when/when-not bar.

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 and openWorldHint, so the safety profile is covered. The description adds value beyond that by stating the data is live ('right now') and enumerating the returned fields, which matters because no output schema exists. It does not mention pagination or any auth/rate-limit 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?

Two short sentences, zero filler. The capability and its return contents come first, and the downstream usage instruction follows.

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 describing returns, which it does (VRAM, class, cheapest hourly price per GPU). Combined with the gpu_slug handoff to search_offers, an agent has enough to call it correctly, though freshness/pagination behavior is unstated.

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

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

Schema description coverage is 100%, so both parameters (query, min_vram_gb) are already fully documented in the schema with examples and constraints. The description adds no filtering syntax or additional parameter meaning, so the baseline 3 applies.

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

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

Specific verb+resource ('list GPU models available on gpu.nz') plus the returned fields (VRAM, class, cheapest hourly price) and a live scope ('right now'). It also implicitly distinguishes itself from the sibling search_offers by positioning itself as the upstream lookup for gpu_slug.

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 it to pick a gpu_slug for search_offers' gives an explicit workflow context and names the downstream sibling. There are no when-not conditions or exclusion rules, but for a read-only catalog lookup the routing guidance is clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds a genuinely new behavioral fact — the required instances:read scope — plus a sketch of the return payload (status, GPU, price, SSH command), which matters because there is no output schema. It omits pagination/rate-limit behavior, keeping it short of a 5.

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

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

Two short, front-loaded sentences with no filler; the payload contents come first and the permission requirement last. The telegraphic phrasing borders on under-specification rather than true economy, which keeps it from a 5.

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

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

For a one-parameter, read-only list tool with no output schema, the description supplies both the permission needed and the shape of the returned rows, which is most of what an agent needs. The one real gap is that it says nothing about result volume or pagination for a potentially long server list.

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 optional parameter with 100% schema description coverage, including the enum values and the default (active) versus destroyed-inclusion semantics. The description adds nothing about status filtering, so the schema-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?

Combined with the title, the description identifies the resource ("Your rented servers") and enumerates what each entry carries (status, GPU, price, SSH command), so it reads clearly as a list-instances tool. It does not explicitly contrast itself with the single-instance sibling get_instance or with search_offers, so sibling differentiation is only implicit.

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?

"Needs instances:read" states a permission prerequisite, which is useful invocation guidance, but the description never says when to prefer this over get_instance or when filtering by status is appropriate. Usage is essentially implied by the tool name, with no exclusions or alternatives 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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: the required auth scope (user:read) and the behavioral fact that these keys are injected into newly created servers — information an agent cannot get from the annotations.

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

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

Two short clauses with no padding, and the resource identification is front-loaded. It is efficient, though the fragment structure reads more like a note than a polished instruction.

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

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

For a zero-param read tool this covers auth and the resource's role. With no output schema, however, the description does not say what a key record contains (name, fingerprint, dates) or whether pagination applies, leaving a modest gap in what the agent can expect back.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. Schema coverage is 100% and the empty schema is self-explanatory.

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 is a noun phrase ("SSH public keys on the account") and leans on the tool name/title for the verb 'list'. It does add a differentiating fact — the keys are installed on new servers — which separates it from add_ssh_key, but the core purpose statement is vague rather than a specific verb+resource declaration.

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?

"Needs user:read" gives a prerequisite, but there is no explicit when-to-use guidance and no named alternative (e.g., add_ssh_key for creating keys). The agent must infer usage entirely from the resource name and the incidental note about new servers.

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=true, so the safety profile is covered. The description adds real behavioral content by enumerating what the catalog contains (including a custom Docker image option), but it does not describe the shape of the returned entries or note that the list may evolve. Adequate, not rich.

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

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

Two sentences, front-loaded with the content of the catalog and closed with the actionable handoff to create_instance. The long enumeration is informative rather than padding, though slightly dense.

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 the return, and it does so at the level of catalog contents plus the `slug` field an agent must use. The only minor gap is not stating the exact returned entry structure, but nothing critical to invoking the call 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, which is the baseline-4 case. The description still surfaces the `slug` field that the sibling create_instance consumes, giving useful semantic context even though this tool itself has no inputs to document.

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

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

The description names the resource explicitly (ready environments a server can start with) and enumerates the concrete templates available, so an agent knows exactly what this call yields. The verb 'list' is only implied by the name, but the content is unambiguous and clearly distinct from siblings like list_gpu_models or list_instances.

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 second sentence gives direct, actionable routing: pass the `slug` as `template` to create_instance, which ties this read call to the downstream write call. It does not state explicit exclusions, but for a parameterless catalog call the when-to-use context is effectively covered.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=true, so safety and open-world reach are covered. The description adds the default sort behavior ('cheapest matches first unless order says otherwise'), though that default is also stated in the schema's order parameter, and it says nothing about pagination, rate limits, or result freshness beyond 'live prices'.

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 purpose front-loaded and the ordering caveat and chaining hint following immediately. Nothing is repeated or padded.

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

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

For an 11-parameter, no-required search with a fully documented schema, the definition covers purpose, ordering, and the downstream handoff to create_instance. With no output schema, it could say more about what a result row actually contains (price fields, region, GPU spec), which is the only notable gap.

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

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

Schema description coverage is 100%, so all 11 parameters (including defaults for limit and order) are documented in the schema itself. The description contributes no filter syntax, unit, or format detail beyond what the schema already gives, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Search rentable GPU servers (offers) with live prices'), and the parenthetical resolves the term 'offers' used elsewhere. It is clearly separable from siblings get_offer (single offer) and list_gpu_models (catalog lookup).

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

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

Says when the results are useful ('Each result has an offer id for create_instance'), which routes the agent into the correct next step. It does not explain when to prefer get_offer over this search or list any exclusions, so it stops short of explicit alternatives 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?

Beyond the annotations (which already flag non-read-only, idempotent, non-destructive), the description adds two non-obvious behavioral facts: GPU billing resumes and instances:write permission is required, plus a user-confirmation requirement. That is real added value; it stops short of describing failure modes or the response shape.

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

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

Three short clauses, front-loaded with the action and its state constraint, followed by the consequence and the permission requirement. Every clause earns its place with no filler.

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

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

For a single-parameter mutation with no output schema, the description covers what it does, the cost consequence, the authorization requirement, and the confirmation step. Only edge behavior (e.g., calling it on an already-running instance) is left to the idempotentHint annotation.

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 there is a single required instance_id, so the schema carries the parameter burden. The description adds no format or sourcing guidance for the id, so the baseline 3 applies.

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

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

States a specific verb and resource ('Starts a stopped server again') and narrows scope to stopped instances, which separates it cleanly from create_instance, stop_instance, and destroy_instance. An agent can pick it out of the sibling list 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?

The phrase 'Starts a stopped server again' gives the precondition for use, and 'Confirm with the user' and 'Needs instances:write' give operational context. It does not explicitly name an alternative tool or state when-not to use it, but the applicable state (stopped) is unambiguous.

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

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

Adds real substance beyond annotations: billing behavior, disk data retention, the non-reversible-in-practice risk that the GPU may be taken by someone else on restart, and the required scope (instances:write). This is exactly the operational context annotations like destructiveHint=false cannot convey, and nothing conflicts 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?

Front-loaded effect plus consequence in the first clause, then retention, then the restart caveat and permission. The nested parentheses in the final sentence make it slightly denser than necessary, but no sentence is 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 one-parameter mutation with annotations present and no output schema, the description covers cost, retention, reversibility, and authorization. The only gap is that it never hints at what comes back from the call, which is minor given the tool's simplicity.

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 (instance_id) and schema coverage is 100%, so the schema already carries the meaning. The description adds no format or sourcing guidance for instance_id, leaving this at the baseline for a fully documented single-param 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?

Specific verb ('Stops') plus resource ('a running server') with the immediate consequence (GPU released, billing drops to disk only). The statement that data is kept and the server can be started again implicitly separates it from destroy_instance in the sibling list, so an agent can pick 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?

Gives clear context for when to use it (want to stop paying for GPU but keep disk contents) and the caveat that the GPU may be reassigned on restart. It doesn't explicitly name destroy_instance as the permanent-delete alternative, which is the one obvious comparison an agent would want 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 give readOnlyHint=true and openWorldHint=false, but the description adds behavior the annotations cannot convey: the output is a URL the user must open externally, the payment flow happens outside the API, and the amount is only a pre-fill. This is meaningful context, though it does not cover link expiry or reuse 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?

A single dense sentence that front-loads what the tool produces and then qualifies the payment channel and optional parameter. 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 and only two optional, fully documented parameters, the description covers everything an agent needs: what is returned (a link), what the agent must not attempt (API payments), and how amount behaves.

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. The description adds value by clarifying that 'amount' is optional and only pre-fills the page rather than charging it, and it names the supported payment rails (SBP, crypto), which the schema does not mention.

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

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

The description names the concrete resource (balance top-up page link) and the mechanism (SBP, crypto, opened in a browser), and states that no payment occurs via the API. This immediately distinguishes it from every sibling tool, which are all instance/SSH/offer management 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?

It clearly signals the channel of use — the link is 'for the user to open in a browser' and 'payments never happen through the API' — which tells an agent when this tool is the right choice. It stops short of explicitly stating the trigger condition (e.g., user wants to add funds), so it is clear but not fully prescriptive.

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