civo

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

Annotations only supply destructiveHint=true; the description adds real value beyond that by disclosing that changes are live and propagate globally, and by naming the only rollback path (dashboard/CLI deletion). It does not mention required permissions or duplicate/collision behavior, 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 action, then the propagation/rollback caveat, then the API route. The endpoint line ('POST /v2/dns/{domain_id}/records') is mildly redundant with the tool's purpose but confirms the method.

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

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

For a mutation tool with no output schema, the description covers irreversibility and propagation, which is what an agent most needs. It leaves out failure modes (duplicate records, permission errors) and confirmation of what is returned, but nothing critical to invoking 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 every parameter including enums, TTL bounds, and the apex '@' convention is already documented in the schema. The description adds no parameter-level detail, 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 and resource ('Add one record to a Civo-hosted domain') with the scope limited to a single record, which cleanly separates it from civo_list_dns_records in the sibling set. An agent can identify the operation without opening the schema.

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

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

Usage is implied rather than stated: you call it when you need to create a DNS entry for a hosted domain. The line about undoing via the dashboard/CLI usefully signals there is no paired delete tool, but there is no explicit when-to-use or when-not-to-use 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?

With only destructiveHint=true available, the description adds real behavioral context the annotation cannot convey: the blast radius (affects every instance, cluster, and load balancer on the firewall) and reversibility (no API undo — must be deleted via dashboard or CLI). That is exactly the 'what gets destroyed / how to undo' information an agent needs before mutating.

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

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

Four short sentences, front-loaded with purpose, then impact, then undo path, then the API mapping. Nothing is padded and the most important warning (blast radius) appears early.

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

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

For a destructive, no-output-schema mutation tool, the description covers purpose, example, blast radius, and reversal path, while region and enum semantics are fully handled by the schema. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description climbs above it by illustrating the interaction of protocol/port/direction/cidr in one example and reinforcing CIDR semantics ('prefer narrow CIDRs'), which adds practical meaning beyond the 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) and immediately grounds it with a concrete example ('allow TCP 443 ingress from 0.0.0.0/0'). An agent can distinguish this from civo_list_firewall_rules and civo_list_firewalls without consulting 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 clear operational context ('changes what is reachable on every instance, cluster and load balancer', 'prefer narrow CIDRs'), which tells the agent when care is warranted. It does not, however, name an alternative tool or state explicit exclusions, so it stops short of the when-not/alternatives bar.

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

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

readOnlyHint=true already covers the safety profile, but the description adds genuinely new behavior: 'Passwords are redacted', which tells the agent the response is partially masked and no secrets will be returned. That is real context beyond the annotations, though it says nothing about error/not-found behavior or any rate limits.

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

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

One dense sentence front-loads the resource and its returned fields, followed by the redaction caveat and the API mapping. Every clause carries information and nothing is padded.

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

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

With no output schema, the field enumeration (status, size, CPU/RAM/disk, IPs, network, firewall, tags, volumes, image) usefully stands in for a return-value description, and the redaction note closes the main gap. Only the region-resolution behavior and failure modes are left to the schema, which is acceptable for a read-only getter.

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 both instance_id and region are fully documented in the schema, including the pattern and the CIVO_REGION default. The description adds no syntax or constraint detail beyond the '{id}' placeholder, 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 single-resource scope ('Fetch one instance') and enumerates the payload fields returned, which cleanly separates it from the sibling civo_list_instances. It also pins the underlying operation as 'Civo: GET /v2/instances/{id}', leaving no ambiguity about what is being fetched.

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 singular scope and the {id} endpoint make it obvious this is the by-id lookup rather than the list call. There is no explicit 'use this when you already have an id, otherwise use civo_list_instances' routing, nor any mention of prerequisites such as needing the correct region.

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

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

Annotations already establish readOnlyHint=true, and the description adds real behavioral context beyond that: the kubeconfig is redacted, and the underlying API call (GET /v2/kubernetes/clusters/{id}) is disclosed. It does not mention auth/permission requirements or error behavior, so it stops 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 resource, then lists returned fields and the security-relevant redaction note before the API endpoint. It is longer than most definitions but every clause describes a distinct output facet, which is justified in the absence of an 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 compensates by enumerating what is returned and flagging the redacted kubeconfig. Combined with full schema param coverage and read-only annotations, it is essentially complete; only pagination/error and auth details are absent, which are minor here.

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

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

Schema description coverage is 100%, so both cluster_id and region are already fully documented in the schema (including the region default and examples). The description adds no parameter-level syntax or format detail, 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?

States a specific verb (Fetch) and resource (one Kubernetes cluster), then enumerates the returned facets (status, readiness, conditions, version, pools, network, firewall, CNI, marketplace apps). An agent can distinguish this from civo_list_kubernetes_clusters without opening either schema.

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

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

The singular 'one cluster' plus a required cluster_id implies the use case (retrieve details for a known cluster id), but no explicit when-to-use/when-not guidance and no sibling alternative is named. The region parameter's dependency on CIVO_REGION is only 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 only declare readOnlyHint=true; the description adds that this returns account-wide limits *and* current usage (no filtering or scoping options), and cites the backing endpoint GET /v2/quota. It does not discuss return structure or any rate/permission constraints, but it goes meaningfully 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 sentences plus the endpoint reference, front-loaded with the resource enumeration and ending with the purpose question. Every clause carries information; nothing is padding.

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

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

With no output schema, the description usefully enumerates the categories returned (instances, CPU, RAM, disk, volumes, snapshots, IPs, networks, firewalls, load balancers, object storage, databases) so an agent knows what it gets back. It does not describe the shape of the response or how usage is expressed relative to limits, 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?

There are zero parameters, so the baseline is 4; the description correctly implies a no-argument, account-scoped call and adds nothing misleading about inputs. Nothing further could be said about parameters here.

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

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

States a specific verb+resource ('The account's limits and current usage') and enumerates the exact resources counted, which cleanly differentiates it from every sibling, all of which are per-resource list/get/create tools. An agent can tell this is the aggregate account-quota call 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 phrase "Answers 'can I launch another one?'" gives a concrete decision context for invoking it, which is real usage guidance. It stops short of naming when not to use it or pointing to alternatives, but the account-level scope 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 already declare readOnlyHint=true, so the safety profile is covered. The description adds real behavioral detail beyond that: the 31-day maximum range and the default window (start of current month through now), which an agent needs to size requests correctly.

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

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

Two sentences, front-loaded with the resource and scope, then constraints; the trailing API endpoint reference is compact and unambiguous. 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 parameterless-required read-only list with no output schema, the description helpfully enumerates the shape of each returned charge entry and the default time window, which is exactly the information an agent would otherwise miss given the absent 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 description coverage is 100% and both parameters carry their own descriptions including format, defaults, and the 31-day rule, so the schema does the heavy lifting. The description restates the same range/default information, adding no syntax or semantic detail beyond the schema.

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

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

States a specific verb and resource ('List billable usage for a period') and enumerates the returned fields (product code, label, region, time span, hours, size_gb for volumes). It is unmistakably distinct from sibling list tools such as civo_list_instances or civo_get_quota, though it does not explicitly name an alternative.

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 name and the returned-field list, and the 31-day range constraint gives practical context, but there is no explicit when-to-use/when-not guidance or pointer to alternatives like civo_get_quota.

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 adds real behavioral value beyond that: the redaction of passwords, the pagination envelope, and the underlying Civo endpoint. It stops short of stating rate limits or whether pagination is 1-indexed, so it is 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?

Two tightly packed sentences plus an endpoint reference; the resource and scope are front-loaded and every clause carries information. It is dense rather than wasteful, though the API endpoint citation is arguably redundant 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?

There is no output schema, so the description correctly takes on the burden of describing return contents (software/version, size, nodes, IPs, port, network, firewall, status) and the pagination envelope. It is essentially complete for a read-only list call.

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

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

Schema description coverage is 100%, so region, page and per_page are already fully documented in the schema (including the CIVO_REGION default and limits). The description adds the pagination response shape but little new parameter meaning, so the 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 and resource (list managed databases), names the engines (MySQL, PostgreSQL), and scopes it to a region. It also enumerates the returned attributes, so an agent can identify it against every sibling list tool (instances, volumes, firewalls) 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 regional scoping is stated ('in a region') and pagination is implied, so the agent knows the context, but there is no explicit when-to-use/when-not guidance or named alternative. Since no sibling tool lists databases, routing risk is low and 3 is adequate.

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 profile is covered. The description adds the underlying REST endpoint (GET /v2/dns), but says nothing about pagination, result ordering, or account scoping behavior at runtime.

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, purpose front-loaded before the endpoint detail, with no filler. Sized appropriately for a parameterless list tool.

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

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

For a simple no-parameter read tool this is close to sufficient, but with no output schema the description does not hint at the shape of the returned domain list, leaving the agent to discover it at call time.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No argument syntax is needed.

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

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

States a specific verb (List) and resource (DNS domains hosted by Civo for the account), which an agent can distinguish from civo_list_dns_records. It is clear but offers no explicit sibling differentiation beyond the resource noun.

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 or when-not-to-use guidance, and no mention of the obvious alternative civo_list_dns_records (records within a domain). Usage is only inferable from the 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?

readOnlyHint=true already establishes a safe, non-mutating read, so the bar is lower; the description adds the exact read path and the returned record fields, which is genuine extra context. It does not mention pagination, ordering, or empty-result behavior, 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?

Two compact sentences: the scope and return fields come first, the optional filters second, and the endpoint reference last. No filler and nothing repeated from 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 usefully lists the record fields the caller will receive, which covers the main gap. Missing pagination/ordering notes and any indication of large result handling keep it just shy 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?

Schema coverage is 100% and each parameter carries its own description (name examples, type enum, domain_id pattern), so the schema does the heavy lifting. The description only restates the optional type/name filters without adding format or edge-case detail, 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 (List) and resource (DNS records of one hosted domain), enumerates the fields returned, and includes the underlying endpoint GET /v2/dns/{domain_id}/records. This cleanly separates it from civo_list_dns_domains, which lists domains rather than their records.

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' tells the agent how to narrow results, and the required domain_id implies a domain must already exist. There is no explicit when-not guidance or named alternative, but the scoping is clear enough to select correctly.

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 description's burden is lighter. It adds genuine value by disclosing the returned fields and the underlying API surface (GET /v2/firewalls/{id}/rules), which substitutes for the absent output schema. It omits pagination/ordering behavior, 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?

One sentence plus an endpoint reference, with the scoping constraint and the payoff question front-loaded. No filler or repetition of the title.

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

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

For a two-parameter read-only list tool with full schema coverage and no output schema, the description covers purpose, returned fields, and API path adequately. It stops short of 5 only by not mentioning result ordering or pagination, which an agent listing rules may want.

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 fully documented in the schema. The description adds no format, default, or validation detail beyond what the structured field already provides, which is 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 ("List the rules of one firewall") and enumerates the exposed fields (protocol, port range, CIDRs, direction, action, label). The scoping to "one firewall" implicitly separates it from civo_list_firewalls, which lists the firewalls themselves.

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?

Frames the intent sharply with "the answer to 'what is exposed to the internet?'", giving an agent a clear situation in which to reach for it. It does not name exclusion conditions or point at an alternative (e.g. use civo_create_firewall_rule to modify), so it stops short of a 5.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description usefully adds that results are scoped to a region and include per-firewall attachment counts, but it says nothing about pagination, permissions, or result ordering.

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 scope and returned fields front-loaded; the trailing API reference ("Civo: GET /v2/firewalls") is marginal but harmless. No wasted 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 carries the burden of describing return content and does so (network, rule count, instance/cluster/LB usage). Adequate for a simple regional list tool, though pagination behavior remains 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 coverage is 100%, so the region parameter and its CIVO_REGION default are fully documented in the schema. The description only restates regional scoping ("in a region") without adding format or default detail beyond the schema.

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

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

States a specific verb+resource ("List the firewalls in a region") and even enumerates the returned fields (network, rule count, usage counts). This is distinct from the sibling civo_list_firewall_rules, though the description never names that sibling to make the distinction explicit.

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

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

There is no when-to-use guidance, no exclusions, and no routing to alternatives such as civo_list_firewall_rules. Usage is only implicitly inferable from the verb "List".

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 covering the safety profile, the description still adds real operational context: the paginated response shape {page, per_page, pages, items}, that passwords are redacted, and the underlying endpoint. Redaction in particular is a behavior an agent cannot infer from annotations.

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

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

Three short sentences, zero filler, with the verb+resource front-loaded and pagination/redaction details following tightly. 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?

No output schema exists, so the description helpfully supplies the return shape and notes redaction, which covers the main unknown. Minor gaps remain (e.g. sorting, total count), but for a read-only paginated list tool it is essentially complete.

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

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

Schema description coverage is 100%, so page, tags, region, and per_page are fully documented in the schema. The description only gestures at region and tag filtering, adding little syntax or format detail beyond the structured fields, 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 compute instances') plus the scoping dimension ('in a region, optionally filtered by tags'). This clearly separates it from siblings like civo_get_instance (single) and civo_list_instance_sizes.

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

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

Gives clear context: region-scoped listing with optional tag filtering, a pointer to civo_list_regions for region codes, and the CIVO_REGION default. It stops short of naming when to prefer an alternative (e.g. get_instance for a single item), so it lacks explicit exclusions.

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, and the description adds genuine value beyond that by disclosing what a size record contains (CPU cores, RAM, disk, transfer allowance, GPU) — useful since no output schema exists. It stops short of pagination or ordering behavior, keeping it out of the top band.

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

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

One sentence plus the underlying API route; the scope of coverage and returned fields are front-loaded with 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?

For a zero-required-param read-only list tool with fully documented schema and no output schema, the description covers purpose, scope and return attributes adequately. Pagination/response-shape details are the only meaningful omission.

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

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

Schema coverage is 100% and the single region parameter is already richly documented in the schema (format, examples, CIVO_REGION fallback, regionality). 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) plus resource (sizes/plans) and immediately scopes what it covers — instances, Kubernetes nodes and databases — and enumerates the returned attributes. No sibling tool does this, so an agent can place it unambiguously 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?

Usage is only implied: a read-only list of launchable plans is naturally consulted before provisioning, but the description never says when to call it or that it precedes instance/database/cluster creation. No alternatives are named, so an agent must infer placement from context 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?

Annotations already declare readOnlyHint=true, so safety is covered. The description adds non-obvious behavior: the pagination envelope shape, that kubeconfigs are redacted, and the underlying Civo endpoint — all useful context beyond the annotations.

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

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

Front-loaded with the resource and scope, followed by pagination shape, a redaction note, and the raw endpoint. Slightly dense but each clause carries information and there is 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 takes on the burden of describing return values and does so, listing key fields plus the pagination envelope and the kubeconfig redaction. Nothing critical is missing for a read-only list call.

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

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

Schema description coverage is 100%, so page, per_page and region semantics (including the CIVO_REGION default and region code examples) are already fully documented in the schema. The description adds nothing parameter-specific beyond that baseline.

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

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

States a specific verb (List) and resource (Kubernetes K3s/Talos clusters) scoped to a region, and enumerates the returned fields (status, version, node pools, API endpoint, installed applications). It is clearly distinguishable from the singular sibling civo_get_kubernetes_cluster.

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 region parameter text points to civo_list_regions and notes resources are regional, which implies when to pass a region. However there is no explicit statement of when to prefer this over civo_get_kubernetes_cluster or other list tools.

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 goes further by disclosing the response shape (algorithm, backends, public IP, state, fronted Kubernetes service) and the underlying endpoint, which the annotations do not cover. It omits pagination or empty-result behavior, 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?

One tight sentence that front-loads the action and scope before listing returned fields, with zero 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 enumerated return fields do the work of describing what comes back, and the annotation covers the safety profile, so an agent has enough to call it correctly. Minor gaps remain around pagination and how results are ordered when many load balancers exist.

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

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

Schema coverage is 100% and the single 'region' parameter is fully documented in the schema, including the default and the note that Civo resources are regional. The description's 'in a region' adds no syntax or format detail beyond that, 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 load balancers') plus the scope ('in a region'), and even enumerates the returned fields. It is unambiguous, though it never names or contrasts a sibling because no sibling tool occupies this domain.

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 by 'List the load balancers in a region'; there is no explicit when-to-use, when-not-to-use, or alternative tool named. For a single-purpose list operation with no competing sibling this is minimally adequate, but it adds no 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 tells the agent this is a safe read, so the bar is lower. The description adds genuinely useful context: results are region-scoped and it names the returned fields. It says nothing about pagination, result limits, or auth requirements, so it is adequate rather than 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 action, scope, and return payload, followed by a compact API-endpoint reference. Nothing is wasted and nothing important is buried.

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

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

For a one-optional-param read tool with annotations covering safety, the description is nearly complete — the field enumeration usefully compensates for the absent output schema. The remaining gap is pagination/result-limit behavior, which is not mentioned anywhere.

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 optional parameter with 100% schema coverage, so the schema already carries the semantics (pattern, default CIVO_REGION, cross-reference to civo_list_regions). 'In a region' restates the scoping but adds no syntax or behavior beyond the schema; baseline 3 applies.

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

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

Specific verb ('List') plus resource ('private networks') plus scope ('in a region'), and it even enumerates the returned fields. The 'private networks' resource is clearly distinct from the other list_* siblings (instances, volumes, firewalls, clusters), so an agent can route to it without opening the schema.

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

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

Usage is only implied by the read-only listing nature of the tool; there is no statement of when to choose this over alternatives or any prerequisite. It does implicitly point at civo_list_regions via the schema's region description, but the description itself offers no 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 readOnlyHint annotation already establishes this as a safe read, so the description's added value is the disclosure of what the payload reveals (default region, out-of-capacity state, feature matrix) plus a cost/latency characterization. It doesn't mention pagination or rate limits, but for a zero-arg listing endpoint that is a small gap.

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

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

Three short sentences, front-loaded with the core action and return contents, then the practical use case, then the underlying endpoint. Every sentence carries distinct information with no filler.

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

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

With no output schema, the description usefully enumerates the fields a caller should expect back, and the endpoint reference pins the API contract. It stops short of describing response shape or ordering, but for a simple list endpoint 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No misleading parameter hints are present.

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 (Civo regions) with scope (available to the account), then enumerates the exact attributes returned: default flag, capacity status, and supported features. An agent can immediately distinguish this from sibling tools like civo_list_instances or civo_get_quota 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?

"A cheap way to confirm the API key works" gives a concrete secondary use case that an agent can act on for connectivity/auth checks. There are no near-equivalent siblings to route away from, so the lack of explicit when-not-to-use guidance is minor, but it does not name alternatives or exclusions.

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 the safe-read profile, and the description adds real value on top: it discloses the returned attributes and the billing nuance that unattached volumes still incur charges. It omits pagination and rate-limit behavior, keeping it short of a 5.

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

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

A single front-loaded sentence covering scope and output, plus a compact endpoint reference. Every clause carries information; nothing is filler or repeated.

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

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

With no output schema, the description usefully enumerates the fields returned and notes the attachment target, which is exactly what an agent needs to interpret results. Only pagination/return-order behavior is left unstated.

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

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

Schema description coverage is 100%: the region parameter already carries the pattern, examples, the CIVO_REGION default, and a pointer to civo_list_regions. The description's 'in a region' only reinforces what the schema states, 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 names a specific verb and resource ('List the block-storage volumes'), scopes it ('in a region'), and enumerates the returned fields (size, status, type, attachment target). No sibling tool lists volumes, so an agent can immediately place this as the only volume-inventory read.

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: it operates within a region and the schema references civo_list_regions for valid codes. There is no explicit statement of when to reach for this versus, say, civo_list_instances or civo_list_charges, and no exclusions.

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, so the description adds real value: it discloses the brief downtime, explains that hard mode is equivalent to pulling the plug and should be a last resort, and names the underlying API endpoints. It stops short of covering async behavior, idempotency, or auth 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 tight sentences; the destructive/last-resort caveat is front-loaded right after the default mode. The endpoint mapping is the only mildly extraneous detail and it is still relevant to the API context.

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

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

With no output schema, a 3-parameter tool, and full schema coverage, the description covers what an agent needs to act safely, including the downtime and mode tradeoff. It omits whether the reboot is asynchronous and whether the instance returns in the same state, which would fully close the loop.

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 meaningfully enriches the enum beyond the schema's bare "soft (default) or hard" by explaining what each mode actually does to the machine. The region parameter is left entirely to the schema.

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

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

States a precise verb and resource with scope ("Reboot one instance"), and the soft/hard explanation makes the operation's nature unambiguous. An agent can distinguish this from the sibling start/stop tools without opening any schema.

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

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

Gives conditional guidance for the mode ("soft (default)... hard... use only when soft does not work") and warns of downtime, but never says when to reboot versus stopping and starting, nor when to prefer a sibling tool. Usage is implied rather than routed.

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 earns credit by explaining precisely what is destroyed (the entire existing tag list, not appended to) and the downstream consequence that tag changes can move an instance in or out of load-balancer pools. It stops short of permissions or error/conflict behavior.

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

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

Three tight sentences, front-loaded with the capitalized REPLACE that signals overwrite semantics immediately, followed by the side effect and then invocation detail. 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?

A mutation tool with no output schema needs the replacement contract, side effects, and endpoint documented — all present. It could still note whether the call is idempotent or what happens on unknown instance ids, but the core is complete.

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

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

Schema coverage is 100% so baseline is 3, but the description adds semantics the schema does not: that `tags` is a full replacement list and that an empty list is a valid clearing operation rather than a no-op or error.

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) with explicit scope, plus the underlying API operation (PUT /v2/instances/{id}/tags). No sibling tool touches instance tags, so it 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?

Explains how to invoke correctly (pass the complete desired list; empty list clears) but gives no when-to-use guidance relative to alternatives, e.g. reading current tags via civo_get_instance before overwriting. Usage context is implied 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 destructiveHint=true, so the agent knows this is a state-changing operation. The description usefully adds that it reverses civo_stop_instance, but says nothing about permissions, whether start is idempotent, or what happens if the instance is already running.

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, the inverse relationship next, and the API endpoint last; nothing is wasted.

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

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

For a simple two-parameter, no-output-schema tool with annotations covering safety, the description is essentially complete. It could mention region scoping or auth requirements, but the schema already covers the region default and the annotations cover the mutation risk.

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

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

Schema description coverage is 100%, so instance_id and region (including the CIVO_REGION default) are fully documented in the schema. The description adds no parameter-level detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb ('Boot') and resource ('a stopped instance'), and explicitly names the inverse operation civo_stop_instance, which distinguishes it from sibling mutators like civo_reboot_instance.

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 'Undoes civo_stop_instance' phrasing gives a clear context for when to invoke it (recovering a stopped instance), but there is no explicit when-not guidance or mention of prerequisites such as the instance already being stopped.

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

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

Annotations give destructiveHint=true; the description adds genuinely non-obvious behavior beyond that: dependent services go offline and the instance keeps being billed while stopped, plus the underlying PUT endpoint. Auth/permission requirements and reversibility nuance 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, front-loaded with the action, then consequence, then API mapping. Every sentence earns its place with no filler.

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

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

For a two-parameter mutation with no output schema and only a destructiveHint annotation, the description supplies the missing behavioral context (downtime, continued billing). It is complete enough to call correctly; only permission or confirmation requirements 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?

Schema coverage is 100%, so both parameters (instance_id and region) are already fully documented in the schema, including the region default and the civo_list_regions pointer. The description adds nothing about parameters, so 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 and resource ('Power off one instance') and explicitly names the counterpart operation civo_start_instance, letting an agent distinguish it from sibling tools like civo_reboot_instance and civo_start_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?

Clearly frames the operational context: anything the instance serves goes offline and it must be started again. The inverse tool is named, which implicitly routes the agent. It stops short of explicitly contrasting with civo_reboot_instance (which also takes an instance down), so not a full 5.

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