UpCloud MCP by usefulapi

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

Adds substantial behavior beyond the annotation: additive/nothing-overwritten semantics, per-GB billing, and the async state machine (backuping/maintenance -> online) with the exact tool to poll. The only tension is that destructiveHint=true over-generalizes a state-changing, billable operation, while the description clarifies nothing is overwritten; this reads as useful disambiguation of a coarse hint rather than a misleading claim.

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

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

Three dense sentences with the core action front-loaded, followed by cost/state caveats and the poll target. Every clause earns its place; no filler or restatement of the title.

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

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

With no output schema, the description compensates by explaining what happens after the call (state transitions, how to observe completion via upcloud_get_storage) and the billing implication. An agent has everything needed to invoke and then correctly handle the asynchronous result.

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

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

Schema description coverage is 100% (both title and storage_uuid are documented with format guidance), so the schema carries the parameter burden. The description adds no parameter-level detail (e.g., title uniqueness or naming implications), making the baseline 3 appropriate.

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

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

States a specific verb+resource+scope: "Take an on-demand, point-in-time backup of a storage device." This is a distinct action not covered by any sibling (the list is dominated by get/list/modify/start/stop), and the UpCloud endpoint footer pins the exact operation.

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?

Clear context for use (on-demand backup) and it routes the agent to the follow-up tool it will need: poll upcloud_get_storage during the async operation. It does not explicitly state when *not* to back up or any quota/limit alternatives, so it stops short of a 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?

readOnlyHint=true already declares the safe read profile, and the description adds real value on top: it discloses the returned content and hints that the call is inexpensive, useful for an agent weighing it against heavier calls. It stops short of detailing auth scope 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?

Three short sentences, front-loaded with the resource and its contents, then usage, then the backing endpoint. Every clause carries information; no 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?

With no params and no output schema, the description correctly carries the burden of describing the return payload and is complete for such a simple read. Only minor omissions (format details, whether limits are absolute or quota) keep it from a 5.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to clarify beyond confirming it operates on 'the calling account' with no inputs.

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: retrieves 'the calling account' and enumerates what comes back (username, credits, resource limits). It is distinguishable from the many list_* and get_* siblings by resource, though it does not explicitly contrast itself with near-neighbors like get_billing_summary.

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?

Offers one clear usage scenario ('A cheap way to confirm the token works'), which is genuine guidance, but gives no when-not conditions and names no alternative tools for overlapping needs such as billing or limits.

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

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

readOnlyHint=true already declares the safety profile, so the description need not restate read-only semantics. It does add genuinely useful behavior context beyond annotations: the account permission required to read billing, and the exact response shape (per-resource fields plus totals).

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 its contents in a single dense sentence; the prerequisite follows. The trailing raw HTTP endpoint ('GET /1.3/account/billing/summary/{yearmonth}') earns little for an agent choosing a tool, slightly diluting 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 two-parameter read-only tool with no output schema, the description carries the needed return-value burden by enumerating the per-resource fields (amount, hours, plan, zone, labels) and totals, and covers the auth prerequisite. Nothing essential 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 both yearmonth (with its YYYY-MM pattern) and the optional resource_id filter are fully documented in the schema. The description only reinforces the one-month scope and hints at per-resource filtering without adding format or edge-case detail, 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 ('Billing summary for one month') plus the exact content it returns (per-resource details and totals). No sibling tool covers billing, so there is no ambiguity an agent needs resolved.

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 one-line prerequisite ('Needs an account allowed to read billing') tells the agent when the call is valid, but there is no explicit when-to-use/when-not guidance or comparison to alternatives. Usage is only implied by the scope of the returned data.

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 the description reinforces this by citing the read-only GET /1.3/server/{uuid} endpoint. It adds no further behavioral context such as error behavior for missing UUIDs or freshness of data. With annotations carrying the safety profile, a 3 is appropriate.

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

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

Two tight sentences, front-loaded with the field inventory, with the API endpoint tacked on efficiently at the end. The field list is long but each item is a genuinely informative return-value hint 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?

There is no output schema, so the description's enumeration of returned fields is doing real work in telling the agent what comes back. The single parameter is fully documented by the schema. Complete for a simple read-by-ID tool, though endpoint/error behavior 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?

Schema description coverage is 100% and the UUID pattern is fully specified in the schema, so the schema does the heavy lifting. The description adds no syntax or format detail beyond it. Baseline 3 is correct.

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 full details) and resource (one server), and the enumeration of returned fields (state, plan, cores/memory, interfaces, storage, firewall, backup, labels, tags) makes the scope unmistakable. It is clearly distinguished from sibling upcloud_list_servers, which returns many servers.

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 'one server' and the UUID parameter — fetch details for a specific known server — but the description never states when this is preferable to upcloud_list_servers or names any alternatives or prerequisites. Adequate but with a clear gap in routing guidance.

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

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

readOnlyHint=true already establishes the safety profile, and the description adds real context: the state field can be transitional ('backuping') and the tool is intended for polling an in-progress backup. It does not mention failure behavior for an unknown UUID or any rate/latency caveats, so not a 5.

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

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

Three tight sentences, front-loaded with the returned-field summary, followed by usage and the underlying API path. The 'UpCloud: GET /1.3/storage/{uuid}' trailer is mildly redundant but cheap and helps map to the documented endpoint.

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

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

With no output schema, the description carries the burden of describing returns, and it enumerates the meaningful response fields plus the polling use case. For a single-parameter read tool with annotations covering safety, 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?

Only one parameter, storage_uuid, and schema description coverage is 100%, so the schema already documents it fully. The description adds no syntax or format detail beyond the schema (it doesn't even restate the UUID), 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 ('Details of one storage') and enumerates the notable fields returned (size, tier, state, encryption, attachments, backups, backup_rule). The scope word 'one' distinguishes it from the sibling upcloud_list_storages, so an agent can route 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 when-to-use guidance: 'Poll this to follow a backup started with upcloud_create_storage_backup.' That ties it to a named sibling and a workflow. It lacks an explicit when-not-to-use (e.g. use upcloud_list_storages for enumerating many), 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 only declare readOnlyHint=true. The description adds genuinely new behavior: the 180-day retention ceiling, the exact facets of each record (actor, resource, timestamp, IP, origin), and that the response carries total_count for paging. It stops short of describing pagination mechanics or auth requirements, 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?

Three dense sentences: purpose and scope first, filter capability second, return/paging note plus the raw endpoint last. No filler and every clause carries 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 should shoulder the return-value burden; it does name total_count and the record facets, but the actual field names/shape of a log entry are not spelled out. Combined with full schema coverage and a read-only annotation, the definition is nearly complete for an 8-param read 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 description coverage is 100%, so the schema already documents all 8 parameters including enums and defaults. The description only restates the filter names and loosely glosses 'q' as UUID/username/IP, adding no syntax or format detail beyond what the schema provides. 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 resource ('Security audit trail of the account') and scope ('up to 180 days') with the exact dimensions captured ('who did what to which resource, when, from which IP and via API or Hub'). It is immediately distinguishable from every sibling, none of which touch audit logs.

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 enumerates the filter axes (action, origin, resource type, time window, keyword) which implies how to narrow results, but never states when this tool should be reached for versus other account tools or what prerequisites exist. There is no explicit when/when-not guidance, only implied usage.

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

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

Annotations only declare readOnlyHint=true; the description goes further by warning that responses 'can include connection URIs with credentials', which is genuinely valuable sensitive-data disclosure for an agent handling the output. It also itemizes the returned fields (state, component hosts/ports, backups, labels), though it does not discuss pagination defaults beyond what the schema already states.

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 sentences, front-loaded with the resource and engines, then return fields, then the credentials caveat. Every sentence carries information; the field enumeration is long but directly useful given there is no output schema.

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

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

With no output schema, the description usefully compensates by listing the returned fields and flagging credential-bearing URIs, covering the security-relevant behavior an agent needs. Remaining gaps (pagination behavior, tenancy scoping) are minor and partly covered by the schema.

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

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

Schema description coverage is 100%, so label, limit, and offset are fully documented in the schema (filtering semantics, 0-100 range, API default 10). The description adds nothing about parameters, 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 clear verb+resource (list Managed Database services) and enumerates the returned fields, plus names the concrete engines (PostgreSQL, MySQL, Valkey, OpenSearch), so an agent knows exactly what this returns. It does not explicitly differentiate from sibling list tools, but no sibling targets the same resource, so the gap is minor.

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 never says when to use this tool versus alternatives, nor mentions prerequisites, tenancy scoping, or any exclusion. Usage is only implied by the phrase 'managed database services'. Sibling list tools exist but no routing guidance is offered.

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

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

Annotations only declare readOnlyHint=true, so the description usefully adds that rules are returned in evaluation order and what each rule's fields mean (position, direction, action, family, protocol, address/port ranges, comment), plus the non-obvious fact that enablement state is not in this payload. It does not mention pagination or result-size behavior, so it is not fully transparent.

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

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

Three tight sentences, front-loaded with the primary content and ending with the API endpoint mapping. The parenthetical field list is dense but earns its place since no output schema 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 carries the return-value burden and does so by enumerating the fields and their ordering, plus flagging the separate firewall-enabled lookup. Nothing critical is missing for a single-parameter read tool, though pagination/limits are unaddressed.

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 required parameter (server_uuid) with 100% schema description coverage, so the schema already documents it and the baseline is 3. The description adds nothing about the UUID format or where to obtain it, but nothing is missing either.

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

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

Names the specific resource (firewall rules of one server) and enumerates the returned fields in evaluation order. It also distinguishes itself from upcloud_get_server by explaining that the enabled/disabled flag lives there, but the verb itself ('list') comes only from the title and no other sibling is 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?

The description implies when to use it (to inspect a server's firewall rules) and provides one useful routing hint—check the `firewall` field of upcloud_get_server to know if the firewall is even active. However, there is no explicit statement of when to prefer this tool, no exclusions, and no prerequisites (e.g., that server_uuid must reference an existing server).

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

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

readOnlyHint=true already establishes the safe-read profile, so the bar is lower, and the description usefully discloses that the scope is the entire account (unfiltered, no query options). It says nothing about pagination, result size, permissions, or ordering, which are the remaining behavioral traits an agent would want for a listing call.

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

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

One sentence front-loads the scope and then lists the returned fields; the trailing 'UpCloud: GET /1.3/ip_address' is a compact endpoint anchor. Nothing is padded or repeated, and the ordering puts the most decision-relevant information first.

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 what comes back and does so field by field, which is genuinely helpful. The only gap is operational detail such as pagination or ordering for a list that could be large.

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 field enumeration in the description describes return values rather than inputs and does not conflict with the empty schema.

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

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

States the resource precisely ('Every IP address on the account') and enumerates exactly what the result contains, from address family to release policy. An agent can distinguish this from upcloud_list_networks, upcloud_list_servers and the other list_* siblings without opening a schema, since no sibling covers IP addresses.

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 resource and the all-encompassing scope ('Every IP address on the account'), which signals that no filtering is offered. There is no explicit when-to-use, when-not-to-use, or pointer to an alternative tool, so it stays at the minimum-viable level.

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

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

The readOnlyHint annotation already establishes this is a non-mutating read, so the description doesn't need to carry the safety profile. It adds useful context by disclosing the shape of the returned records (including nested node-group fields), but says nothing about pagination, result limits, or whether clusters across all zones are returned.

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 compact sentence that front-loads the resource and its attributes. The trailing 'UpCloud: GET /1.3/kubernetes' is minor redundant metadata, but it does anchor the tool to a concrete API endpoint.

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

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

With no input parameters and no output schema, the description's field enumeration is what tells the agent what comes back, making the definition largely self-sufficient for a simple read-only list operation. Only the absence of pagination/scope details keeps it short of complete.

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

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

The tool takes zero parameters and the schema is empty, so the baseline is 4. The description correctly implies an unfiltered full listing rather than hinting at hidden filter arguments.

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

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

States a specific verb and resource ('Managed Kubernetes clusters') and enumerates the attributes returned (name, uuid, zone, plan, state, node groups), so the agent knows exactly what this retrieves. It does not name or differentiate itself from sibling list tools (list_servers, list_databases), but the resource noun is unambiguous.

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

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

There is no when-to-use or when-not-to-use guidance, no prerequisites, and no mention of alternative tools. The description is purely a field inventory; an agent must infer that this is the tool to call when it needs Kubernetes cluster inventory.

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

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

Annotations already declare readOnlyHint=true, so the safe read nature is covered. The description usefully adds what the listing contains (frontends, backends, members, networks, plan, zone, status) and the underlying endpoint. However, it does not disclose pagination defaults or result-size behavior beyond what the schema states.

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: the resource content is front-loaded and the endpoint follows. No filler or redundancy, though the endpoint reference is arguably decorative for an agent.

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

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

With no output schema, the description carries the burden of describing returns and does so by enumerating the included components. Given a simple 3-param read-only list tool, this is reasonably complete, though it omits any usage context.

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 label, limit, and offset are fully documented in the schema. The description adds nothing about parameter semantics, 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 title plus description make clear this lists managed load balancer services and even enumerates the returned sub-resources (frontends, backends, members, networks). It is a noun-phrase description with no explicit verb, but the resource is unambiguous. It does not distinguish itself from any sibling via description text.

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

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

The description gives no when-to-use guidance, no prerequisites, and names no alternatives. An agent gets no signal about when this list tool is preferred over other options or how it relates to the create/get siblings.

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

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

readOnlyHint=true already declares the safety profile, so the bar is lower. The description adds genuinely useful context beyond the annotation: the scope of visibility (account-visible networks), the per-entry contents (subnets, DHCP, routes, attached servers, peerings), and the underlying GET /1.3/network/ endpoint.

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

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

Two tight sentences with the resource and scope front-loaded, followed by the endpoint reference. Only the API-path tail is arguably expendable, but it is short and useful for disambiguation.

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 naming the fields returned per network, which is what an agent needs to decide relevance. It omits pagination/ordering behavior and says nothing about the label parameter, but coverage is largely adequate for a read-only 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?

Schema description coverage is 100%, so both parameters are already documented in the schema. The description only echoes the zone filter ('Optionally only one zone') and says nothing about the label filter, so it adds little beyond the schema — 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 (list networks) and enumerates the network kinds returned — public, utility and private SDN — plus the fields each entry carries. This clearly separates it from siblings such as upcloud_list_zones or upcloud_list_servers.

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 'Optionally only one zone' implies the filtering context, but there is no explicit when-to-use guidance, no prerequisites, and no named alternative (e.g. a get-network-by-id tool). Usage is only implied.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying API route (GET /1.3/object-storage-2) and the shape of returned entities, which is useful context beyond the annotations, but it says nothing about pagination behavior, result volume, or auth scoping.

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 fragments with the resource and its returned fields front-loaded, then the API reference. Nothing is wasted, though the sentence is terse enough that it reads more like a field dump than a directive.

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 field enumeration in the description does real work in telling the agent what comes back. Combined with the readOnlyHint annotation and the fully documented parameters, the definition is nearly self-sufficient; only routing/pagination guidance is absent.

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

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

Schema description coverage is 100%, and each of sort/limit/offset already documents defaults, ranges, and the descending-prefix convention. The description adds no parameter meaning at all, so the baseline 3 for a fully documented schema is appropriate.

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

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

The description names the resource precisely ('Managed Object Storage (S3-compatible) services') and enumerates the fields returned (uuid, name, region, status, endpoints, domains, labels), which tells an agent this is a read/list operation over object-storage services. It implicitly distinguishes itself from the block-storage sibling upcloud_list_storages via 'S3-compatible' and the endpoint, but never names or contrasts 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?

There is no when-to-use guidance, no mention of when to prefer upcloud_list_storages or upcloud_get_storage, and no stated prerequisites or pagination caveats. The agent must infer usage purely from the resource name.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds context about what data plans contain (fixed-price, included storage/transfer, GPU details) but does not disclose any behavioral traits like pagination, result limits, or authentication needs beyond what the annotations provide.

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

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

The description is two sentences: one front-loaded with the resource and its fields, and one giving the API endpoint. It is appropriately sized and free of filler, though the first sentence is a fragment rather than a complete statement of the tool's action.

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 it does so by listing the fields included in each plan. It does not mention pagination or ordering, but for a simple parameterless list tool, the provided context is largely sufficient.

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

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

The tool takes zero parameters, so there are no parameter semantics to document. The baseline score of 4 applies because the description does not need to compensate for any missing parameter information.

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

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

The description identifies the resource (fixed-price server plans) and enumerates the fields each plan contains (name, cores, memory, storage, transfer, GPU details), making the tool's data scope clear. However, it does not explicitly state the operation ('list') and does not differentiate from siblings like upcloud_list_prices, leaving the agent to infer the action from the tool 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?

The description provides no guidance on when to use this tool versus alternatives such as upcloud_list_prices or upcloud_list_zones. There are no conditions, exclusions, or prerequisites mentioned, leaving the agent with only the name to infer usage context.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuine context beyond that: prices are per-hour, per-zone, and expressed in the account's currency. It does not disclose auth requirements, caching/staleness of prices, or whether all zones are returned at once.

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 sentence leads with the core concept and itemizes coverage, followed by a short UpCloud API endpoint mapping. No filler, though the endpoint line is marginally redundant for an agent that cannot call the REST API directly.

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

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

With no output schema and no parameters, the description does the heavy lifting by enumerating the returned price categories and their per-hour granularity, which is what an agent needs to decide relevance. It stops short of saying whether every zone is returned or how to request a single zone.

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. There is nothing for the description to clarify, and it correctly signals the parameterless, whole-account scope implicitly through 'per zone in the account's currency'.

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

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

The description names a specific resource (prices) and enumerates exactly what is covered: per-hour plan, core, memory, storage-tier, backup, IPv4 and traffic prices, scoped to zone and account currency. It is clear but does not explicitly differentiate itself from near-neighbors like upcloud_get_billing_summary or upcloud_list_plans.

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

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

There is no when-to-use guidance: no statement that this is for costing/estimation versus billing history, and no mention of the sibling tools (get_billing_summary, list_plans) an agent should weigh it against. Usage must be inferred from the noun phrase alone.

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

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

readOnlyHint=true already declares the safety profile, so the bar is lower. The description still adds value by disclosing the shape of the response (summary-level only: uuid, title, hostname, zone, plan, cores, memory, state, tags, labels) and by flagging that IPs and disks are deliberately absent — context the annotation alone does not convey. It says nothing about pagination behavior or result totals, which keeps it short of a 5.

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

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

Three tight sentences: what the tool returns, how to narrow it, where to go for more detail, plus the endpoint. The most decision-relevant information (resource + returned fields + sibling routing) is front-loaded 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 low-complexity, zero-required-param list tool with full schema coverage and a readOnly annotation, this description covers everything an agent needs: scope, filterability, response granularity, and the escape hatch to a detail tool. With no output schema, the inline summary-field list adequately substitutes for a documented return shape.

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 every parameter (tag, label, limit, state, offset, search) is already fully documented, including the subtle `a,b` ANY vs `a:b` ALL tag semantics. The description only restates the filter categories the schema defines, adding no new syntax or default information, so the 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?

It names the resource (cloud servers on the account), enumerates the summary fields returned, and states the filter dimensions, so an agent knows exactly what this call yields. It explicitly contrasts itself with upcloud_get_server ('for IPs and disks') and cites the underlying endpoint GET /1.3/server, making it unambiguously the list operation rather than a detail fetch.

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

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

The description gives clear context on when this is the right call (broad enumeration, filterable by state/search/tag/label) and routes the agent to upcloud_get_server when IP and disk detail is needed. It does not spell out when-not to use it or mention other list siblings, but the primary alternative is named with the condition that selects it.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /1.3/storage[/{kind}]) and the fact that omitted `kind` returns everything accessible, but says nothing about result size, pagination, or authorization requirements.

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

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

Three dense, front-loaded segments: resource scope, filter semantics, underlying API path. No filler sentences, and the most decision-relevant information (what it lists, how to narrow) comes first.

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 parenthetical field list (uuid, title, type, tier, size GB, state, zone, labels) usefully tells the agent what a result contains, and the filter semantics are covered. Missing only secondary details like pagination or auth scope, which are minor for a read-only 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the enum alone does not: it glosses each `kind` value (private = yours, public = UpCloud-provided, normal = disks) and explains the private/public axis. The `label` filter is fully documented 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?

The description names the resource concretely and enumerates what counts as a storage device (disks, backups, CD-ROM images, OS templates), which is a specific scope. It does not explicitly distinguish itself from near siblings such as upcloud_get_storage (single item) or upcloud_list_object_storages, so sibling differentiation is left to inference.

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 `kind` values and the schema's 'Omit for every accessible storage' convey the filtering options, but the description never states when to reach for this tool versus upcloud_get_storage or upcloud_list_object_storages. No exclusions or prerequisites are given.

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating read. The description usefully adds the shape of the returned records (id, description, visibility) and the backing endpoint (GET /1.3/zone), which matters since there is no output schema. It does not mention pagination, result ordering, or auth requirements, so it adds value without being rich.

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

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

Two short sentences plus an endpoint reference, front-loaded with the resource and its returned fields. Every clause earns its place and nothing needs to be scrolled past to reach the essential 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 input parameters and no output schema, the description carries the burden of telling the agent what comes back, and it does so adequately by naming the three returned attributes. Minor gaps remain around whether the list is paginated or sorted, but for a simple global lookup this is close to sufficient.

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. The id-format examples (fi-hel1, de-fra1, us-chi1) describe return values rather than inputs, so they don't add parameter semantics, but there is nothing to under-document.

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

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

States a specific verb (list) plus the resource (zones/data centres) and enumerates the returned fields (id, description, public/private cloud) with concrete id examples. It's the only zone-related tool among the siblings, and the note that zone ids are consumed by every other resource makes its distinct role 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?

"Zone ids are used by every other resource" gives clear context for why and when an agent would call this first, e.g. to resolve a zone id before creating servers or storages. It stops short of explicit when-not guidance or naming alternatives, but for a zero-parameter enumeration tool the usage context is well signalled.

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?

It discloses the underlying API call (PUT /1.3/server/{uuid}), the accepted simple_backup grammar including UTC interpretation, and the disabling value 'no' — context the annotations do not carry. The 'reversible fields' claim sits in mild tension with destructiveHint=true, but since renaming and backup-schedule changes are recoverable, this is a conservative annotation rather than 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?

Three tightly packed sentences, front-loaded with the action and its scope, then exclusions, then the backup format. No filler sentences; every clause adds operational value.

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

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

With no output schema, the description covers the mutation surface, the exclusion boundaries, the backup string format, and the API endpoint — enough for correct invocation. It does not describe return values or whether partial updates are supported, which is a minor gap.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: the UTC timezone for simple_backup and the semantics of 'no' to disable. The server_uuid parameter is only implied ('a server's'), not explicitly called out.

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

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

The description names a specific verb (Change) and the exact resource fields (title, hostname, simple-backup schedule), and explicitly contrasts with what it does not do. An agent can distinguish it from start/stop/restart and get_server siblings 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 clearly scopes usage with explicit exclusions ('no resizing or plan change (billing) and no firewall toggle'), which steers the agent away from misuse. It lacks an explicit pointer to a sibling alternative (e.g. when to use get_server first), so it stops short of full when/when-not/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?

It discloses critical behavior beyond the destructiveHint annotation: the operation is DISRUPTIVE, soft restart requires a timeout, timeout_action=destroy causes a hard-stop-and-restart, ignore aborts and leaves the server running, and hard power-cycles immediately. This gives the agent enough context to understand the consequences of parameter choices.

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 compact and front-loads the most important warning (DISRUPTIVE). Every sentence earns its place by explaining restart modes, timeout behavior, or the underlying API call.

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

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

For a restart tool with no output schema, the description covers the operation's disruptive nature, the soft/hard modes, default behavior, timeout semantics, and the API endpoint. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents all parameters, which establishes a baseline of 3. The description adds useful nuance by clarifying that soft is the default, that a timeout is required for soft, and that ignore is the API default for timeout_action.

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: restarting a running server by stop-and-start. It clearly differentiates restart behavior from sibling tools like start_server and stop_server by describing both phases and the soft/hard restart modes.

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 when to use restart by explaining its disruptive nature and restart modes, but it does not explicitly say when to choose this over stopping/starting separately or modifying a server. No alternatives or prerequisites are 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?

Adds real value beyond the destructiveHint annotation: it explains why the operation is flagged as affecting the account ('billing for a started server resumes'), the exact failure mode (409 when not stopped), and the async contract with the follow-up tool to poll. That is rich behavioral disclosure for a two-parameter tool.

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

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

Three short sentences, each carrying a distinct load: action plus precondition, failure condition, async/polling guidance. The critical constraint is front-loaded and nothing is padded.

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

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

With no output schema, the description compensates by telling the agent how to confirm completion (poll get_server for state=started) and what error to expect. There is no output_schema to defer to, and nothing an agent needs in order to invoke this correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description goes further by spelling out the consequence of async (returns immediately, poll upcloud_get_server for state=started) and framing sync as the waiting default, which is more than the enum's terse 'returns at once'.

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

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

States a specific verb+resource ('Start a stopped server') with the precondition baked into the sentence, which cleanly separates it from upcloud_stop_server, upcloud_restart_server, and upcloud_get_server without needing 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 the operative precondition ('Fails with 409 if it is not stopped') and routes the agent to upcloud_get_server polling for the async path. It does not explicitly contrast with upcloud_restart_server, but the 'stopped server' framing makes the boundary clear enough.

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 supply destructiveHint=true; the description goes well beyond that by disclosing the disruption (server goes offline until restarted), the ACPI-vs-power-cut semantics, the timeout-triggered hard stop, and the data-loss risk of hard. That is exactly the behavioral context a destructiveHint flag 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?

The warning is front-loaded in the first clause, and every subsequent sentence carries new information (escalation behavior, data-loss risk, endpoint). No filler or restatement of the title.

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

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

For a no-output-schema mutation tool, the description covers the essential behavior, side effects and safety profile. It does not address edge cases such as stopping an already-stopped server or whether the call blocks until completion, which would matter for correct invocation sequencing.

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 genuinely adds meaning: it states soft is the default and, critically, that supplying a timeout causes a hard stop to follow if the soft stop does not complete. That interaction between timeout and stop_type is not derivable from the schema alone.

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 (stop) plus resource (running server), with scope stated up front as DISRUPTIVE. It explicitly contrasts itself with upcloud_start_server, so an agent can distinguish it from siblings like upcloud_restart_server without opening a schema.

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

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

It names the follow-on alternative (upcloud_start_server) and explains the soft/hard selection logic including the timeout escalation path, which is clear usage context. It stops short of an explicit exclusion, e.g. 'use upcloud_restart_server if you intend to bring the server back up immediately', leaving one sibling relationship to inference.

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