Civo MCP by usefulapi

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

Annotations only carry destructiveHint=true and a title, so the description does real work: it discloses that changes go live and propagate publicly, and that no delete/undo tool is offered here. That meaningfully expands on the destructiveHint flag. It stops short of stating auth requirements, propagation timing, or whether duplicates are rejected.

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 core action, then the consequence, then the reversal path. No filler; the API endpoint reference is compact and additive.

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

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

For a 6-parameter create tool with no output schema and minimal annotations, the description covers action, live-effect consequence, and reversal, which is most of what an agent needs. It omits what the call returns (e.g. the new record's id), which would be needed for later update/delete operations.

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 every field (including ttl, priority, and the @ apex convention) is already documented in the schema, so the baseline of 3 applies. The description contributes nothing extra about parameter semantics, such as type/value coupling (MX and SRV needing priority) or how name interacts with domain_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 ('Add one record to a Civo-hosted domain'), with the scope qualifier 'one' so the agent knows this is a single-record create, not a bulk import. It is trivially distinguishable from the sibling civo_list_dns_records and the broader get/list family.

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 create semantics, and the description usefully explains that reversal happens outside this tool ('delete the record in the Civo dashboard or CLI'). However, it never states when to prefer this over alternatives or what prerequisites (e.g. an existing domain from civo_list_dns_domains, or a valid domain_id) are needed before calling.

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

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

Annotations already flag destructiveHint=true, and the description goes further by explaining the blast radius ('changes what is reachable on every instance, cluster and load balancer') and the undo method. It does not cover auth requirements or rate limits, but the added context is substantial.

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

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

Four short sentences, each earning its place: purpose and example first, then impact, undo, and API endpoint. No unnecessary repetition or 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 nine-parameter mutation with no output schema, the description supplies the missing behavioral context—impact, reversibility, and API mapping—while annotations cover the destructive hint. It omits success/return behavior, but that is a minor gap given the absence of an output schema.

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

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

Schema coverage is 100%, so the schema already documents all nine parameters. The description adds a concrete example ('allow TCP 443 ingress from 0.0.0.0/0') and advises narrow CIDRs, which maps parameters to a real use case beyond the schema's field definitions.

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 ('Add') and resource ('one rule to a firewall') with a concrete example, making its function unmistakable. It does not name a sibling tool to contrast with, so it stops short of perfect sibling differentiation.

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

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

Offers implied context (use when adding a rule) and a safety guideline to prefer narrow CIDRs, plus an undo path via dashboard/CLI. It never states when not to use this tool or names an alternative (e.g., civo_list_firewall_rules for inspection), leaving the agent to infer 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 already declare readOnlyHint=true, so the description is not carrying the safety burden. It still adds genuine value beyond the annotations: 'Passwords are redacted' discloses a non-obvious property of the returned payload, and the trailing 'Civo: GET /v2/instances/{id}' pins the underlying operation. It says nothing about auth requirements, error cases, or pagination, so it falls 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?

A single dense sentence that is front-loaded with the verb and the payload highlights, followed by a short API reference. Every clause carries information; the only mild cost is a long comma-delimited field list that reads as inventory rather than prioritised prose.

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

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

With no output schema, the description is right to enumerate the returned fields, and both parameters are fully documented by the schema. What is missing is the idiosyncratic behavior of the response (what happens for a nonexistent id, whether the redaction affects any other fields), so it is strong but not exhaustive.

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%, including the region default (CIVO_REGION) and the regional-resource caveat, so the schema already does the heavy lifting. The description adds no parameter-level meaning (it never mentions instance_id or region), which is exactly the baseline-3 case.

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 ('Fetch one instance') and then enumerates the returned attributes (status, size, CPU/RAM/disk, IPs, network, firewall, tags, volumes, source image), which makes it unambiguous versus the sibling civo_list_instances. An agent knows exactly what class of tool this is 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?

Usage is only implied: fetch by id when you already have the instance id. There is no explicit when-to-use/when-not, no mention of civo_list_instances as the discovery alternative, and no stated prerequisite about needing the id first. Adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description still earns credit by disclosing that the kubeconfig is redacted (i.e., credentials are not returned) and by pinning the exact upstream call, GET /v2/kubernetes/clusters/{id}. It stops short of describing error/404 behavior for a missing or cross-region cluster.

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

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

One front-loaded sentence carries the payload enumeration, then a short second clause carries the redaction caveat plus the raw endpoint. No filler, no restatement of the tool name, and the highest-value information 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?

There is no output schema, so the description's enumeration of returned fields (status, conditions, pools, network, firewall, CNI, apps) is exactly the compensating detail an agent needs to know what it will get back, and it flags the redacted kubeconfig. With only two parameters, full schema coverage, and a readOnly annotation, nothing material is missing.

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

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

Schema description coverage is 100%, so both cluster_id (UUID) and region (with defaults to CIVO_REGION and the regional-resource caveat) are already fully documented in the schema. The description only echoes the id in the endpoint path and adds nothing about parameter format beyond that, which is the expected baseline when the schema does the work.

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 ('Fetch one') and resource ('Kubernetes cluster') and then enumerates the returned facets (status, readiness, conditions, version and available upgrade, pools, network, firewall, CNI, marketplace apps). The word 'one' cleanly separates it from the sibling civo_list_kubernetes_clusters, so an agent can pick between them 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?

Usage is implied by 'Fetch one Kubernetes cluster' paired with the singular cluster_id requirement, and the endpoint template shows it is an id-addressed lookup. However, there is no explicit statement of when to prefer this over civo_list_kubernetes_clusters, nor any note about what happens when the id is unknown or the region is wrong.

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 read, so the bar is lower. The description adds useful scope (which resources' limits/usage are reported) but says nothing about response shape, refresh/lag of usage data, or permissions — moderate added value only.

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 return content, then the practical use case, then the API endpoint. The long resource enumeration earns its place because there is no output schema to convey the coverage.

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 must carry the return-value burden; it lists the covered resources and states that both limits and usage are returned. It stops short of describing structure/units, which an agent might still want, but is largely complete for a simple 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?

The tool takes zero parameters, so there is nothing to disambiguate; baseline 4 applies. The description correctly implies no input is required.

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

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

The description states a specific resource (the account's quota: limits and current usage) and enumerates the resource categories it covers, so an agent can distinguish it from the many list_* siblings. The verb 'get' is carried by the name/title and the enumerated scope makes the output 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 phrase "Answers 'can I launch another one?'" gives a concrete decision context — check capacity before provisioning. It doesn't name alternatives or exclusions (e.g., use list_charges for billing), so it's clear context without explicit routing.

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

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

Annotations declare readOnlyHint=true, and the description adds non-obvious behavior: the 31-day maximum range and default window, plus the shape of each returned row and the volume exception. It doesn't mention pagination or rate limits, which keeps it short of a 5 given annotations carry the safety profile.

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-loading the purpose before the range constraints. The trailing 'Civo: GET /v2/charges' is a minor extraneous API-pointer that an agent doesn't need, but it costs little.

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

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

For a two-param read tool with no output schema, the description supplies the returned-field inventory, the default window and the range cap, which is enough to call it correctly. Only return-size/pagination behavior is left unspecified.

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

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

Schema description coverage is 100%, so both parameters (from/to, RFC 3339 with pattern) are already fully documented. The description restates the defaults in prose but adds no format or syntax detail beyond the schema, matching the baseline 3.

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

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

States a specific verb+resource ('List billable usage for a period') and enumerates the returned fields (product code, label, region, time span, hours, size_gb for volumes). No sibling tool covers billing/charges, so the agent can immediately distinguish it from the instance/firewall/DNS list 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?

Describes default behavior (from = start of current month, to = now) and the 31-day cap, which tells the agent how to call it in the common case. However, it gives no explicit when-to-use or when-not-to-use guidance against alternatives, and the usage is only implied by the defaults.

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 results are paginated, that passwords are redacted, and that Civo resources are region-scoped. It does not cover rate limits or auth requirements, but the added context is meaningful beyond the annotation.

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 plus an API reference line, all front-loaded with the resource and scope before the pagination and redaction details. 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?

With no output schema, the description carries the burden of describing the return payload, and it does list the key database attributes and the pagination envelope plus the redaction behavior. It stops short of noting result ordering or empty-result behavior, but is largely complete 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 all three parameters are already documented in the schema. The description restates pagination via the {page, per_page, pages, items} shape but adds no new syntax or constraint meaning for page/per_page/region, 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 (List) and resource (managed databases), names the supported engines (MySQL, PostgreSQL), and enumerates the returned attributes (version, size, nodes, IPs, port, network, firewall, status). No sibling tool covers databases, so the agent can place it immediately in the catalog.

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 'in a region' implies regional scoping, but there is no explicit when-to-use/when-not guidance or pointer to an alternative (there is no sibling database tool to route to). Usage is inferable from the name and the region mention rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered and the bar is lower. The description adds only the upstream endpoint (GET /v2/dns) and the account-wide scope; it says nothing about pagination, result ordering, or what an empty result means, which are the traits an agent would still want for a list operation.

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

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

Two short sentences, zero filler, with the resource scope front-loaded before the API reference. Every clause carries information and nothing is repeated from the title or 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?

For a zero-parameter, read-only list tool with no output schema, the description supplies enough to call it correctly: what is listed and whose data. It stops short of describing the shape of the returned collection, which is the only remaining 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?

The tool takes zero parameters, so per the rubric the baseline is 4. Nothing in the description is needed to disambiguate inputs, and it correctly avoids inventing parameters.

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

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

States a specific verb (List) and resource (DNS domains) and scopes it to 'whose DNS Civo hosts for the account'. The noun choice cleanly separates it from the sibling civo_list_dns_records (records, not domains), so an agent can pick correctly without opening the schema.

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

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

The intent (enumerate all hosted DNS domains for the account) is implied by the verb plus the empty parameter set, but there is no explicit when-to-use guidance, no mention that it returns the full account list with no filtering, and no pointer to civo_list_dns_records for the nested-resource case.

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, non-mutating profile. The description adds the underlying endpoint (GET /v2/dns/{domain_id}/records) and the field set returned, which is useful context, but says nothing about pagination or result 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?

Two tight sentences with no waste: the resource scope and returned fields come first, the optional filters second, and the endpoint reference last. Front-loaded and easy to scan.

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

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

With no output schema, the description usefully enumerates the returned fields (name, type, value, priority, TTL), and read-only safety is covered by annotations. It is nearly complete for a scoped list tool, lacking only pagination/limit behavior.

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 three parameters are already documented (name with apex example, type with enum, domain_id as UUID). The description only restates the name/type filters, adding no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (List) and scoped resource (records of one hosted domain), and enumerates the returned fields. It implicitly distinguishes itself from civo_list_dns_domains (domains) and civo_create_dns_record (creation), though it never names a 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?

"optionally filtered by type or name" signals how the filters work, and "of one hosted domain" implies domain_id is the required scope. But there is no explicit when-to-use vs alternatives guidance or any exclusion condition, so usage is only implied.

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

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

Annotations only declare readOnlyHint=true; the description adds the concrete return shape (protocol, port range, CIDRs, direction, action, label) and the underlying endpoint GET /v2/firewalls/{id}/rules. It does not mention pagination, rate limits, or auth scope, 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?

A single dense sentence front-loads the action and resource, then the returned fields, then the endpoint. No filler and nothing redundant.

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

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

For a two-param read-only list operation with no output schema, the description usefully compensates by naming the returned fields and endpoint, and the schema covers region semantics. Only pagination/volumetric behavior is 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?

Schema description coverage is 100%, so both firewall_id and region are already documented, including the CIVO_REGION default and regional caveat. The description adds nothing about parameter syntax beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (rules of one firewall), scoping it to a single firewall so it is distinguishable from civo_list_firewalls and civo_create_firewall_rule. It also enumerates the exact fields returned, making the resource 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 framing 'the answer to "what is exposed to the internet?"' is an implied usage cue, but no explicit when-to-use, prerequisites, or alternative (e.g. civo_list_firewalls for the firewall objects themselves) is named. Usage is inferable but not stated.

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

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

readOnlyHint=true already establishes this as a safe read, so the description only needs to add context. It contributes the Civo REST mapping (GET /v2/firewalls) and discloses the shape of each returned entry (network, rule count, usage counts), which is genuinely useful. It omits pagination, result limits, and any auth/region-default behavior beyond what the schema covers.

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 no filler; the scope ('in a region') and the returned payload are front-loaded before the API reference. 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 takes on the burden of describing returns and does so at a useful level of detail (network, rule count, per-resource usage counts) for a simple one-parameter list call. The only meaningful omission is pagination/result-size behavior common to list endpoints.

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

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

Schema description coverage is 100% and the single 'region' parameter is documented with a pattern, examples, a CIVO_REGION default, and a rationale about regional scoping. The description's 'in a region' adds only a weak tie between the parameter and the operation, 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 ('List the firewalls') and goes further by enumerating the associated data returned per firewall (network, rule count, instance/cluster/load-balancer usage counts). This implicitly separates it from civo_list_firewall_rules, which lists rule objects rather than firewalls. It stops short of a 5 because it never names a sibling or states the boundary 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, when-not-to-use, or alternative-tool guidance. The phrase 'in a region' hints that a region must be supplied, but no prerequisites, pagination expectations, or routing advice (e.g. use civo_list_firewall_rules for rule detail) 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?

Annotations only cover readOnlyHint=true. The description adds real behavioral context beyond them: the pagination envelope shape, that passwords are redacted in the response, and the underlying endpoint. It still omits anything about rate limits or total result caps, 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 with no filler. Scope is front-loaded, pagination and redaction details follow, and the endpoint reference trails — every clause earns its place.

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

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

With no output schema, the description usefully supplies the pagination envelope {page, per_page, pages, items} and notes password redaction, plus region default via the schema. Minor gap: no note on total page behavior or empty results, but an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description only restates the region and tag filters in prose; it adds no syntax, default, or edge-case detail beyond what the schema already documents.

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

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

States a specific verb (List) and resource (compute instances) with scope modifiers (in a region, optionally filtered by tags). This is clearly distinguishable from siblings like civo_get_instance or civo_list_instance_sizes 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?

Usage is implied by the read/list nature and the tag filter, but there is no explicit when-to-use versus when-not, and no sibling is named as an alternative (e.g., use civo_get_instance for a single instance). Adequate minimum-viable guidance only.

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 read. The description adds the upstream Civo endpoint and the shape of the returned payload (plan attributes including GPU), which is modest extra context. It does not mention pagination, caching, or whether results vary by region — gaps that matter for a region-scoped listing.

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

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

One front-loaded sentence carrying the purpose and the return payload, followed by a short endpoint reference. No filler, no 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?

There is no output schema, so the description compensates by enumerating returned fields (cores, RAM, disk, transfer, GPU), which is genuinely useful. What it omits is whether the listing is filtered by region and whether results are complete or paginated — minor gaps for a simple read-only catalog tool.

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

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

Only one parameter exists and schema description coverage is 100%, with the schema fully explaining the region code, format, examples, default, and the regionality caveat. The description adds nothing about region, 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 ('List') and resource ('sizes (plans)'), then enumerates the returned attributes (CPU, RAM, disk, transfer, GPU) and the resource classes they apply to (instances, Kubernetes nodes, databases). This is unmistakably distinct from sibling list tools like civo_list_instances or civo_list_volumes, which return actual resources rather than available 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?

The phrase 'can be launched' implies this is a lookup used before provisioning, but the description never states when to call it versus alternatives or any prerequisites. The only actionable guidance (region scoping, CIVO_REGION default) lives in the schema, not the description.

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 safety is covered. The description adds real value beyond that: the pagination envelope shape {page, per_page, pages, items}, that kubeconfigs are redacted, and the underlying API call GET /v2/kubernetes/clusters.

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

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

Two compact sentences, front-loaded with what is listed and what is returned, followed by pagination behavior and the API mapping. No filler.

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

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

No output schema exists, but the description compensates by enumerating returned fields and the pagination envelope, and flags kubeconfig redaction. Only the absence of explicit alternative-tool guidance keeps it short of full completeness.

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

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

Schema description coverage is 100%, so baseline is 3. The description confirms region-scoped listing ('in a region') and names the paginated envelope, but adds no syntax or constraint detail beyond what the schema already documents.

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

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

States a specific verb (List) and resource (Kubernetes K3s/Talos clusters), plus the fields returned (status, version, node pools, API endpoint, installed applications). The list-vs-get distinction from civo_get_kubernetes_cluster is inferable from the verb but never made explicit.

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

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

No when-to-use guidance is given: nothing says to prefer civo_get_kubernetes_cluster for a single cluster or civo_list_regions to discover valid region codes. The schema param hints at civo_list_regions, but the description itself offers no routing 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?

readOnlyHint=true already declares the safety profile, and the description is consistent with it, adding the concrete endpoint (GET /v2/loadbalancers) and the shape of returned data. It does not mention pagination, auth requirements, or result limits, so it is additive but not rich.

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

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

One front-loaded sentence covering resource, scope, and return fields, plus a short endpoint reference. Dense but every clause carries information; the endpoint tag is marginally useful for traceability.

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

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

With no output schema, the description usefully enumerates the returned fields (algorithm, backends, public IP, state, Kubernetes service), which compensates for the missing schema. Only pagination/result-size behavior is left unspecified, a minor gap for a one-optional-parameter 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% and the single region parameter is fully documented in the schema (pattern, examples, CIVO_REGION fallback). The description only echoes the regional scoping, adding no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (list load balancers) narrowed by scope (in a region), and enumerates the fields returned, so an agent knows exactly what this retrieves. No sibling tool lists load balancers, so there is no ambiguity with the other civo_list_* 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?

The scope phrase 'in a region' implies the intended use and the region parameter, but the description never states when to choose this over alternatives or any prerequisites. Usage is inferable from the purpose rather than stated.

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

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

The readOnlyHint=true annotation already establishes this is a safe read, so the description only needs to add context. It adds the regional scoping constraint and the underlying Civo endpoint (GET /v2/networks), but says nothing about pagination 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?

A single sentence, front-loaded with the action and scope, followed by the returned fields and the endpoint reference. No filler; 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 compensates by enumerating the returned attributes, which is genuinely useful. The only missing piece for a complete picture is pagination/ordering behavior on a potentially multi-item 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?

Schema description coverage is 100% for the single region parameter, which already documents the pattern, examples (LON1, NYC1...), the CIVO_REGION default, and the regionality caveat. The description's 'in a region' phrase adds no syntax or meaning beyond the schema, so the baseline 3 applies.

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

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

The description gives a precise verb+resource ('List the private networks') and qualifies the scope to a single region, plus enumerates the fields returned (label, CIDR, default flag, status, nameservers). It is unambiguous, though it does not need to distinguish itself from any sibling since no other network-listing tool exists.

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: an agent can infer this is the read tool for networks, but there is no statement of when to call it versus e.g. civo_list_firewalls or civo_list_regions, no prerequisites, and no note about whether the region must be active. Adequate but with clear gaps.

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

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

With readOnlyHint=true already declaring the safety profile, the description still adds real value by enumerating what the response contains (default region, out-of-capacity, feature support) and noting the auth-check use case. It does not cover error or edge behavior, but the annotation carries the safety burden.

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 most important content (what is listed and what is returned) leads, followed by the practical auth-check tip and the backing endpoint. Every sentence contributes 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?

There is no output schema, so the description must carry the return-value burden, and it does so explicitly. For a zero-parameter read-only list tool this is fully sufficient to invoke correctly.

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

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

The tool takes zero parameters, so there is nothing to disambiguate and the baseline is 4. The empty schema and description are consistent.

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

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

Specific verb ('List') plus resource ('Civo regions') with an explicit inventory of the returned facets: default flag, capacity status, and supported features. No sibling lists regions, so the tool is trivially distinguishable from the instance, firewall, and database 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?

'A cheap way to confirm the API key works' gives a concrete situation in which to reach for this tool, which is more than a bare restatement. It stops short of explicit when-not guidance or naming an alternative, but there is no competing region tool to route away from.

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 two useful pieces of context beyond that: the exact fields returned and the caveat that unattached volumes still bill. It says nothing about pagination or result limits, which is a gap for a list 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?

A single front-loaded sentence that leads with the verb and resource, then lists returned fields before tacking on the API endpoint reference. The endpoint note is mild redundancy for an agent but costs little; nothing else is wasted.

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

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

With no output schema, the description usefully enumerates the returned attributes and adds the billing caveat, which covers the essentials for a simple regional list tool. Pagination behavior and any filtering capability are unaddressed, but for a one-parameter lister 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 description coverage is 100%, and the region parameter is already documented there with pattern, examples (LON1, NYC1, FRA1, PHX1) and the CIVO_REGION default. The description's 'in a region' adds no syntax or meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the block-storage volumes') and goes further by naming the fields returned (size, status, type, attachment target) and the underlying API call (GET /v2/volumes). No sibling tool overlaps with volume listing, so an agent can identify this unambiguously.

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

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

Usage is largely implied by the verb 'List' and there is no competing volume tool to route against, but the description never states when to call this versus other inspection tools. It does hint at scoping by noting the regional nature and the CIVO_REGION default, which nudges correct invocation.

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

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

Annotations only say destructiveHint=true, but the description discloses the real behavioral traits: what 'hard' actually does ('cuts power ... like pulling the plug'), the risk ordering, and that there is brief downtime. That is meaningful context beyond the annotation.

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: action, mode semantics with risk warning, then the underlying API endpoints. No filler and the risk-relevant warning is front-loaded before the endpoint detail.

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

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

A simple, single-target mutation with full parameter documentation and a clear risk statement — nothing essential is missing. The only omission is that no guidance is given about the resulting instance state or how to confirm the reboot took effect, though with no output schema that is a minor gap.

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

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

Schema coverage is 100%, so a 3 baseline applies, but the description adds genuine semantics beyond the schema's terse 'soft (default) or hard.' by explaining the operational difference between the two modes. Region and instance_id are left to the schema, which documents them adequately.

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 ('Reboot one instance') and immediately distinguishes the two modes. An agent can tell it apart from civo_start_instance / civo_stop_instance without opening any schema.

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

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

Gives explicit when-to-use guidance for each mode: soft is the default, hard should be used 'only when soft does not work.' It does not contrast against the neighboring lifecycle tools (start/stop), but the mode-selection guidance is unambiguous.

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

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

Annotations only declare destructiveHint=true; the description adds real behavioral context beyond that: this is a full replacement, not a merge, and tag changes can move an instance in or out of load-balancer pools. It also pins the underlying PUT endpoint. It does not state auth/permission requirements or what the response contains, 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?

The destructive replace semantics are front-loaded in a capitalized verb, then consequences, then the API mapping. Dense and mostly waste-free, though the 'Civo: PUT /v2/instances/{id}/tags' clause is informational filler rather than actionable guidance.

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

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

For a 3-param destructive mutation with no output schema, the description covers replacement semantics, clearing behavior, and downstream side effects on pools. Missing only peripheral details like permissions required or the exact response shape, which are not essential to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantic value the schema cannot: the tags array is the complete desired state, not a delta, and an empty array is a valid clearing operation. That meaningfully disambiguates the most error-prone parameter.

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

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

States a specific verb and resource ('REPLACE the full tag list of one instance') and makes the replace-vs-append semantics unmistakable. No sibling tool touches instance tags, so the operation 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?

Explicitly tells the agent to pass the complete desired list and that an empty list clears all tags, which is the key usage decision. It does not name a sibling alternative (none exists), but the when-to-use condition 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 destructiveHint=true, and the description adds useful context that the target must be a stopped instance and that this is the inverse of stop. It does not disclose idempotency (behavior on an already-running instance), permission requirements, or what the call returns. With annotations carrying the safety profile, this is an adequate-but-not-rich 3.

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

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

Three short sentences with the core action front-loaded, followed by the inverse relationship and the underlying API endpoint for traceability. No filler or repetition.

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

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

For a two-parameter mutation tool with no output schema, the description covers purpose, inverse operation, and endpoint; annotations cover the safety hint and schema covers all parameters. Minor gaps remain around permissions and behavior on an already-running instance.

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 instance_id and region are fully documented in the schema, including the region-default rule and the pointer to civo_list_regions. The description adds nothing 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 (boot/start) and resource (a stopped instance), and explicitly names the sibling operation it reverses (civo_stop_instance). An agent can distinguish this from civo_stop_instance, civo_reboot_instance, and civo_get_instance 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?

"Undoes civo_stop_instance" gives a clear condition for use and points at the sibling alternative implicitly. It does not state when not to use it (e.g. an instance already running, or a reboot being more appropriate), so it falls short of full when/when-not guidance.

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

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

The destructiveHint annotation signals a disruptive mutation, and the description adds genuinely non-redundant context: served workloads go offline, the action is reversible only via civo_start_instance, and the instance continues to incur billing. Idempotency and any confirmation/async behavior are not covered, 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 short sentences, each earning its place: action, consequence/recovery, and cost note, with the core operation front-loaded. 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-resource mutation with no output schema, the description covers the operation, its blast radius, recovery path, and billing implication, which is enough to call it correctly. It omits region scoping behavior despite region being a parameter, 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 coverage is 100%, with instance_id and region both documented in the schema including the CIVO_REGION default fallback. The description adds no parameter-level detail 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 ('Power off one instance') and immediately contrasts the lifecycle operation with civo_start_instance, so an agent can distinguish it from civo_reboot_instance and civo_get_instance 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 gives clear context for when this applies (you want the instance offline) and names the restoring alternative, civo_start_instance. It stops short of explicit when-not guidance (e.g., preferring reboot for a restart), which would be needed for a 5.

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