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

With no annotations, the description carries full burden. It discloses that the key is public and specifies allowed formats, but lacks details on side effects (e.g., duplicate name handling, validation failures, or response behavior). Some additional behavioral context would be beneficial.

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 concise, using two sentences plus a distinguishing note. Every sentence provides necessary information without redundancy. It is well-structured and front-loaded with the primary purpose.

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?

Given no output schema, the description could mention what is returned (e.g., key ID or success confirmation). It covers parameter constraints and purpose adequately but lacks details on error conditions or post-invocation state changes.

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 description adds meaningful context: name is a display label with uniqueness per account, publicKey specifies OpenSSH types and maximum length. It reinforces the public nature, adding value 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 clearly states the tool adds an account-wide SSH public key for use when deploying new cloud VMs. It explicitly distinguishes from the sibling tool add_service_ssh_key, providing a specific verb and resource with 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?

The description specifies the required scope (account:write) and notes it's a plain write, not gated. It also warns not to paste private keys and distinguishes from per-service key. However, it doesn't provide explicit when-not-to-use scenarios beyond the sibling distinction.

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?

No annotations exist, so description carries full burden. It discloses the monetary impact, required scope, and the confirm contract. Could add error conditions or success response but sufficient for safe invocation.

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?

Description is front-loaded with purpose and warnings, then parameter details. Every sentence adds value, though slightly verbose; could be tightened without losing 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?

Covers scope, cost, confirmation flow, parameter details, and references sibling tools. Missing final outcome description (e.g., returns pool ID) but no output schema makes it acceptable.

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 covers 100% of params, baseline 3. Description adds naming constraints, autoscaling bounds, machine type resolution, volume size range and default, and source for service_id, enriching beyond 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 clearly states the tool adds a named worker node pool to a managed Kubernetes cluster, distinguishing it from siblings like list_cluster_pools, update_cluster_pool, etc.

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 clear context: requires services:write scope, costs money, confirm flag only after user approval, and references list_services for service_id. Lacks explicit when-not-to-use but effectively guides usage.

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

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

With no annotations, the description carries the full burden. It discloses that the write is 'plain' and not gated, and explains server-side validation (port range ordering, leading to 400 error). It could mention idempotency or duplicate handling, but the provided details are sufficient.

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 concise and front-loaded: it begins with the core purpose, then covers prerequisites, parameter behavior, and validation rules in a logical order. Every sentence adds value without 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?

Given the absence of an output schema and 7 parameters, the description covers key aspects: authentication, parameter sources, required vs optional fields, and server constraints. It omits the return value or status codes, but this is acceptable for a creation tool.

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

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

The description adds meaning beyond the schema: it explains that id comes from list_firewalls/get_firewall, that omitting both portRangeMin/Max matches all ports, that remoteCidr restricts to a CIDR block, and provides an example. This enhances understanding beyond the schema's field names and types.

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 the verb 'Add' and the resource 'inbound/outbound rule to a cloud firewall', specifying the action precisely. It distinguishes from sibling tools like create_firewall and delete_firewall_rule by focusing on rule addition.

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 context: it requires scope services:write, explains how to obtain the id (from list_firewalls/get_firewall), and notes that direction and protocol are required. However, it does not explicitly contrast with alternatives or state when not to use it, slightly reducing clarity.

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 no annotations, the description carries full burden. It discloses auth requirements ('services:write') and notes 'Plain write — not gated,' but omits side effects (e.g., behavior if member already exists) and response format. It provides moderate transparency but lacks depth.

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 4 sentences, front-loading the core purpose. Each sentence adds distinct information (action, scope, nature, parameter details) without redundancy. It is concise and efficiently uses 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 mutation tool with no output schema or annotations, the description covers purpose, auth, and parameter sources but lacks details on success output, error cases, or idempotency. It is adequate for simple operations but not 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%, providing descriptions for all three parameters. The description largely reiterates the schema, adding only minor context (e.g., 'from list_load_balancers'). It adds no new meaning beyond what the schema already conveys, warranting the baseline score.

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 starts with a clear action: 'Add a VM as a member of a load balancer pool.' It uses a specific verb and resource, and the name itself distinguishes from siblings like 'remove_load_balancer_member' and 'list_load_balancer_members', making purpose unmistakable.

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

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

The description states the required scope ('services:write') and parameter constraints (e.g., serverId must be in your project). It does not explicitly list alternatives or when not to use, but the sibling names are self-explanatory. The guidance is clear for correct invocation.

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

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

Discloses required scope (services:write) and notes that proxy writes share scope with VM/k8s mutations with no proxy-specific scope. States it is a 'plain write — not gated.' Also mentions IP validation. Without annotations, this provides adequate behavioral insight.

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?

Description is concise, with five efficient sentences that front-load the purpose and progressively add details. No extraneous 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?

Given no annotations, output schema, or high complexity, the description covers purpose, usage context, behavioral aspects, and parameter tips. It is complete enough but could mention that the whitelist addition is immediate or persistent.

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%, but the description adds practical guidance: ip must be valid IPv4/IPv6 and suggests using get_proxy_auth's yourIp field; id comes from list_proxies. This adds meaning 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 clearly states the action (add an IP address) and resource (proxy service's whitelist) and specifies the auth method context. It easily distinguishes from sibling tools like remove_proxy_whitelisted_ip.

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 clear context: limited to ISP proxy services, suggests using get_proxy_auth's yourIp field, mentions required scope. It does not explicitly list when not to use or alternatives, but the context is sufficient.

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 no annotations provided, the description covers key behavioral traits: plain write, no billing impact, not destructive, and per-server operation. However, it does not discuss idempotency or return behavior, which would be beneficial but is acceptable for this 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?

Three concise, front-loaded sentences each serve a distinct purpose: action+distinction, scope+traits, and parameter source. 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?

Despite no output schema, the description adequately covers the tool's effect and prerequisites. It would benefit from mentioning what happens post-installation (e.g., return status), but it is sufficient for a simple write operation.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema; it only mentions service_id source. No extra detail on optional id or name 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?

The description clearly states it installs an SSH public key directly onto a running service and distinguishes from the sibling tool add_service_ssh_key_to_library, making the specific verb and resource unambiguous.

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

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

It explicitly contrasts with the related sibling tool, mentions the required scope (services:write), and notes that service_id comes from list_services, providing clear when-to-use guidance without 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?

With no annotations, the description carries the full burden. It states 'Plain write — no billing impact, not destructive,' which directly informs the agent about safety and cost. It also mentions the required auth scope. This is valuable transparency beyond 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?

The description is a single paragraph with four well-organized sentences: purpose, distinction, permissions/safety, and parameter hint. Every sentence adds value without redundancy. It is concise and front-loaded with the primary 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?

Given the tool's simplicity (3 parameters, no output schema), the description covers purpose, sibling differentiation, permissions, safety, and parameter source. It does not detail error handling or idempotency, but for a write tool with no output schema, this is reasonably complete.

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

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

The input schema already provides descriptions for all three parameters (100% coverage). The description adds only a minor hint about service_id source. Baseline 3 is appropriate since the schema does the heavy lifting and the description adds marginal value.

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 the tool registers an SSH key into a legacy VPS's key library, which is distinct from direct installation via add_service_ssh_key. It names the specific platform (Virtualizor) and references the library listing tool, making the purpose unambiguous and differentiating it from 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 description explicitly contrasts with add_service_ssh_key and mentions the required scope 'services:write'. While it doesn't list all scenarios for when not to use it, the distinction and scope information provide clear guidance. It also indicates the source of the service_id parameter.

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 no annotations provided, the description carries full burden. It discloses that the operation replaces existing keys, is a 'plain write', and has 'no billing impact, not destructive'. This goes beyond the basic action description and adds important behavioral 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?

The description is three sentences with no fluff. The first sentence delivers the core action, and subsequent sentences add essential usage details and behavioral notes. Every sentence earns its place.

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

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

Despite no output schema, the description covers the tool's purpose, required context (scope, source of IDs), behavior (replacement, non-destructive), and parameter options. For a straightforward write operation with two parameters, this is fully 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%, so baseline is 3. The description for keyIds and service_id closely mirrors the schema descriptions, adding little additional meaning beyond directing to list_service_ssh_key_library and list_services. It does not introduce new semantic value.

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 the action: 'Apply a SET of library SSH keys to a legacy VPS, replacing whichever keys are currently authorized on the server.' It specifies the verb (apply), the resource (library SSH keys), and the effect (replacement), distinguishing it from sibling tools like add_service_ssh_key_to_library or list_service_ssh_key_library.

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 explicit context: requires scope 'services:write', uses service_id from list_services, and explains that omitting keyIds applies an empty set. It also clarifies the operation is a 'plain write' with no billing impact. While it does not explicitly state when not to use or compare to alternatives, the context is clear and sufficient.

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?

No annotations provided, so description carries full burden. It discloses write nature, permission requirement, and a constraint (serverId must be in project). However, it does not mention idempotency, error conditions, or return value, leaving some behavioral gaps.

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 sentences, each adding distinct value: the action, the permission and nature, and parameter sourcing. Front-loaded with the core purpose. 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 write operation with 2 parameters and no output schema, the description covers the essential aspects: action, permission, and parameter sourcing. Could mention error handling or return status, but not strictly necessary for a well-understood operation.

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 parameter descriptions. The description largely repeats schema content, adding no new meaning beyond emphasizing 'must be in your project', which is already in 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?

The description clearly states the action ('Attach a cloud firewall to a cloud VM.'), using a specific verb and resource. It distinguishes from siblings like 'detach_firewall' and 'create_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?

Provides clear context: requires scope services:write, notes it's not gated, specifies parameter sources (list_firewalls for id, project ownership for serverId). Does not explicitly list alternatives or exclusions, but the sibling tool set implies the opposite 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?

With no annotations, the description carries the full burden. It discloses side effects: detaching from current VPC while leaving public eth0 untouched. It also states the permission requirement and writes nature. No contradictions. Minor missing details like synchronous/asynchronous behavior, but good for a simple mutation.

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 concise sentences. First sentence states the action and side effect. Second sentence covers permission and parameter guidance. No fluff or redundant 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?

Given the tool's simplicity (2 required params, no output schema), the description adequately covers purpose, permissions, parameter sources, and side effects. It could mention return value or async behavior, but omission is acceptable for a straightforward write operation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by specifying the source for each parameter: 'id is the target VPC from list_networks' and 'serverId is the Nova server id to move.' This goes beyond the schema descriptions and helps the agent understand where to obtain values.

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 the action: 'Move a cloud VM into a private network (VPC), detaching it from its current VPC.' It specifies the resource (cloud VM) and the context (private network/VPC). This distinguishes it from sibling tools like attach_volume or attach_reserved_ip.

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 mentions required scope (services:write) and explains where to get parameter values ('id is the target VPC from list_networks; serverId is the Nova server id to move'). It does not explicitly exclude alternatives or provide when-not-to-use guidance, but the 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?

With no annotations provided, the description carries the full burden. It discloses permissions and the source of IDs, but lacks details about side effects (e.g., whether the attachment causes downtime, replaces existing IP, or is immediate). No output schema means the return value is unknown.

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 sentences, each adding value: purpose, permissions, parameter sources. No wasted words, and the key information 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?

For a simple attach operation with full schema coverage and no output schema, the description covers purpose, permissions, and parameter sourcing. It could mention behavioral side effects (e.g., network impact) but is adequate overall.

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 repeats the schema descriptions for both parameters, adding only the ownership constraint for serverId. It does not provide new semantic insight 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 clearly states the action: 'Attach a reserved (static) public IP to one of your cloud VMs.' The verb 'attach' and the specific resource and target distinguish it from sibling tools like detach_reserved_ip, reserve_ip, and release_reserved_ip.

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 specifies the required scope ('services:write') and notes 'Plain write — not gated,' indicating no additional gates. It also clarifies where the parameters come from (list_reserved_ips and owned VM). However, it does not explicitly mention when not to use this tool or provide alternatives, though the 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?

With no annotations, the description carries full burden. It mentions scope and non-gated write, but does not explain side effects (e.g., what happens if volume already attached) or error conditions.

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 concise sentences, front-loaded with the core action, 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?

Given no output schema no annotations, the description covers action, parameters, sourcing, and permissions. Missing mention of prerequisites (e.g., volume must be unattached) but still fairly 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% with clear descriptions. The description restates the parameter sources but adds no new meaning 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?

The description clearly states 'Attach a block storage volume to a cloud VM,' specifying the verb (attach) and resource (volume to VM). It differentiates from siblings like detach_volume and create_volume.

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 context: requires scope services:write, notes 'plain write — not gated,' and tells where to get parameters. It implies when to use but lacks explicit exclusions or alternative 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?

Discloses irreversible nature with confirm requirement, prepaid behavior (no refund, no upstream teardown), and scope sharing with VM/k8s mutations. Exceeds the destructiveHint annotation with specific behavioral details.

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?

Concise yet comprehensive; front-loaded with purpose, then covers scope, semantics, and precautions. Every sentence adds value, no fluff.

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?

Covers all critical aspects: purpose, prerequisites, behavior, and irreversibility. Lacks mention of return value or error handling, but not essential given no output schema and clear operational description.

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?

Adds significant meaning beyond schema: explains cancel parameter default and undo behavior, describes confirm's role as explicit user approval gate. With 100% schema coverage, description still provides essential context.

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 cancels any proxy service (ISP, GB Residential, mobile) with a specific verb and resource, distinguishing it from sibling tools like cancel_service or renew_proxy.

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 explains prepaid semantics, when to use (at period end), and how cancel parameter works (default true to cancel, false to undo). Mentions required scope and source of id, providing clear when-to-use guidance.

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

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

Beyond the destructiveHint annotation, the description adds crucial behavioral details: 'schedules teardown of the service' and explains the two cancellation types ('immediate' vs 'end_of_term'). It also mentions the required scope 'services:write'. No contradiction with 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?

The description is succinct (3 sentences) and front-loaded with purpose and scope. Every sentence adds necessary detail without redundancy. Structure supports quick comprehension.

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 the main behavioral aspects for a destructive tool (scope, timing, confirmation). However, it lacks information about the return value or what happens after cancellation (e.g., creates a ticket). Given no output schema, this 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?

The input schema already has 100% coverage with descriptions for all parameters. The description adds practical guidance: 'service_id from list_services', 'Pass confirm:true only after the user has explicitly approved', and clarifies the 'type' enum as timing options. This enhances usability 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 clearly states the action ('File a cancellation request') and the resource ('for a service'), specifying the scope requirement and the destructive nature. It distinguishes this tool from siblings like destroy_service or stop_service by detailing the two cancellation timing types.

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 clear context on when to use the tool: for cancellation, requiring explicit user approval via 'confirm:true'. However, it does not explicitly compare to alternative tools or state when not to use it, though the destructive hint and confirmation requirement imply cautious 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?

No annotations exist, so description carries full burden. It describes the operation as a 'WHOIS availability lookup' implying read-only, but doesn't disclose any side effects, error behavior, or expected return format. Minimal beyond basic operation.

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

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

Two sentences, no unnecessary words. First sentence establishes purpose and method, second provides example and usage advice. Perfectly front-loaded and efficient.

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 tool without output schema, the description covers purpose, usage context, and example. However, it omits what the return value will be (boolean? availability status?), leaving the agent partially informed.

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 description for the only parameter. The description adds 'Pass the full domain' reinforcing the format, but this is already in the schema. No additional semantics beyond what the schema provides.

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 the specific verb 'Check' and resource 'domain name availability' with context 'pre-purchase WHOIS availability lookup'. It differentiates from domain sibling tools (list_domains, get_domain, register_domain) by focusing on availability checking.

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 explicitly advises when to use: 'Use before quoting a registration or suggesting an alternative name.' This provides clear context and workflow integration. It lacks explicit 'when not to use' but the purpose is well-scoped.

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?

No annotations provided, so description carries full burden. Discloses auth requirement and return value, but lacks details on side effects or failure conditions.

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?

Extremely concise (4 sentences) with no fluff. Every sentence adds value: action, auth, parameter source, return value.

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

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

For a simple one-parameter tool without output schema, description covers key aspects. Lacks explanation of 'not gated' but otherwise 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 covers 100% with parameter description. Description reinforces same info without adding new semantics, meeting baseline.

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

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

The description clearly states the verb 'close' and resource 'support ticket', distinguishing it from sibling tools like get_ticket, create_ticket, list_tickets.

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 explicit permission requirement ('tickets:write'), notes it's not gated, and tells parameter source from list_tickets. Does not explicitly state when not to use, but contextually 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?

Since no annotations are provided, the description bears full responsibility. It discloses that the tool creates a referral link, places a cookie, redirects, and requires an active affiliate account and write scope. The explicit disclaimer 'NO money movement' helps set expectations. It does not mention error handling or return values, but for a simple creation tool, this is adequate.

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 concise at four sentences. Each sentence adds unique value: the main action, scope requirement, clarification about money movement, prerequisite, and parameter explanation. No extraneous words; front-loaded with the primary verb.

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 creation tool with no output schema, the description covers the essential: what it does, prerequisites, scope, and parameter details. It could optionally mention the return value (the generated link), but this is a minor gap given the tool's simplicity and the overall clarity.

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 input schema already covers the destination parameter with full description, min/max length. The description adds a redundant explanation but essentially repeats the schema. With 100% schema coverage, baseline is 3; no significant added value beyond confirming it must be an absolute http(s) URL.

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 the tool's purpose: 'Mint a signed affiliate referral link that redirects to a destination of your choice after placing the affiliate cookie.' This is a specific verb-resource pair. It also distinguishes from siblings by noting that affiliate activate and withdraw are not exposed, making this the sole affiliate creation 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 description provides explicit context: 'Requires scope account:write' and 'The affiliate account must already be active.' It also clarifies 'Plain write — NO money movement,' indicating this tool is not for financial transactions. While it doesn't name alternatives, the sibling list includes get_affiliate for reading, so the usage boundaries are reasonably 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?

No annotations provided, so the description fully covers behavioral traits: warns that the result is a live credential containing a bearer token, instructs not to echo it, explains TTL defaults and that 'never' mints a 10-year token, and describes the return format as raw kubeconfig YAML.

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 concise, front-loaded with purpose, and efficiently covers all necessary details without redundant sentences. Every sentence adds value.

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

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

Given 4 parameters, no output schema, and no annotations, the description provides solid coverage: security, prerequisites, return format, revocation. Could mention idempotency or error states, but it's fairly complete for the complexity.

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%, baseline 3. Description adds context: explains enum options for role and ttl, clarifies that 'never' means 10-year token, and ties service_id to list_services. This adds meaningful value 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 clearly states the verb 'create', the resource 'kubeconfig credential for managed Kubernetes cluster', and the purpose 'standing automation (CI, GitOps)'. It distinguishes from sibling tools like revoke_cluster_kubeconfig and download_cluster_kubeconfig.

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 explicit scope requirement (services:write), role options, TTL details, and references list_services for service_id. Also suggests revocation with revoke_cluster_kubeconfig. Lacks explicit when-not-to-use or alternatives, but the 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?

No annotations, so description must provide behavioral context. States scope requirement and that it's a 'plain write — not gated,' indicating no extra guardrails. Does not mention idempotency, error behavior, or whether it returns the created resource.

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

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

Two sentences plus a short parameter note. Front-loaded with action and prerequisites. No redundant information. Every sentence adds value.

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

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

For a simple one-parameter creation tool with no output schema, the description covers what, prerequisites, and subsequent steps. Could mention return value or synchronous nature, but overall 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 covers 100% of parameters with descriptions. Description repeats schema info ('name is the display name (1-63 chars)') without adding new semantic meaning. 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?

Clearly states action: 'Create a new cloud firewall (security group).' Distinguishes from siblings by mentioning 'Add rules with add_firewall_rule, then attach it to a VM with attach_firewall.' Highlights requirement 'Requires scope services:write.'

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 states required scope and that it's a plain write (not gated). Implicitly guides usage order: create firewall, add rules, attach. Lacks explicit when-not-to-use or alternative 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?

With no annotations, the description carries full burden. It discloses that the tool spends money (two separate hourly meters), requires confirm for cost approval, and describes the default for healthCheck. Lacks details on irreversibility beyond the confirm flag and error 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?

Single paragraph, front-loaded with purpose, no wasted words. Every sentence adds value, from the operation summary to billing implications to parameter 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?

Given 5 parameters, no output schema, and no annotations, the description is comprehensive. It covers purpose, billing, scope, parameters, and sibling tools. Minor gap: does not describe the return value on success.

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?

All parameters have schema descriptions, but the description adds significant extra meaning: confirm must only be true after user approval, port is both listener and member port, healthCheck defaults to true server-side, memberServerIds are Nova server ids, and name character range.

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 creates an L4 TCP load balancer with VIP, listener, pool, and floating IP. It distinguishes from sibling tools like add_load_balancer_member and remove_load_balancer_member by noting management afterward.

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 mentions required scope (services:write) and tenancy, and warns about spending money with the need for confirm:true after user approval. Does not explicitly state when NOT to use this tool, but the context of creation vs. management 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?

With no annotations, the description must disclose behaviors. It mentions auto-allocation of /16 CIDR and the write nature. However, it does not detail potential side effects (e.g., default rules), idempotency, or error conditions.

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 that front-load the purpose and requirements. Every sentence adds value, with no redundancy or unnecessary 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?

For a simple create tool with one parameter and no output schema, the description covers the operation, authorization, constraints, and next steps comprehensively.

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 one parameter described as 'VPC display name.' Description adds the character limits (1-253 chars) and notes auto-allocation of a /16 CIDR, providing useful context 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?

Clearly states 'Create a new private network (VPC)' with a specific verb and resource. Differentiates from sibling tools like delete_network and attach_network_vm by explicitly mentioning the creation and the follow-up 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?

Provides authorization requirement ('scope services:write'), explains that VPCs carry no separate charge, describes the name constraint, and suggests using attach_network_vm afterward. Lacks explicit when-not-to-use scenarios but is otherwise 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?

With no annotations, the description discloses the required scope (services:write), that it's a plain write (not gated), and the GB Residential-only constraint. It omits return values and potential errors, but overall is fairly transparent.

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

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

The description is concise (4 sentences), front-loads the purpose, and every sentence adds unique value (scope, constraints, parameter sources). No unnecessary 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?

Given the complexity (4 params, no output schema, many siblings), the description covers purpose, constraints, and parameter sourcing. It lacks information on the return value and error conditions, but is otherwise complete for a create tool.

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

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

The schema already describes each parameter (100% coverage), and the description adds valuable sourcing context (e.g., id from list_proxies, countryId from list_gb_residential_countries). This enhances meaning 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 specifies a concrete action (create a proxy-request) on a specific resource (GB Residential bucket), and distinguishes from ISP fixed-IP plans that use get_proxy_list. This differentiates among sibling tools effectively.

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 explicitly states when not to use this tool (ISP fixed-IP plans) and provides source endpoints for each parameter. However, it does not compare against other proxy-related siblings like order_proxy, leaving some 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?

With no annotations, the description carries full transparency burden. It discloses that the operation is a plain write with no billing impact and is not destructive. It could mention backup retention limits or concurrency, but the provided information is sufficient for an agent to understand the behavioral 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?

The description is extremely concise—four short sentences, each adding distinct information. It front-loads the purpose and follows with critical usage details, with no unnecessary words 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 creation tool with no output schema, the description is adequate but leaves gaps: it does not describe the return value (e.g., backup ID or status), error conditions, or limits on backup frequency. Given the tool's low complexity, this is acceptable but not comprehensive.

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 description coverage is 100%, and the description adds value by specifying that service_id should come from list_services. This helps the agent know how to obtain the required parameter beyond the schema's type definition.

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 the action ('Create an on-demand backup'), the resource type ('legacy VPS service'), and differentiates from sibling tools (there is no other create_backup tool). It is specific and 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 provides prerequisites (scope services:write) and safety guidance (no billing impact, not destructive), and tells how to obtain the parameter. However, it does not explicitly discuss when not to use this tool or alternative methods for backup creation.

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?

No annotations are provided, so the description carries full burden. It discloses auth requirements and constraints, but does not explain side effects (e.g., whether ticket ID is returned), success/failure signals, or idempotency. The phrase 'Plain write — not gated' adds some transparency but overall incomplete.

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 paragraph that front-loads the purpose and covers all parameters efficiently. It could benefit from structured bullets but remains concise without 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?

Given no annotations or output schema, the description adequately covers all parameters and constraints (length limits, optional attachments). Missing return value info and potential errors, but sufficient for basic usage.

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%, but the description adds valuable context: linking department to list_ticket_departments, clarifying priority enum values, and detailing attachment format (base64, no data: URI prefix). This goes beyond schema descriptions.

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 'Open a support ticket' as the primary action, with specific verb and resource. It distinguishes from sibling tools like reply_ticket and close_ticket by focusing on creation.

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 mentions required scope ('tickets:write') and that it is 'not gated,' but does not provide guidance on when to use this tool vs alternatives (e.g., when to reply to an existing ticket). Implicit usage from context but lacks explicit 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?

No annotations provided, so description must carry full burden. It discloses cost implications, scope requirement, confirm safety mechanism, size range, and name default. Does not mention idempotency or error behavior, but key behavioral traits are covered.

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 sentences that are concise and front-loaded. Could be more structured (e.g., bullet points), but each sentence adds necessary information without wordiness.

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, so return format is not described. However, the description covers all parameters, required scope, cost, and follow-up action. For a 3-param tool, it is fairly complete but missing output info.

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 decent descriptions. The description adds extra context for confirm (user approval), name default, and size range, but doesn't significantly enhance beyond 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 explicitly states 'Create a new block storage volume (Cinder)' with a specific verb and resource. It distinguishes itself from related tools like attach_volume, delete_volume, etc.

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 clear context: requires scope services:write, spends money, and advises to pass confirm:true only after user approval. Also mentions next step (attach_volume). No explicit when-not-to-use, but adequate guidance.

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

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

Beyond the 'destructiveHint: true' annotation, the description adds important behavioral details: irreversibility, required scope, and the need for explicit user confirmation. This enriches the agent's understanding of the tool's 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 description is concise (3 sentences) and front-loaded with the core purpose. Every sentence adds essential information without redundancy, making it efficient for an agent to parse.

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?

Given no output schema and adequate annotations, the description covers all critical aspects: purpose, prerequisites, side effects, and parameter usage. It is fully sufficient for safe and correct tool invocation.

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

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

With 100% schema coverage, the description enhances parameter semantics by reiterating the source of 'id' and emphasizing the conditional use of 'confirm'. This adds practical guidance beyond the schema definitions.

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

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

The description clearly states the action ('Delete') and the resource ('account-wide SSH key'). It distinguishes from siblings like 'add_account_ssh_key' and 'list_account_ssh_keys' by specifying the deletion operation.

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

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

The description provides clear usage guidance: requires scope 'account:write', uses 'confirm:true' only after user approval, and references 'list_account_ssh_keys' for the ID. It lacks explicit exclusions but covers essential usage context.

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

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

Confirms destructiveHint annotation with 'Low blast radius and easily re-created' context. Describes confirm-gated behavior and that it makes no API call if confirm is false or omitted.

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 concise sentences front-loaded with purpose, requirements, behavior, and usage. 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?

Covers purpose, permissions, confirmation flow, and singleton nature. Lacks description of return value on success, but given simplicity and destructive hint, this 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 covers 100% of parameters with good description. Description adds that the alert is a singleton and that confirm must be user-approved, providing extra context beyond 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?

Clearly states 'Remove the month-to-date spend alert', a specific verb+resource. Mentions it's a singleton, distinguishing from other delete tools, and references sibling set_billing_alert.

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 says requires scope billing:write, explains confirm parameter usage with approval requirement, and notes the alert is easily re-created via set_billing_alert, providing alternative context.

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

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

Beyond the destructiveHint annotation, the description adds that worker nodes are drained and destroyed, and that the operation is rejected if it would leave zero pools. This provides meaningful behavioral context without contradicting 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 sentences with no wasted words. The most critical information (action, destructiveness, constraints, parameter sources) is front-loaded and efficient.

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, and the description does not mention what the tool returns on success or failure. For a destructive action, agents would benefit from knowing the expected response (e.g., a confirmation object). Otherwise, the description covers inputs and constraints adequately.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining how to obtain service_id (from list_services) and pool (from list_cluster_pools), and for confirm clarifies the refusal behavior when not true. This is helpful but not extensive.

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 ('Remove') and resource ('worker node pool from a managed Kubernetes cluster'), clearly distinguishing it from sibling tools like add_cluster_pool, update_cluster_pool, and rename_cluster_pool.

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 clear context: requires scope services:write, states the constraint that the last pool cannot be removed, and mandates user approval via confirm:true. However, it does not explicitly compare to alternatives (e.g., update_cluster_pool) but the naming is sufficiently distinct.

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 destructiveHint annotation, description reveals irreversibility, server-side refusal when attached, and the exact behavior of confirm parameter. No contradictions.

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: first states core purpose, second provides critical usage details. No wasted words, 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?

For a simple delete operation with no output schema, the description covers prerequisites, constraints, user confirmation, and parameter source. Complete and actionable.

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 covers both parameters with identical descriptions. The description provides no additional semantic value beyond the schema (e.g., same text for confirm). Baseline 3 due to 100% schema coverage.

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 explicitly states 'Delete a cloud firewall' – a specific verb and resource. It clearly distinguishes from siblings like detach_firewall by noting the prerequisite to detach first.

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 when to use (delete firewall), when not (if still attached – detach first), prerequisites (scope services:write, id from list_firewalls), and user confirmation protocol (confirm:true only after explicit approval).

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 goes beyond the 'destructiveHint: true' annotation by explaining the irreversible nature: 'IRREVERSIBLE: the rule stops applying immediately, changing what traffic is allowed.' It also details the confirm parameter behavior (omit/false leads to refusal). No contradiction with 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?

The description is concise (three sentences), front-loaded with the purpose, and each sentence adds distinct information: purpose, scope, irreversibility, confirm usage, and parameter origins. No 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?

Given no output schema, the description does not need to explain return values. It covers the core operation, side effects, and prerequisites. It could mention that the removal is reflected in subsequent get_firewall calls, but this is implied. Overall, it provides sufficient context for an AI agent.

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?

Input schema has 100% description coverage, so baseline is 3. The description adds value by specifying that 'id and ruleId both come from get_firewall,' providing a data source hint. For the confirm parameter, the schema already explains behavior fully, so no extra credit needed.

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

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

The description clearly states 'Remove a rule from a cloud firewall,' which is a specific verb+resource. It implicitly distinguishes from the sibling tool 'add_firewall_rule' by being the inverse operation, and the tool name itself indicates deletion.

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 necessary prerequisites ('Requires scope services:write') and operational guidance ('Pass confirm:true only after the user has explicitly approved'). It also explains that id and ruleId come from get_firewall, aiding source selection. However, it does not explicitly state when not to use this tool versus alternatives like add_firewall_rule, though the name makes it 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?

Beyond the destructiveHint annotation, the description details the irreversible cascade deletion and VIP release, explains the authorization requirement, and describes the refusal behavior for k8s-managed resources. No contradiction with 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?

Four efficient sentences, front-loaded with purpose, followed by scope, effects, exceptions, and usage instructions. No redundant 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?

Given no output schema, the description covers all essential aspects: purpose, side effects, authorization, constraints, and parameter usage (id source, confirm requirement). It provides sufficient context for an agent 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?

Input schema has 100% description coverage for both parameters. The description reiterates that 'id comes from list_load_balancers' and the importance of confirm, but adds no significant new meaning 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?

The description clearly states the tool 'Delete a load balancer' and lists the cascade effects (listener/pool/members/health-monitor, VIP floating IP), distinguishing it from creation or listing tools. It also notes the exception for k8s-managed load balancers, further clarifying its 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?

The description explicitly requires scope 'services:write', advises to pass confirm:true only after user approval, and warns that it is refused for k8s-managed load balancers (directing to Kubernetes Service instead). This provides clear when-to-use and when-not-to-use guidance.

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

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

The description adds significant context beyond the destructiveHint annotation: explains irreversibility, server-side refusal conditions, and scope requirement. No contradiction with 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?

Compact yet complete: three sentences covering action, prerequisites, constraints, and user approval. Front-loaded with core purpose.

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?

Sufficient for a deletion tool: covers what, when to use, safety, and failure scenarios. Missing return value but not critical given destructive nature.

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 description adds meaning: id comes from list_networks, confirm must be explicitly approved. This reinforces schema descriptions effectively.

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 explicitly states 'Delete a private network (VPC)', clearly indicating the action and resource. It distinguishes from sibling tools like create_network and attach_network_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?

Provides explicit guidance: requires scope services:write, irreversible, refused for default VPC or with VMs attached, and instructs to pass confirm:true only after user approval. No direct alternative mentioned but 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?

Adds beyond destructiveHint annotation by stating IRREVERSIBLE and immediate endpoint termination. Also explains confirm parameter 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?

Every sentence serves a purpose: action, scope, irreversibility, parameter guidance. 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?

Covers all critical context: scope, irreversibility, prerequisites, and confirm usage. Complete for a destructive 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?

Adds value beyond schema by specifying data sources (list_proxies, list_proxy_requests) and confirm semantics (omit/false refuses).

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 states it deletes a proxy-request from a GB Residential bucket, specifies required scope, and distinguishes from other proxy-request operations.

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

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

Provides explicit when-to-use guidance: scope services:write, GB Residential only, and prerequisites for id and reqId. Does not explicitly contrast with other deletion tools, but 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 behavioral context beyond the destructiveHint annotation: it labels the operation as 'IRREVERSIBLE: the volume and its data are gone for good,' specifies the auth scope, and explains the confirm parameter's behavior (omit/false results in refusal). No contradiction with 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?

The description is concise, with three brief sentences that front-load the purpose and key behavioral points. Every sentence adds essential information without 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?

Given the tool's simplicity (2 params, no output schema), the description covers purpose, permissions, irreversibility, and parameter usage. It could mention billing impact or recovery options, but overall it is sufficiently complete for a delete operation.

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 parameter descriptions are already detailed. The description for id ('id comes from list_volumes') duplicates the schema, and the confirm behavior is also echoed. Minimal additional value over 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 clearly states 'Delete a block storage volume permanently,' specifying the action (delete) and resource (block storage volume). It distinguishes from sibling tools like detach_volume or delete_network by naming the resource type.

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 mentions the permission requirement ('Requires scope services:write') and the confirm parameter condition, but does not explicitly compare to alternatives like detach_volume or reinstall. It lacks when-not-to-use guidance.

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

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

Clearly warns that it spends money and provisions billable infrastructure. States that confirm:true is required for execution, otherwise no API call is made. Irreversibility implied. No annotations exist, so description carries full burden and does so well.

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?

Description is brief yet comprehensive: main purpose first, then behavioral warnings, then parameter guidance. Every sentence adds value. No fluff.

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?

Given the tool's complexity (29 params, polymorphic, billing), the description covers the essential workflow, prerequisites, cost implications, and parameter discovery. No output schema, so return value explanation is omitted appropriately.

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

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

With only 31% schema description coverage, the description adds significant value by explaining polymorphic behavior (category selects family), aliases (name, plan, image, sshKey), and directing users to discover family-specific fields via other tools. However, it does not describe all 29 parameters individually.

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 states it deploys a new service and charges the account. Distinguished from sibling tools like stop, destroy, etc. by focusing on ordering/provisioning.

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 requires scope services:write and user approval before passing confirm:true. Recommends previewing cost with get_product_details and discovering parameters with helper tools. Provides clear when-to-use and when-not-to-use guidance.

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

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

The description adds significant behavioral context beyond the destructiveHint annotation, stating 'IRREVERSIBLE: the service and its data are gone for good' and that the operation spends from the account balance. This goes beyond what the annotation alone 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?

The description is exceptionally concise: two short sentences and a numbered instruction. The critical information (irreversibility, confirm requirement, service_id source) is front-loaded with 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?

Given the tool's simplicity (2 params, no output schema, no nested objects), the description covers all necessary aspects: what it does, prerequisites, and behavioral implications. It fully equips the agent to use 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?

With 100% schema coverage, the description still adds value by clarifying that confirm must only be true after user approval and that service_id comes from list_services. This enriches the schema descriptions.

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 the verb and resource: 'Permanently destroy a service and release its resources.' It uses strong, specific language that distinguishes this destructive tool from sibling tools like get_service, stop_service, or reboot_service.

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 explicitly states prerequisites: 'You MUST pass confirm:true, and only after the user has explicitly approved.' and 'service_id comes from list_services.' This provides clear context for when and how to use the tool, though it does not explicitly mention when not to use it or list alternatives.

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

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

No annotations provided. Description discloses it's a write operation ('Plain write — not gated') and scope requirement, but does not mention reversibility, side effects, or behavior on duplicate calls.

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 concise sentences. First states purpose, second adds prerequisites and parameter sources. No redundant 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?

Covers purpose, permissions, and parameter sources. For a simple two-parameter write operation, this is adequate. No output schema, but return value is not described. Could mention if it returns the firewall or just success.

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% but description adds value by specifying that 'id comes from list_firewalls' and clarifying 'serverId is the Nova server id to detach from', which goes beyond schema descriptions.

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?

Description clearly states 'Detach a cloud firewall from a cloud VM' with specific verb and resource. Distinguishes from sibling tools like attach_firewall and 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?

Provides explicit context: requires scope 'services:write', parameter sources (id from list_firewalls, serverId is Nova server id). No explicit when-not or alternatives, but 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?

Despite no annotations, the description discloses key behavioral details: the IP remains allocated and billed after detach, and the permission requirement for a write 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?

Three sentences, all relevant: first states the action, second explains lifecycle, third gives permission and source of id. Front-loaded and efficient.

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 tool with one parameter and no output schema, the description fully covers effect, lifecycle, permissions, and parameter source. No 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 schema already describes the 'id' parameter as 'Reserved IP id from list_reserved_ips.' The description adds minimal extra value by restating 'id comes from list_reserved_ips.' With 100% schema coverage, baseline is 3.

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

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

The description clearly states the action 'Detach a reserved public IP from its VM' and distinguishes from sibling tools like release_reserved_ip and attach_reserved_ip by mentioning the IP stays allocated and can be released later.

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 explicitly states the required scope ('services:write') and notes that it is a plain write not gated, giving clear guidance on when to use this tool and when to use release_reserved_ip instead.

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

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

With no annotations, the description must self-disclose behavior. It correctly identifies it as a write operation and mentions authorization, but does not detail side effects like whether the volume persists independently after detachment or if any data loss occurs.

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 extremely concise with two sentences, front-loading the action and providing necessary detail without unnecessary 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?

Given only two required parameters and no output schema, the description covers the essential aspects: the operation, authorization, and parameter sources. It is sufficient for an agent to correctly select and invoke the tool.

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

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

The schema already describes both parameters (volume id and server id) but the description adds value by specifying that the volume id comes from list_volumes and that serverId is a Nova server id, which provides context 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 clearly states the action (Detach) and the resource (block storage volume from a cloud VM), and distinguishes it from sibling tools like attach_volume, create_volume, and delete_volume.

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 specifies the required scope (services:write) and indicates it's a 'plain write' operation. It also mentions that the volume id comes from list_volumes, providing context for when to use this tool. However, it does not explicitly state when not to use it or list alternatives.

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

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

With no annotations, the description carries full burden. It discloses the result is a live credential with a bearer token, gives security instructions, and mentions revocability. It does not explicitly cover auth or rate limits, but the security context 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?

The description is front-loaded with the core action, then adds conditional, security, and return info in logical order. Slightly verbose but each sentence earns its place.

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

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

Given no output schema, the description explains the return type (raw kubeconfig YAML). It also covers prerequisites, security handling, and error conditions. Fully complete for a 2-parameter read operation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the parameter provenance (from list_cluster_kubeconfigs) and the active-credential constraint, which is not in the schema.

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

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

The description uses a specific verb ('Re-download') and resource ('LONG-LIVED kubeconfig credential'), and explicitly distinguishes from the sibling tool get_cluster_kubeconfig by contrasting long-lived vs short-lived credentials.

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 clearly states when to use this tool ('for standing automation that must keep working'), when not to use ('revoked or expired credentials return an error'), and explicitly names the data source for parameters (list_cluster_kubeconfigs).

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?

Discloses all key behaviors: money spent, irreversibility, idempotence, required scope, and confirm requirement. No annotations provided, so description fully carries the burden.

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

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

Four sentences plus a phrase, no fluff. Information is front-loaded with purpose, then requirements and caveats. Every sentence adds value.

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

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

Given tool complexity and no output schema, description covers all necessary aspects: action, prerequisites, cost, irreversibility, and confirmation needed. Complete for agent usage.

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% but description adds value: explains confirm is needed only after user approval and that service_id comes from list_services. Goes beyond 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?

Clearly states it enables HA control plane on a managed Kubernetes cluster, with specific effect (multi-zone API server/etcd). Distinguishes from siblings by being a unique enabling 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?

Explicitly says it's add-only, irreversible, and requires user approval due to cost. Specifies when to use (after user approves) and where to get service_id. Provides idempotency info.

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?

No annotations are provided, so the description must carry the full burden. It discloses the returned fields, which is good, but does not mention that the tool requires authentication, is read-only, or has no side effects. The term 'authenticated user' implies auth, but it's not explicit.

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 consists of two short, focused sentences. The first sentence enumerates the returned fields, and the second provides usage guidance. No wasted words; it is efficient and 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?

For a simple read tool with no parameters and no output schema, the description covers the essential aspects: what it returns and when to use it. It does not mention error cases or authentication details, but given the low complexity, it is mostly 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?

There are no parameters, and the schema coverage is 100% (empty). The description adds value by listing the fields returned, giving the agent context about what data to expect. This goes beyond the schema and justifies a score above baseline.

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

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

The description clearly states the tool retrieves the authenticated user's profile with specific fields (email, name, country, billing currency, account creation date). It also gives a concrete use case ('what account am I on?'), distinguishing it from sibling tools like get_billing_state or get_account_limits.

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 explicitly says to use it to confirm identity before cross-account actions or to answer 'what account am I on?'. This provides clear context. It doesn't explicitly state when not to use it, but the use case is specific enough to avoid misuse.

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 no annotations, the description carries the full burden. It discloses pagination behavior, default ordering, and the types of events included. It does not mention authorization or rate limits, but for a read-only audit trail tool, this is sufficient.

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

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

The description is two sentences with no wasted words. The first sentence covers purpose and content, the second covers pagination and usage. It is front-loaded and efficient.

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?

Given no output schema, the description provides adequate context: it lists event types, ordering, and pagination. It could mention what fields are returned, but for a simple list tool, the description is reasonably complete.

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

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

Schema description coverage is 100% (both parameters have descriptions in the schema). The tool description rephrases the same information without adding new meaning. Per the scoring rule, 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 ('Get') and resource ('account audit trail'), lists specific event types (sign-ins, 2FA changes, etc.), and specifies ordering (newest first). This clearly distinguishes it from sibling tools like get_bonus_ledger or get_billing_alert.

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 explicitly states when to use the tool: 'Use for "show my recent account activity" or a security review.' It does not mention when not to use or compare to alternatives, but the provided use cases 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?

No annotations provided, and the description does not disclose behavioral traits such as whether the operation is read-only, requires authentication, or has rate limits. For a tool with no annotations, the description should fill this gap; it only states what it retrieves without further safety or side-effect information.

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 succinct sentences: first clearly defines purpose, second provides usage context. 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?

The tool is simple (no parameters, no output schema). The description lists resource categories and gives a usage scenario. It would benefit from noting that it returns both limits and current usage values, but overall is sufficiently complete for its complexity.

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 input schema has zero parameters (100% coverage via empty schema). With no params, the baseline is 4. The description does not need to add param details, and it 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?

Description explicitly states 'Get account resource limits and current usage', with a specific verb and resource type. It lists the categories (servers, vCPUs, etc.), distinguishing it from sibling tools like get_account which returns account metadata.

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?

Explicit guidance: 'Use before recommending a deploy to make sure the user has headroom.' Provides clear context for when to use, though does not mention when not to use or name alternative 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?

No annotations provided, so the description carries the full burden. It discloses a key behavioral trait: returns {active:false} when the affiliate program is not enabled. It also describes the return structure comprehensively. Could mention authentication or rate limits, but for a read-only tool without parameters, this is reasonably transparent.

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

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

The description is concise and well-structured: starts with main purpose, lists output fields, handles the edge case, and ends with a use case. Every sentence adds value without redundancy. It is front-loaded with the essential operation.

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?

Given no output schema, the description adequately covers the return values by listing the main fields (referral link, stats, commissions, etc.) and the failure case. It is mostly complete for an AI agent to understand what to expect, though exact JSON key names or types are inferred rather than specified.

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 input schema has no parameters, so schema coverage is 100%. The description implicitly confirms no parameters by focusing entirely on output. It adds value by explaining what the tool returns, which is appropriate given zero parameters. Baseline is 4 for no-parameter tools.

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 states the tool's purpose: 'Get the authenticated account's affiliate status and stats.' It specifies the exact data returned (referral link, visitors/signups/conversion rate, commissions summary, etc.) and distinguishes itself from siblings like create_affiliate_link by focusing on retrieval of stats rather than creation.

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 direct use case: 'Use for "how are my referrals doing?"' This gives clear context for when to use the tool. However, it does not explicitly list alternatives or conditions when not to use it, though the sibling list contains no other affiliate stats tool, so the guidance is sufficient.

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?

No annotations are provided, so the description carries the full burden. It describes the read behavior (getting state) but does not explicitly state it is read-only or mention side effects, authentication needs, or error conditions. While 'get' implies safe reading, explicit disclosure would improve safety understanding.

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

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

Two sentences, front-loaded with the core purpose, and no extraneous text. Every sentence adds value.

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

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

Given no output schema, the description sufficiently lists the return fields. There are no nested objects, pagination, or other complexities. The description is complete for a simple getter.

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

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

There are 0 parameters, so the baseline is 4. The description adds value by explaining what the tool returns (threshold, spend, triggered status), which goes beyond just the tool name. No parameter information is needed.

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

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

The description clearly states the tool retrieves spending-alert state including threshold, month-to-date spend, and triggered status. It uses a specific verb 'Get' and resource 'spending-alert state'. The sibling list shows no other getter for billing alerts, so it's well-distinguished.

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 explicitly provides a use case: 'Use for "am I close to my spending alert?"' This gives clear guidance on when to invoke the tool. However, it does not mention when not to use it or alternatives, but given the simplicity, this is adequate.

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

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

With no annotations provided, the description bears the full burden of behavioral disclosure. It explains the return value (active campaign or null) and implies no side effects, but doesn't discuss authentication requirements or potential rate limits. While adequate, it could be more explicit about being read-only (though inferred).

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

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

The description is two sentences long, front-loads the purpose, and every sentence adds value. No redundant or extraneous 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?

Given the tool has no parameters and no output schema, the description adequately covers what it does, its return type, and a primary use case. It doesn't detail the campaign structure or auth, but for a simple read tool this is 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 has no parameters, and the schema coverage is 100% (no parameters to cover). The description adds no parameter details, which is acceptable as there are none. Baseline of 4 applies for zero-parameter tools.

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 the tool gets the currently-active credit/deposit-match campaign and specifies it returns {campaign: null} when none is running. It distinguishes itself from sibling tools like get_bonus_ledger or get_credit_balance by focusing specifically on the promotional campaign.

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 advises checking before suggesting a top-up to catch a bonus match, providing a clear use case. It doesn't explicitly exclude other scenarios or mention alternatives, but the context is adequately clear for this simple read 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?

Without annotations, the description carries full burden. It clearly indicates a read-only query returning state, though it omits details like error handling or rate limits. The simplicity of the tool mitigates the gap.

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

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

Two sentences, no redundancy. First sentence defines purpose and output, second sentence provides usage advice. Efficient and well-structured.

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?

Given no output schema, the description fully explains what is returned and the purpose. The context of low balance risk completes the picture. No missing elements for a simple no-param getter.

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

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

No parameters exist (0-param tool), so baseline is 4. The description adds no parameter info, but nothing is needed. It adds value by explaining the output values and purpose.

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 the tool returns the cloud auto-suspend state (normal/grace-period/suspended) and connects it to the billing banner, distinguishing it from sibling tools like get_billing_alert which handle alert thresholds.

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 explicitly tells when to use it ('check whether a low balance is putting services at risk of suspension'), but does not contrast with alternatives or state when not to use it.

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

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

Without annotations, the description adds behavioral context: the balance is a separate promo balance that depletes first as a taxed discount line. This goes beyond a simple 'get balance' and informs the agent about the balance's nature and priority.

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 concise sentences, front-loading the purpose and then adding behavioral detail. Every sentence is informative without 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?

Given no parameters and no output schema, the description sufficiently explains the return value and how it integrates with get_credit_balance. It does not cover error states or availability, but for a simple read tool this 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?

There are no parameters, so schema coverage is 100%. The description adds value by explaining the return value (balance in cents EUR) and the balance's role, which is helpful beyond the empty schema.

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

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

The description clearly states the tool returns the account's promo balance in cents EUR, and distinguishes it as a separate non-WHMCS balance. It also differentiates from sibling tool get_credit_balance by explaining how this balance depletes first.

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 explicitly advises pairing with get_credit_balance for a complete spending picture, providing usage context. However, it does not give strict when-not-to-use guidance or alternative tools for other scenarios.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It mentions ordering and entry types but does not describe whether the operation is read-only, requires authentication, returns paginated results, or what fields are included. While adequate for a simple list, it leaves some behavior implicit.

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

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

The description is two sentences long, front-loads the main purpose, and adds just enough context to differentiate from siblings. Every word earns its place with no 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?

Given the tool has zero parameters and no output schema, the description sufficiently covers what the tool does and why one would use it. It answers the likely user question. However, it omits any mention of potential filtering or the exact return format, which could be useful but is not critical for such a simple tool.

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

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

The input schema has zero parameters, so schema coverage is 100%. The description does not need to add parameter details. Per guidelines, 0 parameters yields a baseline of 4.

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 the tool lists bonus-credit ledger entries, specifies ordering (newest first), and distinguishes between positive (campaign grants) and negative (promo consumption) entries. It also explicitly differentiates from the sibling tool get_credit_ledger, which tracks real credits.

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 a clear use case ('explain where did my bonus go?') and explicitly names the alternative get_credit_ledger for real credit tracking, guiding when to use which. However, it does not explicitly list when not to use the tool or conditions that might make get_bonus_balance more appropriate.

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?

No annotations are provided, so the description must disclose behavioral traits. It does not mention that the tool is read-only, requires authentication, or handles errors (e.g., invalid SKU). The description implies a safe query but lacks explicit transparency.

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: first explains what the tool returns, second tells when to use it. No fluff, every sentence earns its place. Ideal length for a simple tool.

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

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

The description enumerates the return contents (plans, specs, pricing, billing tracks) and usage context. It lacks details on error handling or output structure, but for a one-parameter tool with no output schema, this is reasonably complete.

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

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

The schema covers the single 'sku' parameter 100%, and the description adds value by specifying the source ('from list_catalog_products') and providing an example. This goes beyond the schema's description, earning a 4.

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 explicitly states the tool retrieves 'full details for a single catalog product including all plans, specs, pricing, and billing tracks'. It clearly distinguishes from sibling tools like 'list_catalog_products' which lists SKUs, and 'get_product_details' which may be less specific.

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