FFxF

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

Annotations already declare non-read-only, non-destructive, open-world behavior; the description adds the required scope 'sshkeys.write', which is genuinely useful auth context an agent cannot get from the annotations. It does not mention idempotency or duplicate-key behavior, keeping it short of a 5.

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

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

Two tight sentences, zero waste, with the action and its purpose front-loaded before the scope constraint.

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?

Annotations cover the safety profile and the description supplies the scope requirement; with only two parameters and no output schema, little else is needed. The undocumented 'name' parameter is the one 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?

Schema coverage is 50%: public_key is fully documented with a format example, while name is undocumented in both schema and description. The description adds no parameter-level detail, so the baseline 3 applies at this coverage level.

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

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

Names a specific verb (saves) and resource (public key) plus the concrete benefit (passwordless access for new machines). It clearly reads differently from list_ssh_keys or delete_ssh_key, though it never explicitly contrasts with those siblings.

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 'so new machines can be reached without a password' clause implies the context of use, but there is no explicit when-not guidance and no mention of the alternative sibling tools (list_ssh_keys, delete_ssh_key).

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

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

Goes well beyond the annotations: enforcement latency (~10 seconds), a hard cap of 5 firewalls per machine, additive rule semantics, the public-address prerequisite, and the required scope network.write. The 'Attaching again is harmless' note reinforces idempotentHint with plain-language confirmation rather than contradicting it.

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 the behavioral consequence before the limits and failure condition. Minor friction from the elliptical phrasing 'no rule of its firewalls opens', which takes a moment to parse, but 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?

For a two-parameter mutation with no output schema, the description covers the resulting state, propagation delay, quota, prerequisites, idempotency, and permission scope. The only real gap is the absence of any routing to the detach/update siblings for the inverse or modification 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% (vm and firewall are both documented with provenance from list_vms/create_vm and list_firewalls/create_firewall), so the schema carries parameter meaning. The description adds nothing about the two parameters, so the baseline 3 applies.

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

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

The description defines the tool by its effect ('the machine refuses inbound traffic no rule of its firewalls opens') and the idempotency note implies an attach action, which the title 'Attach a firewall to a machine' confirms. It is distinguishable from detach_firewall and set_rules by its additive, per-machine scope, but the core verb is never stated outright in the description text itself.

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

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

Usage is implied by the effect statement and the prerequisite 'Refused for a machine with no public address', which tells the agent when a call will fail. However, no sibling is named and there is no explicit guidance contrasting this with detach_firewall, set_rules, or update_firewall.

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

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

Adds useful context beyond annotations: it is differential, starts within a minute, is unavailable on linked forks, and requires backups.write scope. It does not explain what the call returns or how to monitor completion, but annotations already cover the mutation and non-destructive 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?

Very compact and front-loaded: purpose, timing, restriction, and required scope are all stated without 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 simple one-parameter operation, the description covers purpose, timing, restriction, and auth scope. It does not say what 'starts' returns or whether the caller should poll for completion, but the core invocation context is present.

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 schema has 100% description coverage and fully documents the single database parameter. The description adds no parameter-specific meaning beyond what the schema already provides, so the baseline score 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: it starts a differential backup for a database. This is clearly distinct from sibling tools such as list_database_backups and restore_database.

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

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

Gives an explicit use case ('before a risky migration') and an explicit exclusion ('Not available on a linked fork'). No sibling tool competes for starting a backup, so no alternative routing is needed.

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

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

Goes beyond the annotations by disclosing that the operation is a hot-add with no restart, that repeat connects are safe because the same address returns, that manual configuration requires in-guest address setting, and the required network.write scope. The only gap is nothing about failure behavior when no address is free.

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

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

Front-loads the core behavior in the first sentence and keeps the whole thing to three short sentences. The 'configuration: manual' fragment is cryptic and refers to nothing in the schema, costing a point.

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 annotations covering safety and idempotency, the description does the main work: hot-add semantics, scope, and repeat-connect behavior. It leaves open what happens on address exhaustion and never resolves the unexplained 'configuration' concept, so it is adequate but not 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 all three parameters are documented there, including the 'next free one' default. The description adds only a vague notion of 'sets its address' and a dangling 'configuration: manual' reference that matches no parameter in the schema.

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

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

'Hot-adds a card on the private network and sets its address' is a specific verb+resource statement that clearly separates this from disconnect_vpc or attach_firewall. It doesn't name a sibling explicitly, so it stops short of a 5.

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 'configuration: manual' note and 'Connecting again returns the same address' give some usage context, but the description never says when to use this versus disconnect_vpc or when to prefer specifying an ip versus letting the default free address be picked. Usage is implied rather than directed.

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

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

Adds a great deal beyond the annotations: hourly billing from now, 24 hours of credit required, monthly/yearly drawn from credit or parked in billing.pending_invoice, provisioning timeline with status pending → active, and the fixed admin user ffxfadmin with logical database defaultdb. The retry-safety sentence duplicates idempotentHint but the surrounding credit and invoice semantics are exactly the kind of consequence disclosure a mutation tool needs.

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 ordering verb and the resource lead the sentence, and each clause carries operational facts (pricing, billing, provisioning, credentials). It is dense to the point of being a single run-on paragraph, which slightly hurts scanability, but 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?

For a create tool with no output schema it covers pricing, billing mechanics, credit prerequisites, provisioning timeline and the resulting credentials, which is nearly everything an agent needs. It never says what identifier the call returns, so the agent must infer the follow-up to get_database to poll status.

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 86%, so the schema already documents vpc, engine, billing, size_gb and version in detail. The description reinforces the billing trade-off (monthly/yearly consuming credit or producing an invoice) but adds little on the remaining parameters such as name constraints or idempotency_key behavior; 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 and resource — ordering a managed database — and enumerates the supported engines (PostgreSQL, MySQL, MariaDB, Valkey) plus the private-network placement. That level of detail makes it distinguishable from create_vm, create_logical_database and create_database_user 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?

Explicitly routes the agent to get_database_options for pricing and tells it to ask the user about the billing period; the 'Scope: vms.create' line signals the authorization surface. It does not name when to prefer e.g. fork_database or restore_database instead of a fresh order, so it stops short of full alternative 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?

Goes well beyond annotations: password is shown exactly once and must be treated as a secret, propagation is 'within seconds', a 30-user limit applies, and it details the exact privileges granted (read/write + table creation, public schema on PostgreSQL, SELECT-only with read_only, no access anywhere else). Also documents the connection_uri target and the Valkey-specific degradation, none of which annotations convey.

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

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

The critical facts (created user, one-time password) are front-loaded, but the body is a single dense paragraph with stacked parentheticals ('(on PostgreSQL in public too)', '(no databases, no read_only)') that could be split into scannable points. Every sentence carries information, but the structure makes it harder to extract than it needs to be.

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

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

For a mutating, credential-generating, platform-varying operation with no output schema, the description covers creation effects, secret handling, limits, per-engine behavior, and required scope. An agent has everything needed to call it and to warn the caller about the one-time password.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning by explaining the consequence of omitting databases (all logical databases, future ones included) and of read_only (SELECT only, MySQL/MariaDB SELECT+SHOW VIEW), plus where the resulting connection_uri points. Some of this duplicates the schema's own parameter text, keeping it below 5.

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

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

Opens with a specific verb+resource+effect: 'Creates a user with a generated password, returned here once.' This clearly separates it from delete_database_user and get_database_credentials without needing the schema.

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

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

Points to get_database_credentials as the alternative for reading the password later, and states the scope requirement (databases.write) and the 30-user cap. It doesn't explicitly say when to use set_database_user_access instead of the databases/read_only parameters at creation time, so it falls short of a full when/when-not statement.

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

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

Beyond the annotations, it discloses important defaults: omitted rules start with SSH and ping open from anywhere, rules: [] creates no rules, and the firewall has no effect until attached. It also states the required scope, network.write.

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

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

The description is four compact sentences, front-loaded with the core action and followed by the most important defaults and scope. There is no wasted wording.

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

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

For a creation tool with annotations and no output schema, the description covers the critical behavioral details an agent needs before invoking it. It does not describe the return value or idempotency, but those are minor gaps given the available schema and sibling tools.

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

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

The schema lacks top-level parameter descriptions, so the description adds meaningful semantics for the rules parameter, especially the default behavior when omitted and the special meaning of rules: []. The name parameter remains undocumented but is obvious from the schema.

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

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

The description states a specific verb and resource: creates a reusable set of inbound and outbound rules. It also clarifies that the firewall itself does not filter traffic until attached, which distinguishes creation from attachment and use.

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

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

It clearly establishes the creation context and explains that nothing is filtered until the firewall is attached. It does not explicitly name update_firewall or attach_firewall as alternatives, but the use context 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?

The description adds substantial behavior beyond the annotations: billing is hourly by default, monthly/yearly may require credit or an invoice in billing.pending_invoice, the resource stays hourly until payment, readiness follows pending → active, pools/listeners can be added meanwhile, and retrying is safe. These details are consistent with the annotations, including idempotentHint=true, and provide exactly the operational context an agent needs.

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

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

The description is front-loaded with the core action and then layers in billing, readiness, retry, and scope information. It is dense but mostly earns its length for a billing-sensitive creation tool, though some billing details overlap with the schema and could be slightly tighter.

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 complex creation tool with billing implications and no output schema, the description is complete enough to call correctly: it covers prerequisites, billing modes, invoice fallback, readiness timing, idempotency, and authorization scope. The schema supplies the remaining field-level constraints.

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 75%, so the schema already documents vpc, billing, and idempotency_key. The description still adds meaning beyond the schema by explaining billing coverage behavior, pending_invoice handling, actual CAD prices, and the safety of retrying with the same call; only the name parameter remains without added semantic detail.

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

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

The description states a specific verb and resource: 'Orders a load balancer in a private network.' It also adds useful scope with 'Scope: vms.create,' but it does not explicitly distinguish this tool from sibling alternatives such as create_vm or the load-balancer pool/listener 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 description gives clear usage context: it is for ordering a load balancer in a private network, requires sufficient credit for hourly billing, and explains that pools and listeners can be added while the load balancer becomes ready. It does not explicitly name alternatives or when-not-to-use conditions, so it falls short of a 5.

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

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

Adds real context beyond the annotations: a hard quota of 30, engine incompatibility with Valkey, admin ownership, and the required databases.write scope. It doesn't cover what happens when the quota is reached, but the description clearly earns credit with annotations present.

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

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

Front-loads the verb and resource, then layers constraint, exclusion, and scope compactly. The parentheticals are dense but each carries distinct information; only the Valkey SELECT-range detail borders on excess.

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 creation tool with full schema coverage and a safety profile in annotations, the description covers quota, engine support, ownership, and required permission. Only the return value (whether an id/credentials come back) is left 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%, with both 'name' (regex + pattern explanation) and 'database' (id source) fully documented in the schema. The description adds no further parameter detail, 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 ('Creates another database inside the managed database') and clarifies the ownership model. The nesting phrase distinguishes it from the top-level create_database sibling without naming it 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?

Gives a concrete precondition ('up to 30') and an explicit exclusion ('Not on Valkey'), telling the agent when not to call it. It does not name an alternative sibling for the Valkey case, which keeps it short of a 5.

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

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

Annotations already declare write, idempotent, open-world, and non-destructive behavior. The description adds meaningful context beyond that: credit is spent or an invoice is raised, a provisioning action is returned, retries are deduplicated for 24 hours, and the required scope is vms.create.

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

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

The description is short, front-loaded with the core action, and each sentence adds useful information about billing, return value, idempotency, or scope. There is no wasted text.

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

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

For a complex 13-parameter mutation with no output schema, the description covers the important missing context: what it returns, how to poll the provisioning action, billing implications, retry safety, and the permission scope. Remaining parameter details are fully covered by the schema.

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

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

Schema description coverage is 100%, so the parameters are already well documented. The description reinforces billing behavior but does not add syntax or meaning beyond the schema for the 13 parameters, so the baseline score 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 uses a specific verb and resource: it orders a machine, states the billing effect, and says it returns the machine plus a provisioning action. It is clear what the tool does, though it does not explicitly distinguish itself from the sibling estimate_vm tool.

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

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

It provides usage context by saying the retry is deduplicated for 24 hours and that the returned action should be polled with get_action. However, it does not explicitly say when to use create_vm instead of estimate_vm or list the prerequisite discovery tools, leaving alternatives mostly 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 supply the safety profile (write, non-destructive, open-world), and the description adds real value beyond them: 'ready when the call returns' discloses synchronous/blocking behavior, the .1 gateway reservation reveals address allocation, and 'Scope: network.write' states the required permission.

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

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

Two tight sentences, front-loaded with the core action, then behavioral detail and scope. 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 creation tool with no output schema, it conveys sync readiness and permission scope, but doesn't indicate what is returned (e.g., the new VPC id), which matters for follow-up calls like connect_vpc or attach_firewall.

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 already documents cidr and region (67% coverage), and the description adds meaning by explaining the .1 gateway reservation that affects how the cidr is consumed. The 'name' parameter remains undocumented anywhere, keeping it from a 5.

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

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

States a specific verb and resource ('Creates an isolated private network'), which is clearly distinguishable from get_vpc, list_vpcs, and delete_vpc by verb alone. It stops short of naming the sibling it complements, so it lands just under a 5.

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 'Creates' and the scope note, and it helpfully points to list_regions for the region slug. However, it never states when to prefer this over alternatives or any prerequisites (e.g., ensure name is unique), leaving conditions 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 flag destructiveHint=true, so the description's job is added context — and it delivers: billing stops, backups persist for 7 days and are restorable, and deletion is refused if a linked fork depends on the database. These are non-obvious side effects and failure modes that no annotation or schema field conveys.

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 clauses with zero filler, and the highest-stakes information (destructive scope, ask-user-first, confirmation requirement) is front-loaded. Nothing repeats the annotations verbatim and nothing could be cut without losing a distinct fact.

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

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

No output schema exists, yet the description covers consequences, retention window, recovery path, blocking condition, and confirmation semantics for a two-parameter destructive tool. Nothing an agent needs in order to call this safely is missing.

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

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

Schema coverage is 100% and both parameters are already documented in-schema, so baseline is 3. The description restates the confirm_name requirement and the database-id provenance without adding format, syntax, or edge-case detail beyond what the schema already says.

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

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

Opens with a specific verb and resource ('DELETES the database and its data') plus a consequence ('billing stops'), and the trailing scope ('vms.destroy') pins the exact operation. An agent can distinguish this from destroy_vm, delete_logical_database, or detach_database_fork 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 an explicit precondition ('Ask the user first'), an explicit when-not ('Refused while a linked fork depends on it'), and a named recovery alternative ('restore_database can bring it back meanwhile'). The agent knows both when to call it and what to do instead when blocked.

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 idempotentHint=true, so the description's main added value is the ownership-transfer behavior and the protected admin account. It does not mention irreversibility or connection handling, but the annotations cover the basic destructive 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?

Three short sentences, front-loaded with the main effect, then the exception, then the permission scope. No redundant restatement of the tool name 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 low-complexity destructive mutation tool with full schema coverage and destructive annotations, the description covers the critical side effect, the admin exception, and the required scope. It could mention whether active connections are terminated, but nothing essential is missing.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds an important constraint beyond the schema: the username value 'ffxfadmin' (or the default admin on Valkey) cannot be deleted. It does not add detail about the database 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?

The description uses a specific verb and resource ('drops the user') and adds the key side effect ('Hands the user's objects to the admin'). It is clearly distinct from sibling tools like create_database_user and set_database_user_access.

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

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

It states a precondition that the admin account cannot be deleted and names the required scope, which helps avoid a failed call. However, it does not explain when to choose this tool versus alternatives such as set_database_user_access or reset_database_password.

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, idempotentHint, openWorldHint and non-readOnly, so the safety profile is carried. The description adds genuinely new context: the operation is refused for attached firewalls, and it requires the `network.write` scope. It doesn't say whether the deletion is recoverable, though the precondition disclosure is the more valuable half.

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 operation, then the blocking condition, then the permission scope. No sentence restates the title or wastes tokens.

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

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

For a single-parameter destructive delete with full annotation coverage and no output schema, the description supplies everything an agent needs to call it correctly and anticipate the failure mode: precondition, refusal behavior, and required scope.

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

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

Only one parameter and the schema already documents it at 100% coverage, including the cross-reference to `list_firewalls`/`create_firewall`. The description adds no format or lookup detail beyond what the schema supplies, so baseline 3 is appropriate.

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

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

The description states a specific verb (deletes) and resource (firewall) and immediately qualifies scope with a precondition: the firewall must be attached to no machine. That qualifier also cleanly separates it from sibling `detach_firewall`, which the agent might otherwise confuse it with.

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

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

It gives an explicit when-not ('Refused while it protects one') and the corrective action ('detach it first'), which effectively routes the agent to the detach path. It stops short of naming the sibling tool `detach_firewall` by name, so the routing is inferred rather than explicit.

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

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

The annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is largely covered. The description adds valuable behavioral detail beyond annotations by specifying the concrete effect: the port is closed and its rules are removed. It also discloses the required scope 'network.write,' which tells the agent about authorization needs.

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

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

The description is two short sentences with no wasted text. The destructive effect is front-loaded, followed by the authorization scope, making it easy to parse quickly.

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 destructive deletion tool with complete schema coverage and rich annotations, the description provides enough context to call it correctly: it explains exactly what gets removed and the required scope. No output schema exists, so return values need not be explained. A slight gap is the lack of explicit guidance on alternatives or traffic-impact consequences.

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 (lb and listener) are fully documented in the schema, including where their IDs come from. The description adds no parameter-level details, but the schema carries the full burden effectively, so the baseline of 3 is appropriate.

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

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

The description states a specific effect: 'Closes the port and removes its rules.' This distinguishes a listener deletion from a generic delete and clarifies that both the port and associated rules are removed. It does not explicitly name or contrast with sibling tools such as upsert_listener or delete_load_balancer, so sibling differentiation is left to the tool name and title.

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

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

The description gives no guidance on when to use this tool versus alternatives like upsert_listener or delete_load_balancer. The only contextual cue is the scope 'network.write,' which signals a write operation but does not explain when deletion is appropriate or what preconditions an agent should check.

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 and idempotentHint, and the description still adds consequences an agent could not infer: billed resources are released ('billing stops') while 'target machines are not touched'. Those are exactly the side-effect boundaries that matter before an irreversible call.

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

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

One dense sentence that leads with the action, then the side effects, then the safety instruction and scope. Every clause carries distinct information; nothing is repeated from the title or annotations.

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

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

For a single-parameter destructive tool with no output schema, the description covers impact, confirmation, and permission scope. It doesn't say what happens to in-flight traffic or what errors arise if the balancer is still referenced, but nothing essential to calling it is missing.

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

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

Schema coverage is 100%, and the schema's own description of 'lb' already tells the agent where ids come from (list_load_balancers or create_load_balancer). The tool description adds nothing about the parameter, 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 states a specific verb and resource and enumerates what disappears with it: the load balancer, its address, and its configuration. That level of detail separates it cleanly from neighbouring delete_* tools such as delete_vpc or delete_firewall.

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?

'Ask the user first' gives an explicit confirmation precondition, and 'Scope: vms.destroy' names the permission needed to proceed. It doesn't point to any alternative or non-destructive path, but for a pure deletion tool there may be none worth naming.

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?

Even though annotations already mark this as destructive and idempotent, the description adds context the annotations cannot: that all contained data is destroyed, that backups preserve recoverability for 7 days, and that the caller needs the databases.write scope. Those three facts—data loss, recovery window, and authorization—are exactly what an agent needs before doing something irreversible.

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

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

Three short clauses; the destructive effect and data scope lead, followed by the recovery caveat, the confirmation instruction, and the required scope. 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 2-parameter destructive delete with rich annotations and no output schema, the description covers what is destroyed, how long it can be recovered, the auth scope required, and the confirmation step. Nothing needed to call it safely 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%; both `name` (with its pattern) and `database` (with its id reference) are fully documented in the schema, so the baseline is 3. The description adds no extra format, ordering, or validation detail for either 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?

The description uses a specific verb in capitals ("DROPS") and names the exact resource ("logical database", with its contents), so the agent can tell it apart from create_logical_database. It stops short of distinguishing itself from the sibling delete_database, leaving the agent to work out "logical" vs. plain database scope.

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?

"Ask the user first" gives an explicit confirmation requirement before calling, which is real usage guidance for a destructive operation. However, there is no explicit when-not or pointer to a sibling alternative (for example, dropping a whole database instead of a logical one), so it falls short of a 5.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds the crucial blast radius: targets and the routing rules pointing at the pool are removed too. That is real behavioral information not present in the structured fields. It stops short of saying whether deletion fails when the pool is still referenced by a listener, or whether the action is reversible.

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

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

Two short sentences with no filler; the destructive cascade is front-loaded ahead of the permission note. 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 two-parameter destructive call with full schema coverage and no output schema, the definition supplies the cascade effect and the required scope, which is what an agent most needs. Minor gaps remain around failure conditions when the pool is still in use.

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 both parameters (lb, pool) are documented in the schema with provenance hints, so baseline 3 applies. The description contributes nothing about parameter meaning beyond the schema — notably no note that the pool id must come from the same load balancer.

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 (removes) and resource (pool) plus the cascade footprint — its targets and the rules leading to it. That distinguishes it cleanly from upsert_pool, 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?

"Scope: network.write" describes an authorization requirement, not when to use the tool. There is no guidance on prerequisites (e.g., pool must be empty/detached), no mention of alternatives such as upsert_pool or delete_load_balancer, and no stated when-not-to-use.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds genuinely new context: existing deployments retain the key and only future deployments are affected, plus the required sshkeys.write scope. It doesn't state behavior on an unknown key id, which keeps it from a 5.

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

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

Three short sentences, zero filler, with the core action front-loaded and the consequence of deletion stated immediately after.

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

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

For a single-parameter destructive tool with no output schema, the description plus annotations give an agent enough to call it safely and understand the blast radius. Error semantics for a nonexistent key are the only notable gap.

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

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

Schema description coverage is 100% and the 'key' parameter is documented as 'Key id from list_ssh_keys' with an integer-or-string union. The description adds nothing about the parameter, 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 ('Removes a key from the account'), which cleanly separates it from add_ssh_key and list_ssh_keys in the sibling set. It doesn't explicitly name those alternatives, so it stops short of a 5.

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 verb – an agent can infer you call this to revoke a key, but there is no explicit when-to-use, no mention of prerequisites such as confirming the key is not the last admin key, and no named alternative for rotating keys (add_ssh_key).

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 idempotentHint=true, so the safety profile is covered; the description goes beyond them by disclosing the server-side refusal precondition for non-empty networks, the required confirmation step, and the 'network.write' permission scope. These are behavioral facts not recoverable from the annotations.

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

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

Three short sentences with zero padding; the core action leads, followed by the precondition, the safety directive, and the permission scope. Every clause carries actionable content.

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

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

For a one-parameter destructive tool with rich annotations and no output schema, nothing an agent needs to call it safely is missing: precondition, remediation path, user-confirmation requirement, and required scope are all present.

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 'vpc' parameter is fully documented in the schema ('Private network id, as returned by list_vpcs or create_vpc'). The description adds no syntax or format detail beyond the word 'empty', 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 ('Deletes an empty private network') and adds a scoping constraint ('empty') that distinguishes it from create_vpc, connect_vpc, disconnect_vpc, move_vpc, and the read-only get_vpc/list_vpcs siblings. 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?

Gives an explicit when-not condition ('Refused while a machine is still on it'), the remedy ('disconnect or destroy those first'), and an interaction policy ('Ask the user first'). This is exactly the when/when-not/alternative structure an agent needs before calling a destructive tool.

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

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

Annotations already declare destructiveHint=true, but the description adds crucial context beyond them: no undo, no backup kept, and user confirmation should be sought first. That is exactly the behavioral information an agent needs before invoking an irreversible operation.

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

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

Front-loaded with the destructive effect, followed by safety guidance and the confirmation requirement. Every sentence earns its place and there is no waste.

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 operation with complete schema coverage and annotations, the description supplies the remaining essentials: irreversibility, backup loss, user confirmation, and exact-hostname confirmation. Nothing needed to call it safely 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 vm, when, and confirm_hostname are already documented in the schema. The description reinforces the exact-hostname requirement but does not add new meaning beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb and resource ("DESTROYS the machine and its disk") and makes the destructive scope unmistakable. It is clearly distinguishable from sibling VM tools such as power_vm, reinstall_vm, and delete_database.

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 operational guidance: ask the user first, provide the exact hostname, and note the scope. It does not explicitly contrast with alternatives such as power_vm or reinstall_vm, but the when-to-use condition for a destructive operation 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 readOnly=false, idempotent=true, destructive=false, so the safety profile is covered. The description adds real context beyond that: the database is unavailable for roughly 30 seconds and its backups start afterward. It does not say whether detaching is reversible or what happens to the link on the parent side.

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 a scope tag, with the key operational fact (30-second unavailability) front-loaded after the action statement. No filler; the 'Scope: vms.action' note is compact and informative.

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

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

For a one-parameter mutation with no output schema and full annotation coverage, the description supplies the essential operational detail (downtime, backup behavior). Missing only reversibility and the explicit relationship to fork_database.

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

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

There is a single parameter with 100% schema description coverage ('Database id, as returned by list_databases or create_database'), so the schema carries the meaning. The description adds nothing further about the database argument, which is the baseline 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: it gives a linked fork its own copy of the data, which is distinct from the sibling fork_database (which creates a fork). The 'linked fork' phrasing implies the parent relationship without naming fork_database explicitly, so the differentiation is inferable rather than stated.

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

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

Usage is only implied: you run this on an existing linked fork. There is no explicit when-to-use/when-not guidance and no pointer to fork_database as the tool that produces the linked fork this operates on.

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 readOnly=false, destructive=false and idempotent=true, so the description is not carrying the safety profile alone. It still adds real value by disclosing the consequence for inbound traffic when no other firewall remains, and by naming the required auth scope (network.write). It stops short of saying whether the firewall object itself survives or whether attached services are disrupted.

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 operation first and the operational consequence second, plus the auth scope. No filler or redundancy.

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

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

For a simple two-parameter detach with a fully documented schema and annotation coverage, the description supplies the key non-obvious consequence and the permission scope. The remaining gaps — whether the firewall object persists and how it differs from delete_firewall or set_rules — are minor but real for a network-mutating tool.

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

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

Schema coverage is 100%, and both parameters (firewall id, vm id) are documented in-schema with provenance hints (list_firewalls, list_vms). The description adds nothing about the parameters, 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 object: "Removes the firewall's rules from the machine", which is unambiguous about what is being detached. It does not explicitly contrast itself with siblings such as attach_firewall or update_firewall, but the operation is clear enough to act on.

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

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

There is no explicit when-to-use or when-not guidance, and no routing to alternatives like update_firewall, set_rules, or delete_firewall. The scope note ("network.write") signals a permission requirement rather than a usage condition, and the traffic-behaviour sentence describes an outcome rather than when to choose this tool.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the description's added value is the non-obvious failure semantics: without CASCADE a dependent extension survives the call, and the reason surfaces via get_database. It also names the required scope (databases.write), which the annotations do not convey. It does not describe the success return, keeping it below 5.

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

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

Two sentences, zero filler: the destructive no-CASCADE behavior is front-loaded and the permission scope is a compact trailing note.

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

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

For a destructive, three-param tool with no output schema, the description covers the key risk (dependent objects block the drop), where to diagnose it, and the required scope. Only the success-path outcome is left implicit.

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

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

Schema coverage is 67%, so the schema does most of the work, but the description adds no meaning for any of the three params — notably 'extension' has no schema description at all and the description never mentions it or the naming rules for it. 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 and resource ("Drops the extension") with an important qualifier (no CASCADE), which clearly marks the inverse of the enable_extension sibling. It stops short of naming that sibling explicitly, but 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?

The description implies when this tool applies by describing the dependency case and pointing to get_database for diagnostics, but it never states explicit when-to-use/when-not conditions or names enable_extension as the counterpart operation.

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

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

Annotations already declare destructive/openWorld/idempotent, so the bar is lower, yet the description still adds real value: no restart required (no downtime), an explicit refusal condition, and the required scope network.write. It does not state whether the removed card is recoverable or what the response confirms, but the pre-call behavioral picture is strong.

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

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

Three short sentences, each carrying a distinct fact (effect, no-restart, refusal, scope) with the primary effect 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 destructive two-parameter mutation with no output schema, the description covers effect, downtime, failure mode, and permission scope. Missing only the return value and whether a partially configured machine (no VPC attached) errors out.

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 both parameters (`vm`, `vpc`) are documented with cross-references to list_vms/create_vm and list_vpcs/create_vpc. The description adds nothing about them, 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?

"Removes the machine's private address and card, without a restart" names the specific mutation and its two effects, which is well beyond restating the name. It is clearly the inverse of connect_vpc in the sibling list, though the description never names that counterpart 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?

"Refused for the only network of a machine with no public address" gives a concrete precondition that determines whether the call will succeed, which is exactly the kind of guidance an agent needs before invoking it. It stops short of naming a fallback (e.g., attach a public address first, or use connect_vpc to reverse).

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 non-read-only, idempotent, non-destructive, open-world. The description adds genuine value beyond them: the provisioning is "on demand" with a latency expectation ("live within a minute") and it names the required permission scope (databases.write). Reversibility is only implied via the sibling disable_extension.

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 with the platform constraint front-loaded and no filler. Dense, but every clause (source of names, timing, permission scope) carries information an agent would otherwise lack.

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-required-param mutation with no output schema, the description covers precondition, valid value source, timing, and permission scope. Missing only an explicit statement of what is returned or how to undo it, which is minor given annotations and the disable_extension sibling.

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 67%, and the undocumented 'extension' parameter is exactly the one the description compensates for, giving examples that map logical names to extension ids (vector for pgvector). "in one logical database" also reinforces that 'name' is the database name while 'database' is the numeric id, resolving a confusing schema pairing.

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 (enables an extension in one logical database), scopes it to PostgreSQL only, and gives concrete extension examples (vector for pgvector, postgis, pg_trgm). An agent can distinguish it from disable_extension and from generic database mutations 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?

"PostgreSQL only" sets a hard precondition, and pointing at get_database_options as the source of valid extension names tells the agent how to prepare the call. It doesn't explicitly say when not to use it (e.g., the disable_extension counterpart), but the operational context 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?

Goes well beyond the readOnlyHint annotation by disclosing that it is a dry run that executes the same validation set as create_vm, that nothing is created, and that it requires the vms.create scope. It omits edge behavior such as whether a failed check surfaces as would_succeed=false or an error, and whether the returned price is guaranteed at creation time.

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 for behavior plus two short clauses for sequencing and scope; nothing is padded and the key fact (no creation) is front-loaded.

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 four returned values, and the scope note covers the authorization question. It could still say what a false would_succeed looks like or whether the estimate expires, but for an agent deciding to call it, this is close to sufficient.

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

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

Schema description coverage is 100% and each of the 10 parameters is documented with slugs, cross-references to list_* tools, and behavioral notes (billing, ipv4, private_only). The description adds nothing parameter-specific, 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 ('runs every check of create_vm and prices it') and immediately disambiguates from the sibling create_vm by saying it creates nothing. The list of returned values (would_succeed, hourly rate, monthly price, credit required) makes the output contract tangible.

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?

'Call it before create_vm' gives an explicit sequencing rule that an agent can act on. There is no explicit when-not or named alternative for the no-estimate case, but the pairing with create_vm leaves little ambiguity.

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

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

Goes well beyond the annotations (which only say non-read-only, open-world, idempotent, non-destructive): it discloses billing impact, cloned users/passwords, the 7-day link window, that the fork has no backups of its own, that the source cannot be deleted while linked, and the vms.create scope required. Retry safety is stated in prose as well as annotated.

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

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

Front-loaded with the core action and copy semantics, then lifecycle, then retry safety and scope. Every clause carries information, though the single dense run-on sentence could be split for faster scanning.

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 mutating tool with annotations but no output schema, it covers billing, clone contents, lifecycle, deletion constraint, idempotency, and auth scope. The one gap is that it never indicates what is returned (e.g., the new database's ID) for chaining into get_database or detach_database_fork.

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 80%, so the schema already carries parameter meaning (vpc default, size_gb defaults and its dependency on get_database_options, source database). The description adds no parameter-level detail such as naming constraints or idempotency_key usage beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Creates a NEW database') and immediately defines the fork semantics as 'an instant copy of this one', which distinguishes it from create_database, restore_database, and backup_database in the sibling list. The parenthetical use case (test or staging copy) further pins down intent.

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

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

Gives clear context for when to use it ('for a test or staging copy') and names the counterpart tool that ends the relationship (detach_database_fork). It does not explicitly contrast with create_database or restore_database, so the alternative-selection guidance is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds the required billing.read scope, which is valuable context, but says nothing about data freshness, rate limits, or response shape.

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

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

Two terse fragments that are front-loaded with the returned data and end with the required scope. There is no waste, though the fragmentary style is slightly less clear than a complete sentence would be.

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

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

For a zero-parameter, read-only tool with no output schema, the description sufficiently covers what data is returned and the required scope. Exact response structure is not detailed, but the essential information an agent needs to call it correctly is present.

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 has zero parameters, so there is nothing for the description to compensate for. The baseline for zero-parameter tools is a 4, and the description does not need to explain 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?

Names the specific resource (the account) and enumerates the concrete data it exposes: credit balance, burn rate, runway, quota and budget caps. The intent is clear, though it lacks an explicit verb and does not explicitly differentiate itself from sibling get_* 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?

States the required scope 'billing.read', which is a useful precondition, but does not say when to use this tool versus alternatives or when not to use it. Usage is implied rather than guided.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds genuine context beyond them: this is a polling endpoint whose terminal condition is status != running, errors surface a reason, and it requires vms.read scope. Return shape details and polling cadence/limits are not covered, so it is strong but not exhaustive.

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

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

Three short clauses, front-loaded with the core behavior, then the polling contract, then the required scope. No filler sentences and no 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 one-parameter polling tool with no output schema, the description should at least say where the action identifier comes from and roughly what fields (status, error message) come back. It gestures at status and error reason but leaves the input source and response shape underspecified.

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 single parameter 'action' has 0% schema description coverage, so the description carries the full burden, and it only indirectly hints at the domain with '(create, reinstall, power…)'. It never says the parameter is an integer action ID nor where to obtain one (list_vm_actions), leaving the agent to guess at the value's origin.

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 ('follows') and resource ('an asynchronous action'), with concrete examples of action kinds (create, reinstall, power). It does not name the closest sibling list_vm_actions, so the distinction between polling a single action and listing actions is left to inference, keeping it below a 5.

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?

'Poll until status leaves running' gives a concrete usage pattern rather than a generic verb, and 'on error it carries the reason' tells the agent what to expect on failure. It still gives no explicit routing such as 'use list_vm_actions to find the action ID' or when not to call it, 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?

With readOnlyHint=true already declaring safety, the description still adds meaningful behavior: 'No passwords' tells the agent that credentials are excluded (pointing implicitly toward get_database_credentials), and 'users with their databases (null: all) and read_only' explains a semantic quirk of the returned data. The openWorldHint implication of live external reads is not discussed, 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?

It is compressed into essentially one long comma-chained sentence enumerating ten-plus field groups, so information density is high but scannability is poor; the core action ('fetch one database') is buried mid-list rather than front-loaded. Nothing is wasted, but the structure could be far cleaner.

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 carries the return-value burden and does so thoroughly by enumerating status, connection details, users, extensions, backups, maintenance window, and warnings, plus the password exclusion. Error/not-found behavior and Valkey-vs-standard variants are only partially addressed, so it stops short of fully 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 the 'database' parameter is fully documented in the schema ('Database id, as returned by list_databases or create_database'). The description adds nothing beyond signaling that exactly one database is addressed, so the baseline 3 applies.

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

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

The title plus the opening phrase 'One database: status, connection..., backups and restore window, maintenance window, fork link, warning' makes clear this returns the full detail record for a single database, which contrasts naturally with list_databases (plural) and get_database_metrics (time series). The verb itself is only implied ('One database:'), but the enumerated payload makes the resource and scope 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?

Usage is implied rather than stated: an agent infers it should call this when it needs details/status for an already-known database id. No alternative is named (e.g., 'use list_databases to find the id, use get_database_metrics for performance'), and the 'Scope: vms.read' note is a permission hint rather than a usage rule.

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

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

Annotations declare readOnlyHint=true/openWorldHint, and the description is consistent with a pure read. Beyond the annotations it discloses important traits: the response contains plaintext secrets, includes both private-network and public-when-open connection URIs, and requires databases.write–scoped auth. It doesn't note rotation or rate limits, 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?

Front-loaded with what is returned, then the security handling, then scope. Slightly compressed phrasing in the first clause but every sentence carries information; 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 describes the return shape (users, passwords, databases, read_only, connection_uri) and covers the security and scope implications an agent needs. Nothing material for correct invocation is missing.

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

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

Schema description coverage is 100% and the single 'database' param is documented in the schema as an id from list_databases/create_database. The description adds no further parameter meaning, so the baseline 3 applies.

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

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

Specific verb+resource: retrieves per-user credentials (password, databases, read_only) and ready-made connection strings for a given database. It is clearly distinguishable from metadata tools like get_database or credential-mutating tools like reset_database_password. It doesn't explicitly route against those siblings, keeping it at 4.

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?

"Scope: databases.write" states a prerequisite, and the secret-handling instruction (env var or secret store, never code/commits/logs) gives clear context for use. However, it never names alternatives or says when not to call it (e.g. when only metadata via get_database is needed), so no 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?

Annotations cover the read-only profile, but the description adds real behavioral detail beyond them: the bucket granularity per range (1m/10m/1h) and the fact that only buckets with samples are returned, which affects downstream zero-filling assumptions. It also discloses the required scope (vms.read), a permission signal not present in 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?

Dense single sentence, front-loaded with the metric list followed by ranges and scope; every clause carries information. It is a bit semicolon-heavy and reads as a spec line rather than prose, which slightly hurts scannability.

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's enumeration of returned metrics is the main substitute for return-value documentation and does that job. What is missing is anything about result shape/ordering or whether the range parameter defaults when omitted.

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

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

Schema coverage is only 50% – the 'database' param is documented in the schema but 'range' has just an enum with no explanation. The description compensates by explaining what each range value means in terms of bucket resolution and window length, which is exactly the missing semantic layer.

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

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

Names the exact metrics returned (CPU, memory, connections, commits/commands per minute) and the resource (database), with the supported time ranges spelled out. An agent can distinguish this from get_vm_metrics or get_load_balancer_metrics purely from the resource and metric list.

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 nature of the tool (observability of a database); there is no explicit 'use this when...' statement, no mention of when to prefer get_database or get_slow_queries, and no stated prerequisites beyond the permission scope.

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 read-only and open-world behavior, so the bar is lower, and the description adds real context beyond them: the required auth scope ('vms.read') and the expectation that the agent surface prices to the user. It does not describe pagination, caching, or the shape of the returned price data, leaving a small gap for a read-only endpoint.

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

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

Two compact sentences plus a scope tag, front-loading the returned content and then the call-to-action. Every clause — the price granularities, the disk add-on price, the user-facing price display, the scope — carries operational weight 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 parameters and no output schema, the description carries the burden of explaining return content, and it does so by enumerating the categories returned including regional price granularity. It stops short of indicating how the response is organized (e.g., grouped by size or region), which would matter for an agent that must render prices.

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. What parameter-like variability exists (region affecting prices) is at least mentioned in the returned content description.

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 enumerates exactly what the tool returns — engines, versions, extensions, sizes with hourly/monthly/yearly prices per region, and disk pricing — which is far more specific than the name 'get_database_options' alone. It lacks an explicit verb ('list'/'retrieve'), and its boundary against sibling catalog tools like list_plans and list_regions is left implicit.

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

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

It states a concrete trigger ('Call it before create_database') and a follow-through action ('show the price to the user'), which is meaningful guidance for an agent planning a database workflow. It doesn't explicitly say when not to call it or how it differs from list_plans/list_regions, so it stops short of the top mark.

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

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

Annotations already cover the read-only/open-world profile, and the description adds genuinely new context: the response contents (rules, protected machines) and the status enumeration (applied, pending, error), plus the required vms.read scope. It does not mention latency, pagination, or error behavior for a missing id.

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 compact sentence, front-loaded with the resource and immediately followed by the return shape and scope. Zero filler.

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

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

For a one-param read tool with no output schema, the description adequately conveys what is returned and the permission needed. A brief note on what happens when the id does not exist would close the 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?

Schema coverage is 100% and the single 'firewall' parameter already documents that the id comes from list_firewalls or create_firewall. The description adds no syntax or format guidance 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 resource ('One firewall') and describes exactly what comes back: its rules, the machines it protects, and per-item status. The singular 'one' implicitly distinguishes it from list_firewalls and create_firewall, though no sibling is named.

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 singular framing and the 'Scope: vms.read' note. There is no explicit 'use this when you have a firewall id and need details; use list_firewalls to find one' style routing, even though list_firewalls is the obvious alternative.

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

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

Annotations already establish read-only and open-world behavior, and the description adds useful context: the required permission scope and a detailed preview of returned fields such as DNS IPs, pool targets, listener rule order, and certificates. It does not describe error behavior, but that is minor for a read-only get tool.

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

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

The description is two compact sentences with the main purpose front-loaded, followed by a tight enumeration of returned fields and the permission scope. Every phrase contributes useful information without repetition.

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

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

With no output schema, the description takes on the job of explaining return contents and does so thoroughly: status, IPs, pool/target health details, listener rules, and certificates. The permission scope adds operational context, making the definition complete for a one-parameter read tool.

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

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

Schema coverage is 100%, and the schema already documents the single "lb" parameter as the load balancer id returned by list or create operations. The description adds no parameter-specific syntax or constraints beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The phrase "One load balancer in full" clearly identifies retrieval of a single load balancer and enumerates the returned data. It distinguishes itself from list-style siblings through "One," but does not explicitly contrast with get_load_balancer_metrics or list_load_balancers.

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

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

The description implies this is for fetching a single load balancer's full configuration, but it gives no explicit when-to-use guidance versus list_load_balancers or get_load_balancer_metrics. The only usage cue is the permission scope "vms.read."

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

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

Annotations already declare readOnlyHint and openWorldHint, so the bar is lower, yet the description still adds the required scope (vms.read) and the bucket granularity for each range. It does not discuss cost, rate limits, or partial-data behavior, but the auth scope disclosure is meaningful extra context.

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

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

One dense sentence that front-loads the returned metrics and then the time-range semantics, followed by a short scope note. No padding, though the telegraphic style makes the range mapping slightly harder to parse on first read.

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 series and mentions totals. The main remaining gap is the behavior when the optional range parameter is omitted (default window), which an agent must know to get predictable results.

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 50%: the lb parameter is documented in-schema but range is a bare enum. The description compensates by mapping each range to its bucket size (1-minute, 15-minute, 1-hour), which is exactly the information an agent needs to choose a range and interpret the series.

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

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

The description names the resource and enumerates the exact metrics returned (requests by response class, connections, bytes in/out, peak sessions, totals), which is far more specific than the tool name alone. It is distinguishable from get_vm_metrics and get_database_metrics by the metric set, though it never states 'load balancer' explicitly because that is carried by the name/title.

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: this is the companion to get_load_balancer for time-series data. There is no explicit statement of when to call this versus get_load_balancer or the other metrics tools, and no note about what to do when range is omitted.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the required authorization scope ('billing.read'), which is useful behavioral context, but does not discuss data freshness, pagination, rate limits, or external-call behavior beyond the open-world 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?

The description is a single long, comma-heavy sentence listing many returned data categories. The length is partly justified because no output schema exists, but the run-on structure makes it harder to parse than a concise front-loaded summary followed by grouped return-value details.

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

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

With no output schema and no parameters, the description does the necessary work of enumerating the data returned and states the required scope. It is largely complete for a read-only retrieval tool, though it omits differentiation from list_runner_jobs and does not describe response shape or pagination.

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 has zero parameters and schema description coverage is 100%, so the baseline is 4. There are no parameter semantics for the description to clarify beyond what the empty schema already communicates.

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 clearly identifies the resource as GitHub runners and enumerates the specific data returned: runs-on labels, vCPU/memory/price, account concurrency, linked organizations, monthly minutes/cost, actions cache, and Docker cache. It does not, however, distinguish this tool from the sibling list_runner_jobs, which an agent might reasonably confuse with runner-related retrieval.

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

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

The description provides no explicit when-to-use guidance, no exclusions, and no alternatives. It states an authorization scope ('billing.read') but does not explain when an agent should call get_runners versus list_runner_jobs or other runner-related 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?

Annotations already mark it read-only and open-world, and the description adds important behavior: results are capped at 20, query values are normalized ($1/$2 or ?), engine-specific data sources are noted, and vms.read scope is stated. It omits whether PostgreSQL/MySQL results are cumulative since statistics reset and does not fully explain ordering beyond total time.

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

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

The description is efficient and front-loaded with no filler, and every sentence contributes useful information. The first sentence is very dense with parenthetical engine details, which slightly hurts readability but not enough to lower the score further.

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

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

For a one-parameter read-only getter, it covers engine variants, returned fields, the 20-row limit, and auth scope. It could be more complete with time-window or statistics-reset semantics, but it provides enough to invoke the tool 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 single required database parameter has full schema coverage with a clear description in the schema itself. The tool description adds no parameter-level meaning beyond what the schema already provides, making the baseline score 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 exactly what is returned: the 20 queries with the most total time, including engine-specific sources and fields. It is clearly distinguishable from sibling metric tools like get_database_metrics by focusing on query-level top offenders rather than aggregate metrics.

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?

Provides a clear use case with 'A starting point for indexes,' which implies when to call the tool. It does not explicitly say when not to use it or name get_database_metrics as an alternative, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds meaningful behavioral context: traffic values are Internet-only and scoped to the current traffic month with used_gb, limit_gb, and period_ends_at, plus the vms.read permission scope. It does not cover error behavior or whether suspended machines are returned differently.

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

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

The description is compact, front-loaded with the resource and returned fields, and avoids repetition. The parenthetical traffic details are dense but earn their place by clarifying a non-obvious scoping rule.

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 main returned fields and traffic semantics. For a simple single-parameter read tool with read-only annotations, this is largely complete, though it omits not-found behavior and return structure details.

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 vm parameter is already documented as 'Machine id, as returned by list_vms or create_vm.' The description adds no further parameter semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states it retrieves a single machine and enumerates the returned data (status, IPs, specs, traffic, billing, suspension). It does not explicitly contrast with list_vms or get_vm_metrics, but the resource and scope are easy to distinguish.

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 'One machine' implies single-resource retrieval vs. a list operation, and 'Scope: vms.read' gives permission context. However, it never explicitly says when to use this instead of list_vms, get_vm_metrics, or get_vm_network, 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 already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context that the measurements are external to the machine and requires vms.read, but it does not explain timeframe aggregation, defaults, sampling, or response shape.

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

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

Two short sentences, front-loaded with the returned metric categories and followed by the permission scope. There is no wasted wording.

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

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

For a simple two-parameter read-only metrics tool, the description gives enough to understand what is returned and the permission requirement. However, with no output schema it should clarify the timeframe behavior and the shape of returned metrics, which are currently left implicit.

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

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

Schema coverage is only 50%: the `vm` parameter is documented as a machine id, but the `timeframe` enum has no descriptive semantics. The description mentions metric categories but adds nothing about how timeframe affects results or what the default is, so it does not compensate for the schema gap.

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 specifies the metrics returned (CPU, memory, disk, network) and that they are measured from outside the machine, which distinguishes it from guest-level or sibling metrics tools such as get_database_metrics. It does not use an explicit verb, relying partly on the tool name/title, so it is clear but not maximally self-contained.

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

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

It gives the required permission scope ('vms.read') but provides no guidance on when to choose this tool versus get_vm, get_vm_network, or other metrics tools. Usage is only implied by the metric categories.

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 annotations already declare a safe, read-only operation (readOnlyHint=true, openWorldHint=true), so the safety profile is covered. The description adds the required permission scope (vms.read) and specifies exactly what data is returned. It does not describe error behavior for unknown or inaccessible VM ids.

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

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

One short sentence plus a scope clause, both front-loaded with zero filler. The only minor cost is that the fragmentary phrasing reads like a return-type list rather than a complete statement of action.

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

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

No output schema exists, so the description usefully enumerates the return contents (IPv4/IPv6, reverse DNS, private networks) and states the auth scope. For a single-parameter read tool this is nearly sufficient; only error/empty-case 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%, and the single 'vm' parameter is documented as a machine id returned by list_vms or create_vm. The description adds nothing about the parameter, so baseline 3 is appropriate when the schema carries the full burden.

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

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

The description names the specific resource and its contents: IPv4/IPv6 addresses with reverse DNS plus private networks. It distinguishes itself implicitly from the sibling get_vm by focusing on network data. The only weakness is that it is a noun phrase with no verb, so the action must be inferred from the get_ prefix.

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 usage is implied by the content (fetch network details for a known machine), and 'Scope: vms.read' signals the permission context. However, there is no explicit when-to-use statement, no exclusions, and no reference to alternatives such as get_vm or get_firewall.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds genuinely new context: the required scope 'vms.read' and the fact that the response includes member machines and their private addresses (useful since no output schema exists). It does not contradict the annotations.

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

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

Two short fragments with the returned resource front-loaded and the scope constraint last; nothing is wasted, though the telegraphic phrasing borders on under-specification.

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-item getter with no output schema, the description sketches the return payload and names the permission, but omits failure behavior (e.g., unknown vpc id) and any note on whether machine data is truncated. Adequate but with visible gaps.

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 single 'vpc' parameter is fully documented in the schema, including its reference to list_vpcs/create_vpc for obtaining the id. The description adds nothing about the parameter, 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?

Clearly identifies the resource as a single private network plus its attached machines and their private addresses, which implicitly distinguishes it from list_vpcs. The verb is implied by the name rather than stated, but an agent can tell what it retrieves.

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 statement of when to use this versus list_vpcs, get_vm_network, or get_vm. The only guidance-like text is the permission scope 'vms.read', which is an authorization requirement rather than usage direction.

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

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

Annotations already mark the tool as read-only, but the description adds substantial behavior: weekly full and daily differential backups, continuous transaction log archiving, a minute-granular restore window, Valkey-specific hourly snapshots with 24-hour retention, and the vms.read permission scope. It does not describe pagination or response shape, but it is far richer than the annotations alone.

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

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

The description is dense but front-loaded with the backup schedule and restore-window information. Every sentence contributes useful context, though the long parenthetical first sentence reduces immediate scannability.

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

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

For a one-parameter read-only list tool, the description covers backup cadence, retention, restore window, engine-specific behavior, and permission scope. It does not explain the exact return shape, but with no output schema the description provides enough to call the tool 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 single required 'database' parameter is fully documented in the schema. The description does not add syntax or format details beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description clearly implies it lists completed backups and the restore window for a database, and distinguishes itself from restore_database by naming that sibling. It never states the verb 'list' explicitly, but the resource and scope are clear.

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

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

It routes the agent to restore_database when a restore is needed, making the alternative explicit. It does not state when not to use this tool, but the context is clear for a read-only backup listing.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered; the description goes further by stating exactly which fields come back and explicitly that passwords are excluded, preventing a wasted follow-up expectation. The required 'vms.read' scope is a genuinely useful auth precondition not present in the schema.

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

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

A single front-loaded sentence: resource first, then returned fields, then the scope constraint. Every clause carries information — the field list, the password exclusion, and the permission scope all earn their 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 must describe return values and does so field by field, plus the auth scope. Minor omissions remain — no pagination/limit behavior or result ordering — but for a small account-level inventory this is close to sufficient.

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

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

The tool takes zero parameters, which is the baseline-4 case, and schema coverage is 100% regardless. The description correctly signals that no filters (account, region, status) are accepted, matching the empty object schema.

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

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

The description uses a specific verb-resource framing and enumerates exactly what the listing returns (status, private/public addresses, disk, backups, billing, quota), which clearly separates it from get_database or list_database_backups. It never explicitly names those siblings, so an agent must infer the distinction from the field list.

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 enumeration of what is returned — an agent can infer this is the whole-account inventory call — and the 'Scope: vms.read' note tells it which permission is exercised. However, there is no explicit when-to-use vs. get_database/list_database_backups guidance 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 already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds two pieces of value beyond that: the required permission scope ('vms.read') and a clear statement of what the response contains (firewalls, inbound rules, protected machines, quota). It does not discuss volume or truncation behavior, keeping it just 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 sentence with no filler, front-loading the resource and then the returned payload, with the permission scope appended last. Every clause adds 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 parameterless read tool with no output schema, the description supplies what an agent needs: what it returns, at what scope, and what permission it requires. Nothing material is left ambiguous.

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

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

The tool takes zero parameters, which sets the baseline at 4. There are no arguments whose meaning needs explaining, and the description correctly says nothing about parameters beyond the account-level scope.

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

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

Names a specific verb and resource (list the account's firewalls) and goes further by enumerating the contents returned: inbound rules, protected machines, and quota. It does not explicitly contrast with the singular sibling get_firewall, but the 'list' framing and account-wide scope make the distinction reasonably clear.

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 account's firewalls' – an agent can infer this is the bulk-listing call rather than a single-resource fetch. However, there is no explicit when-to-use guidance, no mention of when to prefer get_firewall for a specific firewall, and no prerequisites or exclusions 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 mark this as read-only and open-world, and the description usefully adds that access is public and no key is needed. It also explains the downstream relevance of slug, though it does not describe filtering or pagination 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 short sentences with no wasted text, and the create_vm relationship is front-loaded by the second sentence. It is appropriately sized for a simple list endpoint.

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

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

For a read-only list tool with no output schema, it covers access and the key output field (slug), but it does not explain the result shape or the optional filters. The definition is usable but leaves meaningful gaps.

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 description says nothing about the plan, region, or category parameters. Schema coverage is only 67%, and region has no schema description either, so the description should have compensated but does not.

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

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

The description identifies the resource as OS and application images, and clarifies that image slugs feed create_vm. It does not explicitly say 'list' or differentiate strongly from sibling list_* tools, but the resource is clear.

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

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

It gives a clear use context by saying the slug is what create_vm expects, and notes the catalog is public with no key needed. It stops short of explicit when-not guidance or naming alternatives such as list_plans or list_regions.

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 and openWorldHint already declared, the description adds useful context: it lists exactly what data is included (addresses, pools, targets and health, listeners and rules, certificates, quota) and states the required scope 'vms.read'. It does not mention pagination, ordering, or result-size 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?

The description is a single front-loaded sentence with no filler. Despite enumerating several returned data categories, it remains compact and focused on what the tool provides.

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 provides a solid summary of returned contents and the authorization scope. It is nearly complete, though it could clarify whether results are paginated or returned in full.

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 has zero parameters, so there is no parameter semantics to explain. The baseline score for an unparameterized tool is appropriate, and no schema-detail gap exists.

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 clearly identifies the resource and account scope: 'The account's load balancers' and enumerates the related data returned. It is distinguishable from get_load_balancer by the plural scope, though it does not explicitly name that sibling as 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?

It gives no explicit when-to-use guidance or exclusions. An agent can infer this is the bulk listing tool, but the description does not state when to choose it over get_load_balancer or other load-balancer-related 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?

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely new context: the endpoint is public and requires no authentication, and prices are quoted in CAD in both hourly and monthly form — details an agent would otherwise have to discover empirically.

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 compact sentence, with the payload contents front-loaded and the access precondition second. Nothing is wasted, though the terse style leaves the 'list' verb implicit.

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

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

For a one-parameter read-only catalog tool with no output schema, the description covers return content (plans, resources, prices), units and currency, and auth requirements. Only the region filtering behavior is left to the schema, which is a minor gap.

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

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

Schema coverage is 100% and the single region parameter is fully documented in the schema, so the baseline is 3. The description never mentions the region filter, so it adds nothing beyond the structured field.

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

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

The description names the resource (plans) and specifies what each entry contains — resources and prices in hourly/monthly CAD — which is more informative than a bare 'list plans'. It is clearly distinguishable from the mutation and VM/database siblings, though it never explicitly contrasts with a catalog sibling like list_images or list_regions.

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 'Public, no key needed' clause gives useful context about when this call is safe/possible, but there is no explicit statement of when to use it (e.g. before create_vm or estimate_vm to pick a plan) and no named alternative. Usage is only implied by the catalog nature of the tool.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely new context — that the endpoint is public and requires no API key — which affects whether an agent can call it before authenticating. It stops short of describing the response shape or whether the data is cached/static.

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 fragments with zero waste, and the auth note is useful. The trade-off is that the first fragment is cryptic rather than informative, so brevity costs a little clarity.

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

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

For a zero-param, read-only enumeration tool this is close to sufficient, but with no output schema the agent gets no hint about the return value (region slugs, identifiers, availability). The description covers what and auth but not what comes back.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; the 4 baseline applies. The description does not mislead about inputs.

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

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

"Where machines can run" gestures at the concept of a region but never says explicitly that this returns the list of available regions/locations; the agent must infer it from the tool name. No sibling is named, though no other region-related tool exists, so confusion risk is low.

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 statement of when to use this versus alternatives (e.g., list_plans, list_images for other enumeration needs). The only usage-adjacent signal is "Public, no key needed," which tells the agent it can call it unauthenticated but not why or when.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-structured context: default sort order (most recent first) and the required scope 'billing.read', which the agent would otherwise not know. It stops short of saying how pagination terminates or how large result sets behave.

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 what the tool returns, then lists fields and the scope. Dense but every clause carries information; the status enumeration is the longest part and is defensible given the enum lacks descriptions.

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 field inventory (repository, workflow/job, label, status, times, billed minutes and amount, run link) carries the return-value burden and does so thoroughly. Combined with the order and scope statements, an agent has what it needs to call this correctly.

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

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

Schema coverage is 75%, so the baseline is 3. The description explains the meaning of status values (queued with waiting_reason credit/budget/account, stopped_for_credit, refused) which the bare enum does not, but it never clarifies that `status` and `repository` act as filters — they read as returned fields rather than query parameters, and limit/cursor are untouched.

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 the resource concretely — jobs that ran or waited on FFxF runners — and enumerates what each record contains (repository, workflow/job, label, status, times, billed minutes, run link). It is not a tautology of the title. It does not, however, distinguish itself from the sibling get_runners, so an agent may hesitate between the two.

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: 'most recent first' plus 'Scope: billing.read' suggests an audit/billing review use case and names the required permission. There is no explicit statement of when to prefer this over get_runners, and no exclusions or pagination guidance beyond the schema's cursor field.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is structured data. The description does add non-obvious auth context ("Scope: sshkeys.write or vms.read"), which is the main value-add, but says nothing about return shape, ordering, or pagination for a listing call.

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

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

Two short, front-loaded fragments with no filler – the resource comes first and the purpose follows. The telegraphic, comma-spliced style is slightly under-written, but 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 zero-parameter, no-output-schema listing tool with annotations covering safety and open-world behavior, the description supplies what structured fields cannot: the account-level scope and the required auth scopes. Only the return content/format is left unstated, a minor gap for such a simple read.

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 the description needs to disambiguate; baseline for a no-param tool applies. No misleading parameter implications are introduced.

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?

"SSH keys saved on the account" identifies the resource clearly and, in combination with the name list_ssh_keys, makes the read-only listing intent unambiguous against siblings add_ssh_key and delete_ssh_key. It never states an explicit verb ("List"), so it falls just short of a precise verb+resource statement.

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?

"to pass to create_vm" gives a concrete downstream use case that tells an agent why and when to call this rather than another lookup. It stops short of explicit exclusions or naming alternative retrieval paths, so it is clear context rather than full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds useful context about data provenance ('from the API and the console') and the required scope, but it does not disclose pagination, ordering, or return-shape behavior.

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

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

Two short sentences, front-loaded with the core purpose and followed by scope and provenance. No wasted words.

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 one-parameter read tool this is adequate, and annotations cover safety. Still, there is no output schema and the description does not mention pagination, ordering, or what an action record contains, leaving gaps for an agent planning the 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 coverage is 100% and the only parameter (vm) is already documented in the schema as the machine id. The description reinforces that the scope is one machine but adds no syntax, format, or constraint details 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?

The description states a clear resource and scope: action history for one machine. It does not explicitly differentiate from the sibling get_action, but an agent can infer that this tool lists actions rather than retrieving a single action.

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 'History of actions on one machine' implies the use case, and 'Scope: vms.read' states the required permission. However, it gives no explicit when-to-use guidance or comparison to alternatives such as get_action or list_vms.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the required permission scope (vms.read), which is real value, but says nothing about pagination behavior despite a cursor parameter, nor whether the result is complete or truncated.

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

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

Two short, front-loaded fragments with zero padding. It is efficient, though the sentence-fragment style leaves the verb implicit.

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 five optional filter parameters, no output schema, and 40% schema coverage, the description needed to explain filtering and pagination. It partially compensates for the missing output schema by naming returned fields, but leaves the agent guessing about how to narrow results or page through them.

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 only 40%: cursor and status are documented, while limit, region, and billing are not. The description never mentions filtering at all, and by naming 'status' and 'billing' as returned fields it actively blurs the line with the identically named filter 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?

Names the resource (the account's machines) and what each entry carries (status, addresses, billing), so an agent knows this is an account-wide VM listing. It does not distinguish itself from get_vm or list_vm_actions, which is the only thing keeping it from a 5.

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 statement of when to use this versus get_vm, list_vm_actions, or list_regions, and no guidance on whether filters are expected. The 'Scope: vms.read' line is a permission prerequisite rather than usage guidance.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds genuinely new behavioral context: the required auth scope and the shape of what is returned (range, gateway, connected machines, quota). It stops short of covering pagination, result limits, or ordering, which are the remaining unknowns 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?

A single ~20-word sentence with the resource front-loaded, followed by the returned fields and then the scope. There is no filler and nothing redundant with 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 input parameters and no output schema, the description carries the burden of explaining return values, and it does so reasonably well by naming four returned fields plus the quota. It could be slightly more complete by indicating whether results are paginated or bounded, but the essentials for calling it are present.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing the description could add or omit on this dimension.

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

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

The description names the specific resource (the account's private networks) and enumerates the fields returned (range, gateway, connected machines, quota), so the agent knows exactly what it gets back. It does not explicitly distinguish itself from get_vpc, which returns a single network, leaving that routing distinction to be inferred from the name.

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

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

The only usage-adjacent statement is 'Scope: vms.read', which is an authorization requirement rather than guidance on when to call this instead of get_vpc or list_vms. The listing intent is implied by the name and the plural resource, but no exclusions or alternatives are 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 declare non-read-only, non-destructive, open-world, so the safety profile is mostly covered. The description adds real value beyond them: the join-then-leave ordering that prevents the machine being cut off, address-ending preservation when free, and the required network.write scope.

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, front-loaded with the operational mechanism and followed by the scope constraint. No wasted wording.

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

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

For a 3-integer, fully required schema with no output schema, the description covers the behavioral essentials an agent needs. It could say more about failure modes (e.g., what happens if the machine isn't on 'vpc'), but it is adequate.

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 ('to', 'vm', 'vpc') is documented in the schema, so the baseline of 3 applies. The description adds no field-level detail such as whether 'vpc' is validated against the machine's current network.

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 — it joins the target network then leaves the current one, moving a machine between private networks. This clearly separates it from connect_vpc/disconnect_vpc, though it never names those siblings explicitly.

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

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

Usage is implied by the mechanism and the 'network.write' scope, but the description never states when to prefer this over connect_vpc plus disconnect_vpc, or any prerequisites (e.g., machine must be on the source network given in 'vpc').

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

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

Beyond the annotations, it discloses that shutdown is a clean ACPI operation, stop is a hard power-off, and the call returns an action that must be polled with get_action. This adds meaningful behavioral context for a mutation tool whose annotations already indicate it is not read-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?

The description is a single compact sentence plus a scope note, with the action list and key semantic distinctions front-loaded. Every phrase contributes useful 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 two-parameter VM action tool with no output schema, the description covers the available actions, the important shutdown-vs-stop distinction, the async return behavior, and the required scope. It is complete enough for an agent to call it correctly.

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

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

Schema coverage is only 50%, but the description compensates well for the undocumented 'type' enum by explaining the practical difference between shutdown and stop. The 'vm' parameter is described in schema, and the description adds scope context without repeating it.

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 enumerates the specific operations (start, shutdown, reboot, stop) and clarifies the resource via the scope 'vms.action' and required 'vm' parameter. It distinguishes shutdown from stop semantically, but it does not explicitly differentiate itself from sibling tools such as destroy_vm or reinstall_vm.

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

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

It gives useful operational guidance by distinguishing clean ACPI shutdown from hard power-off stop, and it points to get_action for polling the returned action. It does not explicitly say when to choose this tool over alternatives like destroy_vm, but the action semantics are 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, but the description specifies exactly what is destroyed — disk contents — plus a human-confirmation requirement and the permission scope (vms.action), which are genuinely additive. It does not say whether the machine keeps its id, IP, or SSH keys after redeploy, which is the remaining behavioral gap.

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

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

Four short sentences, with the consequence (ERASES THE DISK) front-loaded in capitals ahead of the procedural rules. No sentence is filler.

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

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

For a destructive, irreversible operation with no output schema, the description covers data loss and confirmation but omits what state survives the reinstall (hostname, IPs, attached keys) and what ssh_keys/password_delivery do. Adequate to call safely, not 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?

At 60% schema coverage, the description largely restates the schema's own wording for confirm_hostname rather than adding meaning. ssh_keys and password_delivery are undocumented in both the schema and the description, so the description does not compensate for the coverage gap.

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?

"ERASES THE DISK and redeploys another image" states a specific verb (reinstall/redeploy) and resource (the machine's disk) with the destructive effect front-loaded. An agent can tell it apart from create_vm and destroy_vm by the redeploy-with-data-loss framing, though no sibling is named 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?

"Ask the user first" is an explicit interaction prerequisite, and the confirm_hostname rule gives a clear precondition for a successful call. It lacks any when-not/alternative guidance (e.g., versus destroy_vm + create_vm), which keeps it below a 5.

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

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

Annotations already cover safety (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=true). The description adds one genuinely useful behavioral fact beyond them: the change is applied inside the guest OS as well as in the console. It omits whether the guest must be running/agent-equipped and whether the change is immediately effective.

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 core effect front-loaded and the scope note trailing. Nothing here is redundant with the name or 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 simple two-parameter mutation with full schema coverage and covering annotations, the definition is close to sufficient. The remaining gap is operational context: power-state/guest-agent requirements and confirmation of what the returned action represents.

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

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

Schema description coverage is 100%; both parameters (vm, hostname) carry their own descriptions including the hostname pattern. The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb+resource (change hostname of a VM) and clarifies the effect happens both inside the guest and in the console, which is more precise than the title. It does not explicitly distinguish itself from nearby siblings such as set_reverse_dns, but the operation itself is unambiguous.

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

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

There is no guidance on when to use this versus alternatives, and no prerequisites such as whether the machine must be running, whether a guest agent/tools must be installed, or what happens on next boot. 'Scope: vms.action' is an API scope annotation, not usage 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 description communicates high-impact behavioral traits (instant password invalidation) that go beyond standard operational status. Coupled with the annotations (`destructiveHint: true`), it paints a complete picture of the tool's risk and immediate impact.

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 two sentences are extremely efficient. The first sentence states the output/action, and the second addresses the critical operational consequence, maximizing informational density.

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?

The description covers all necessary aspects: what it does, its immediate consequence, and how the resulting new password should be handled. Given the high-risk nature (destructiveHint: true), this level of transparency is required and provided.

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%, providing a baseline of 3. The description adds valuable semantic context by confirming the parameters are an ID (`database`) and a user identifier (`username`). No further compensation is strictly necessary 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?

The title and description clearly state the action (resetting a password) and the resource (database). It is distinguishable from sibling tools like `get_database_credentials` because it performs an active change rather than a retrieval.

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 includes a critical, real-world behavioral guideline: the old password stops working within seconds. It explicitly instructs the user on the necessary sequence of operations (update application first or right after), preventing state mismatches.

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