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

Annotations already declare the safety profile (not read-only, not destructive, open-world), so the description's job is to add what they don't cover. It does exactly that by disclosing a genuinely non-obvious side effect: the contact is created with a random email and must be corrected in Invapi. Auth/rate-limit details are still absent, so not a 5.

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

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

Two sentences, zero filler, with the action stated first and the critical WARNING front-loaded where an agent will not miss it.

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

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

For a one-parameter mutation with no output schema, the definition covers what it does, the target system, and the key gotcha. It stops short of explaining which account scope is used or what the call returns, but nothing essential to calling it correctly is missing.

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

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

There is only one parameter and the schema documents it fully ('Must be true to run the operation'), so the schema carries the load. The description adds no extra meaning about 'confirm', which is the correct baseline when coverage is 100%.

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

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

States a specific verb and resource ('Add an additional contact to the account') and even names the underlying endpoint (whmcs/add_contact). The word 'additional' implicitly separates it from update_contact/delete_contact, but no sibling is named explicitly.

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

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

The description never says when to reach for this versus update_contact, get_contacts, or delete_contact, nor what prerequisites (a valid account/client) are needed. The only workflow hint is the post-creation fix-up, which is a behavioral caveat rather than usage guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description adds a real behavioral fact the annotations omit — the required pdns/edit permission — which is valuable for auth planning. It still omits conflict/duplicate handling and reversibility, but given annotations carry the safety profile, a 3 is appropriate.

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

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

A single tight sentence front-loading the action, with the endpoint and permission requirement as compact trailing clauses. Every phrase earns its place with no filler.

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

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

For a create tool with no output schema and annotations covering the mutation profile, the description plus schema are mostly sufficient. The notable gap is the unresolved overlap with the add_dns_zone sibling, which the description does not address.

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

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

Schema description coverage is 100%, so both parameters ('name' with an example, 'confirm' with its meaning) are fully documented in the schema. The description adds no parameter detail beyond that, so the baseline 3 applies.

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

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

The description names specific verbs and resources ('Create a DNS zone and add a domain to the domains table') plus the underlying endpoint (pdns/add_domain), so the action is unambiguous. However, it fails to differentiate from the sibling add_dns_zone, and by mentioning both 'create a DNS zone' and 'add a domain' it blurs the boundary between the two tools.

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

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

It states a permission prerequisite (pdns/edit) but gives no guidance on when to use this tool versus add_dns_zone/add_dns_subdomain, and no exclusions or context for choosing it. The agent is left to infer usage from the name alone.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so safety profile is covered. The description adds real behavioral value beyond that: the required pdns/edit permission, the upsert semantics ('add or update'), and error-recovery guidance for SOA. It does omit that confirm must be true to execute, which is a notable guard the agent must know.

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

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

Three compact sentences, front-loaded with purpose then prerequisites then type-specific detail. No filler, though the final 'fill them in on error' clause is slightly cryptic out of context.

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

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

For a 15-parameter mutation tool with no output schema, the description covers purpose, auth, and the trickiest record types. It omits mention of the mandatory confirm flag and increase_soa_serial default, but those are documented in the schema, so the gap is minor.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds cross-field conditional meaning the schema lacks: it ties proto/priority/weight/port/target together specifically for SRV records and explains the mname/rname practical trigger (SOA check failure). That is genuine guidance beyond the flat per-parameter 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?

States a specific verb (add or update) and resource (DNS record in a zone) plus an internal API hint (pdns/add_dns). It clearly contrasts with the delete_dns_record sibling by verb, but never names or distinguishes itself from other write siblings like add_dns_zone or edit_dns_subdomain.

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

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

Gives actionable context: the pdns/edit permission requirement, when to populate SRV fields, and the SOA-fill-on-error tip. However, it never states when to use this tool versus alternatives such as edit_dns_subdomain or delete_dns_record, leaving the routing decision to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful non-annotation context: the required pdns/edit permission and the backing API endpoint. It still does not say what happens on duplicate names or on failure.

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

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

One compact sentence with the action front-loaded and zero filler. The parenthetical endpoint is the only arguably optional element, but it is short and aids traceability.

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

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

For a four-required-parameter mutation tool with no output schema, the definition covers the action and the auth requirement but omits edge-case behavior (duplicate subdomain, validation failures) and any note on the confirm flag's meaning beyond what the schema already states.

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

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

Schema description coverage is 100%, so all four parameters (name, confirm, domain_id, server_id) are already documented in the schema, including the cross-reference to list_dns_domains. The description adds no parameter-level detail, so baseline 3 applies.

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

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

States a specific verb and resource ("Add a subdomain") and even names the underlying API operation (pdns/add_subdomain). It is distinguishable from siblings like add_dns_domain, add_dns_zone, and edit_dns_subdomain, though it never explicitly contrasts itself with them.

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

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

Usage is implied by the name and the permission note, but there is no explicit when-to-use guidance, no mention of the edit_dns_subdomain alternative, and no statement of prerequisites beyond the pdns/edit permission requirement.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description usefully adds the required pdns/edit permission and the authoritative-server target, but says nothing about idempotency, what happens on a name collision, or whether zone creation is reversible.

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

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

Two compact sentences, action first, permission second, with zero filler or restated field lists.

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 an 8-parameter, one-nested-object mutation with no output schema, the description covers action, target, and permission but omits conflict/failure behavior and any hint of when this is the right choice. Adequate but with clear 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?

Schema description coverage is 100%, so the nested SOA object, kind enum, dnssec/rrsets defaults, and the mandatory confirm flag are all documented in the schema itself. The description adds no parameter-level meaning beyond that, making 3 the correct baseline.

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

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

States a specific verb+resource ("Create a DNS zone") and names the underlying target (authoritative PowerDNS server / pdns/add_zone), which is concrete enough to act on. It does not, however, differentiate itself from the sibling add_dns_domain, which an agent could easily confuse with this tool.

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

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

The only guidance given is the required permission (pdns/edit). There is no statement of when to prefer this tool over add_dns_domain or add_dns_subdomain, nor any prerequisite or conflict conditions.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds one useful behavioral fact, that the created user is 'temporary', but says nothing about credential lifetime, permissions granted, or the need to clean up with remove_ipmi_user.

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

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

A single compact sentence that front-loads the action and resource before the trailing parenthetical. The '(eq/add_ipmi_user)' endpoint note is minor internal noise but the structure is otherwise tight 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?

Adequate for a 2-parameter mutation whose annotations carry the safety profile, but it omits the lifecycle context an agent would want: how the temporary credential is returned or used, and that remove_ipmi_user is the corresponding cleanup. Nothing misleading, just incomplete.

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?

Both parameters are fully documented in the schema (id = Server ID, confirm = must be true), giving 100% coverage, so the baseline is 3. The description adds no additional meaning such as credential naming or implications of the confirm flag.

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

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

States a specific verb and resource ('Create a temporary IPMI user') and clarifies its purpose ('for web access to IPMI'). It does not, however, differentiate itself from sibling tools like request_rh_kvm or remove_ipmi_user, so an agent must infer the distinction.

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

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

The phrase 'for web access to IPMI' implies when the tool is relevant, but there is no explicit when-to-use guidance, no exclusions, and no mention of alternatives such as request_rh_kvm or the paired remove_ipmi_user cleanup path. Usage is left to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, so the safety profile is largely covered. The description adds the specific permission requirement, which is real behavioral value, but does not explain what happens on the update path (overwrite vs merge) for an upsert-style operation.

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

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

A single compact sentence with the operation front-loaded and the permission caveat trailing. No filler; appropriately sized for the tool's simplicity.

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

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

With annotations carrying the safety hints, three fully documented params, and no output schema to explain, the description covers the essentials including the auth requirement. The remaining gap is disambiguation from upload_iso.

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

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

Schema description coverage is 100%, so the schema already documents url, name, and confirm, including that confirm must be true. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ('Add a new ISO image or update an existing one by name') and even cites the underlying endpoint (iso/add), so the agent knows exactly what it does. It does not, however, differentiate itself from close siblings like upload_iso or mount_iso, which could confuse selection.

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 supplies a prerequisite ('Requires special add permission'), which is useful context. But it gives no guidance on when to choose this over upload_iso or delete_iso_image, so usage is only implied by the name.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the write/safety profile is largely covered. The description adds genuinely useful context with 'client-visible', flagging that the message is exposed to the client rather than internal-only. It does not explain the confirm requirement or any visibility/permission nuances.

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

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

A single tight sentence with the action front-loaded and no filler. Appropriately sized for the tool's simplicity, though it could have used one more clause to cover the confirm gate.

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 3-parameter write tool with full schema coverage, no output schema, and annotations covering the safety profile, the core information is present. It is adequate but thin: it omits the confirm prerequisite behavior and any relationship to the other RHR tools, which would help an agent route correctly.

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

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

Schema description coverage is 100%, so the schema already documents id, message, and confirm, including that confirm must be true. The description adds only the 'client-visible' qualifier for the message, which is the correct baseline-3 situation where the schema does the heavy lifting.

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 (Add) and resource (a client-visible message to the request history/chat), which is far more informative than the name alone. The 'rhr/chat' parenthetical ties it to the RHR family. It stops short of explicitly distinguishing it from siblings like create_rhr_request or discard_rhr_request.

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

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

No guidance on when to use this versus the related RHR tools (list_rhr_requests, create_rhr_request, discard_rhr_request), nor any prerequisites. The reader must infer usage entirely from the one-line purpose.

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

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

Annotations already declare that this is a non-read-only, non-destructive, open-world operation. The description adds useful behavioral context beyond annotations: the call is asynchronous and should be tracked with `check_task`, and `ip_acl` may be required by some accounts. It does not describe duplicate-NAT behavior, permissions, or side effects in detail, but the annotation coverage lowers 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?

The description is front-loaded with the core action and resource, then adds only operationally relevant clauses: endpoint, distinction from Secure IPMI Proxy, async tracking, and ACL handling. There is no filler, and each clause contributes to correct tool selection or invocation.

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

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

For a mutation tool with no output schema, the description covers the essential context: what it creates, why it is needed versus proxy access, that it is asynchronous, how to track it via `check_task`, and when to supply `ip_acl`. The remaining parameter details are fully covered by the schema and annotations.

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 all five parameters are already documented, establishing a baseline of 3. The description adds meaningful conditional semantics for `ip_acl` by saying to pass it when `server_ipmi_acl_required` occurs, which goes beyond the schema's generic parameter description.

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

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

The description states a specific verb and resource: create a static DNAT for server IPMI, with the underlying endpoint `nat/add_static_nat`. It also clarifies the use case as public IP for classic IPMI access and distinguishes it from the Secure IPMI Proxy feature, so an agent can identify the operation without opening the schema.

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

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

The description gives a clear usage condition: it is for classic IPMI access via public IP, and Proxy Active alone may not satisfy the call. It also tells the caller to pass `ip_acl` when `server_ipmi_acl_required` occurs. It does not explicitly name sibling alternatives such as `clear_static_nat`, `remove_static_nat`, or `drop_nat`, so it falls short of full when/when-not/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?

Annotations already declare readOnlyHint=false and openWorldHint=true, so the write nature is covered. The description adds meaningful context by warning 'MONEY: deducts funds from the account' and noting partial payments, though it omits prerequisites such as sufficient credit or irreversibility.

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

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

Two short sentences, front-loaded with the action and resource, followed by a compact financial warning. The parenthetical API path is minor but harmless, and 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 financial write tool with full schema coverage and annotations covering the read/write boundary, the description is adequate but incomplete. It does not address prerequisites (e.g., sufficient credit balance), error behavior, or when to choose this over sibling payment tools like mass_pay.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The phrase 'in full or in part' adds a small amount of meaning to the amount parameter by clarifying partial payments are allowed, but it provides no syntax or additional parameter-level detail beyond the schema.

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

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

The description states a specific verb ('Pay'), resource ('invoice'), scope ('in full or in part'), and funding source ('credit balance'). It is clear enough to distinguish from payment-gateway siblings, but it does not explicitly name alternatives such as mass_pay or create_addfunds_invoice, so it falls short of full sibling differentiation.

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

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

There is no explicit when-to-use or when-not-to-use guidance, nor any mention of alternative tools. The purpose implies the tool is for paying an invoice from credit, but that is tautological rather than actionable routing advice.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is partly covered. The description adds the network-level scope and abuse-request framing, but says nothing about reversibility (the four_hours auto-lift and unblock_ip are left undisclosed) or permission requirements. With annotations doing part of the work, this is adequate but not rich.

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

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

A single tight sentence with the core action front-loaded, plus a short 'useful for' clause. Nothing is wasted, though the parenthetical API path is marginal detail.

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

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

For a simple, fully-schema-documented mutation with no output schema, the description covers the core action and safety is partly carried by annotations. However it omits how the block is reversed (four_hours expiry / unblock_ip) and any permission or side-effect context, leaving meaningful gaps for a state-changing 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 description coverage is 100% and all five parameters (id, ip, description, confirm, four_hours) are documented in the schema itself. The description adds no parameter-level meaning such as the effect of four_hours or the confirm gate, so the baseline 3 applies.

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

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

States a specific verb+resource ('Block an IP address on the server') and adds the network layer ('Hostkey network level'), so the operation is unambiguous. It does not explicitly contrast itself with the sibling unblock_ip, so an agent has to infer the pairing rather than being routed to it.

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?

'Useful for abuse requests' gives an implied context for when the tool applies, but does not name unblock_ip as the inverse operation, nor state any exclusions or prerequisites (e.g. needing the server id and a reason). Usage is implied rather than spelled out.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, but the description adds non-obvious gating context: confirm=true is ALWAYS required and destructive/paid actions additionally need HOSTKEY_ALLOW_DESTRUCTIVE=1. That is real auth/prerequisite disclosure beyond the annotations, though it does not describe response/error behavior for this raw passthrough call.

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

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

A single dense but well-ordered block: purpose first, examples second, hard requirements third, routing rule last. Every clause earns its place, though the run-on examples-plus-URL sentence is slightly heavy.

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 universal passthrough tool with no output schema, the description covers scope, mandatory confirmation, the destructive env-var gate, and alternative routing, which is most of what an agent needs. It does not characterize the shape of returned data or failure modes, a minor gap for an openWorld raw call.

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

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

Schema description coverage is 100% and each of the 5 parameters is documented there, including the confirm gate and the nested-object params convention. The description adds resource examples (iso, s3, rhr) and a docs pointer for the action vocabulary, but nothing the schema does not already cover, so baseline 3 applies.

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

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

States a specific verb and resource ('Universal direct InvAPI call by resource and action') and immediately scopes it to 'resources without typed tools', naming concrete examples (iso, s3, rhr). An agent can distinguish this generic escape-hatch tool from the many typed siblings without opening any schema.

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

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

Explicitly says when to use it (resources lacking typed tools) and when not ('Prefer typed tools when they exist for the needed operation'), plus routes to the docs for the action list. This is exactly the when/when-not/alternative guidance the dimension asks for.

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 substantial context beyond the readOnly/openWorld annotations: how to interpret result values ('Not ready' vs 'OK'), that the key expires after completion, that deploys can take 10-30 minutes, and that progress notifications are emitted when a progressToken was supplied. This is exactly the lifecycle/timing detail annotations cannot carry.

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

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

Front-loads the core action, then packs interpretation, timing, and notification behavior into a few dense clauses. Every sentence carries usable operational information with no filler.

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

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

With no output schema and no annotations covering return values, the description takes on the full burden and delivers: result semantics, key expiry, and expected latency. Nothing an agent needs to poll and reason about completion is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining the parameter's origin (the key from a prior async response) and its lifecycle (the key expires once the result is 'OK'). It stops short of adding format details, so it is not a full 5.

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

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

States a specific verb (Check) and resource (async job status) and names the exact mechanism (eq_callback/check) with the callback key. No sibling tool does this, so it is unambiguous even within a large tool set.

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

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

Clearly states when to use it: operations that return {"result":"OK","callback":"<key>"}, enumerating concrete examples (power on/off, order, reinstall, snapshots). It does not state when NOT to use it or name a polling alternative, so it falls just short of a 5.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the mutation profile is known. The description adds genuinely non-obvious behavior beyond that: skipping this step causes an unexpected reinstall on the next reboot, which is exactly the kind of consequence an agent cannot infer from structured fields.

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

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

A single dense sentence that front-loads the workflow position, then the action, then the consequence of omission — front-loaded and mostly waste-free. The terse 'step 7' and endpoint parenthetical are compact rather than padded.

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

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

For a 3-param mutation tool with no output schema, it covers purpose, workflow ordering, and failure consequence, which is nearly everything an agent needs. Minor gaps (behavior if the config is already absent, why confirm plus id plus hostname are all required) remain.

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% (id, hostname, confirm are all documented, including 'Must be true to run the operation'). The description adds no parameter-level detail, so this is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource (remove the PXE config), names the underlying endpoint (eq/clear_pxe), and locates the tool as step 7 of the PXE reinstall workflow. An agent can immediately distinguish it from the sibling create_pxe_config.

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 when to call it ('REQUIRED after completion') and ties it to a concrete sequence position (step 7), which is strong context. It does not name a when-not condition or point at an alternative tool, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true, so the agent knows this mutates remote state; the description adds the useful scoping detail that removal is keyed by internal IP (i.e., potentially all rules for that IP), which goes beyond the annotations. It stops short of stating whether the operation is irreversible, idempotent, or requires elevated auth, and destructiveHint=false sits somewhat awkwardly with a verb like "Remove".

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

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

A single front-loaded sentence with no filler. The trailing parenthetical "(nat/clear_static_nat)" merely restates the tool name/endpoint and earns little, keeping it just short of a 5.

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

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

There is no output schema, so return values need not be explained, and annotations carry the safety profile. Still, for a state-mutating removal keyed by IP, the description leaves unclear whether one rule or all matching rules are deleted and what failure looks like, which is a real gap for an agent deciding to call it.

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

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

Schema description coverage is 100%, so both `ip` and `confirm` are already documented; baseline is 3. The phrase "by internal IP" adds modest value by clarifying that the IP is the selector for which rules are cleared, but the description adds nothing about the mandatory `confirm` flag or the address format.

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?

Clear verb+resource+scoping: "Remove ... static NAT forwarding rules by internal IP". An agent knows exactly what is affected and how it is keyed. However, it does not distinguish itself from the near-identical sibling remove_static_nat (or drop_nat), so the selection decision is left ambiguous.

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 word "stale" hints at the intended scenario (cleaning up obsolete rules), which is a weak implied usage signal. There is no explicit when-to-use, no when-not-to-use, and no routing to remove_static_nat or drop_nat, which is exactly what this tool's closest siblings would require.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety posture is largely covered. The description does add real value beyond them by flagging that this creates an actual monetary invoice; however it stops short of saying whether funds are captured immediately, whether it is reversible, or what the confirm flag protects against beyond the schema's own text.

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

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

Two tight sentences with no filler, and the key impact signal ('MONEY') is front-loaded. The parenthetical API path is arguably internal plumbing, but it is short and harmless.

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 money-moving mutation with no output schema, the description plus annotations cover the essentials: it writes, it's not read-only, it touches the open world, it creates a real invoice, and confirm must be true. It still leaves the agent guessing about downstream effects (payment capture, whether the invoice must be paid separately) and offers no routing hint to the sibling billing tools.

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

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

Schema description coverage is 100% (amount is 'Top-up amount in account currency', confirm is 'Must be true to run the operation'), so the schema carries the parameter burden. The description only restates 'for the given amount' and adds no unit, currency, or range detail beyond the schema.

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

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

States a specific verb and resource ('Create an invoice to top up the credit balance') and even names the backing API operation (whmcs/create_addfunds), so the agent knows exactly what it does. It does not, however, differentiate itself from the many nearby billing siblings like apply_credit or generate_due_invoice, which is where confusion is most likely.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no reference to alternatives such as apply_credit or mass_pay that also affect a client's balance. 'MONEY: creates a real invoice for the given amount' is a warning about impact, not a usage rule for choosing this tool.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the write/non-destructive profile is covered structurally. The description adds genuinely new behavioral context beyond annotations: the key value is returned only once and must be saved. It does not mention permission requirements or whether the operation is reversible.

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

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

Two tight sentences with zero filler; the core action is front-loaded and the one critical caveat (save the key) follows immediately. Every clause earns its place.

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

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

With no output schema, the description usefully covers the one non-obvious return detail (one-time key value). It is missing only peripheral context such as authentication/permission prerequisites for a mutating tool, but overall it is sufficient to invoke correctly.

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

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

Schema description coverage is 100% (7 params, 4 required, enum documented), so the schema already carries parameter meaning and the baseline is 3. The description's scope statement loosely maps to the optional server_id but adds no syntax or formatting detail 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?

Names a specific verb+resource ('Create a new API key') and adds scope disambiguation ('for the account or a specific server') plus the underlying endpoint (api_keys/add). It does not explicitly contrast with siblings like update_api_key or get_api_key, so it falls short of the top band, but an agent knows exactly what this does.

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

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

There is no explicit when-to-use or when-not-to-use guidance relative to alternatives (update_api_key, list_api_keys, list_server_api_keys). The account-vs-server scope is implied but the agent must infer when this tool is the right choice versus other key-management tools.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the one-word 'DESTRUCTIVE' adds nothing beyond structured data. The description does supply workflow sequencing (step 2) and the upstream API op (eq/create_pxe), but omits what actually gets destroyed (existing OS/data), the confirm=true gate, and any prerequisite ordering — gaps that matter for an irreversible reinstall.

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

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

Two compact clauses with the workflow position front-loaded and the API endpoint in parentheses. No filler; every fragment carries information.

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

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

For a 9-parameter, 5-required destructive mutation with no output schema, the description is thin: it never states that create_reinstall_task must run first to yield reinstall_key, nor that confirm must be true. The annotations cover the safety profile, but the sequencing prerequisite an agent needs to call this correctly is only half-stated.

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% across all 9 parameters, so the schema already documents every field including confirm and reinstall_key semantics. The description adds no parameter-level detail, which is the correct baseline when the schema does the heavy lifting.

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

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

The description names a specific verb and resource ('create a PXE config for OS install') and pins its position in a workflow ('PXE reinstall step 2'), which separates it from siblings like clear_pxe_config and create_reinstall_task. It stops short of explicitly stating which sibling precedes it, so the distinction is implied rather than named.

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

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

'PXE reinstall step 2' implies this must follow an earlier step, which is useful ordering context, but no alternative tool is named and no when-not condition is given. An agent must infer that create_reinstall_task produces the reinstall_key this tool expects.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally; the description adds concrete value by specifying WHAT is destroyed ('wipes server disks') and by naming the returned reinstall_key. It still omits auth/permission requirements and whether the destruction is immediate or deferred to a later step, so it is strong but not exhaustive.

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

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

Three tight sentences, front-loaded with purpose then the return value then the danger warning. Every sentence carries information an agent needs; there is no filler.

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

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

With no output schema, the description correctly covers the return value (reinstall_key), the destructive consequence, and the link to check_task. It leaves the surrounding reinstall workflow (relationship to create_pxe_config / reinstall_server, and whether the wipe happens here or later) implicit, so an agent may need to infer sequencing.

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

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

Schema description coverage is 100% and both parameters (id, confirm) are documented in the schema, including that confirm must be true. The description adds nothing about parameter meaning or valid values, so this is the baseline case where the schema does all the work.

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

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

States a specific verb+resource ('create an OS reinstall master key (eq/reinstall)') and positions it as step 1 of a named flow, plus names the downstream sibling check_task that consumes its output. An agent can distinguish it from reinstall_server or create_pxe_config from the description alone.

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

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

Gives clear context for when to use it ('PXE reinstall step 1', output feeds check_task to track stages), which is real sequencing guidance. It stops short of naming an alternative or an exclusion (e.g. when to prefer reinstall_server or create_pxe_config instead), so it does not reach the explicit when/when-not bar.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that this escalates to on-site humans performing physical datacenter work, which is useful context beyond the annotations, but says nothing about approval flow, cost, expected turnaround, or what happens after submission.

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

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

Two tightly written sentences with zero filler; the core action is front-loaded and the usage restriction follows immediately. Nothing could be cut without losing information.

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

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

For a mutation tool with annotations covering safety, full schema coverage and no output schema, the description supplies purpose, usage restriction and the critical comment-detail expectation. It omits the request lifecycle (approval, scheduling, notification) that would make it fully self-contained.

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

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

Schema description coverage is 100% and all four parameters are documented in the schema, so the baseline is 3. The description's only param-level contribution is reinforcing that comment should be 'as much detail as possible', which largely restates the schema's 'Detailed description of the required work'.

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

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

States a specific verb+resource ('Create a Remote Hands request (rhr/add)') and immediately qualifies the resource ('on-site datacenter shift work that cannot be done remotely'), which distinguishes it from request_rh_* remote power/KVM helpers and from list_rhr_requests/add_rhr_comment/discard_rhr_request. An agent can identify the tool's niche without opening the schema.

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

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

Gives an explicit exclusion: 'Use only if the remote server management module is unavailable/not working.' That is a real when-not condition that steers the agent away from misuse. It does not, however, name the specific alternative sibling (e.g. reboot_server, request_rh_power_on) to use first, so routing is left partly to inference.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds the crucial behavioral fact that this is asynchronous and must be tracked via check_task — information annotations cannot convey. It stops short of describing timing, failure modes, or what happens to existing snapshots.

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

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

Three short sentences, front-loaded with the action, then the async nature, then the tracking tool. Nothing is padded and every clause carries information.

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

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

For a 3-parameter mutation tool with no output schema, the description supplies the essentials: what it does, that it is async, and how to poll it. Only minor gaps remain, such as state prerequisites or behavior on an already-snapshotted VM.

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 id, name, and confirm are all documented in the schema itself. The description adds no parameter-level meaning (e.g. naming rules or what confirm guards against), so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a virtual machine snapshot') and even names the underlying endpoint (vm/create_snapshot). This clearly distinguishes it from sibling snapshot tools like get_snapshots, remove_snapshot, and restore_snapshot.

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?

Tells the agent the operation is async and explicitly routes follow-up polling to check_task, which is real usage guidance. It does not, however, state any prerequisites or when-not-to-use conditions (e.g. snapshot limits, VM state requirements).

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

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

Annotations already declare destructiveHint=true, so the safety bar is lower. The description adds genuine context beyond the annotation by naming the consequence: apps using the key will lose access. It still doesn't state irreversibility or required authorization level.

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

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

Two short sentences, zero filler, with the destructive consequence front-loaded right after the action. Every clause earns its place.

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

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

Annotations carry the safety profile, the schema fully documents both parameters, and no output schema is needed for a deletion. The description adds the downstream consequence, making it nearly complete for a simple two-param destructive call.

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

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

Schema description coverage is 100%, so both id and confirm are already documented in the schema. The description adds no meaning beyond that (e.g. where to find the key id), so the baseline 3 applies.

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

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

States a specific verb (Delete) and resource (API key), plus the underlying endpoint api_keys/delete. It clearly separates itself from create_api_key/update_api_key/list_api_keys by naming the action, though it doesn't explicitly position itself against those siblings.

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

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

No explicit when-to-use or when-not-to guidance is given. The destructive warning implies caution, but it never says when deletion is appropriate versus rotating (update_api_key) or revoking via another path – usage is only implied by the name.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, covering the safety profile. The description adds nothing beyond the annotations – no auth requirements, no side-effect detail, no explanation that withdrawal cancels an existing request and requires confirmation.

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

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

A single front-loaded sentence with no wasted prose. The parenthetical API path is minor noise but harmless, and the core meaning is delivered immediately.

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

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

For a simple two-parameter mutation tool with full schema coverage and annotations, the description is minimally viable. It omits behavioral context (confirm requirement, effect on the underlying cancellation) but the structured fields carry most of the load.

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

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

Schema description coverage is 100%, so both parameters (id and confirm) are fully documented in the schema, justifying the baseline 3. The description adds no meaning beyond the schema, though none 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 states a specific verb ("withdraw") and resource ("service cancellation request"), which lets an agent distinguish it from request_cancellation and get_cancellation_requests. It does not explicitly name those siblings, but the verb+resource pair is unambiguous.

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

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

There is no guidance on when to use this tool versus request_cancellation, get_cancellation_requests, or discard_rhr_request, and no mention of prerequisites such as the confirm flag. The agent must infer usage from the name alone.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the trailing 'DESTRUCTIVE.' merely restates what structured data provides and adds no new context. The description says nothing about irreversibility, cascade effects on linked records, or permission requirements, so it contributes no value beyond the annotations.

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

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

Two short, front-loaded sentences with no filler. It is efficient, though arguably under-specified rather than truly concise, which keeps it off a 5.

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

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

For a two-parameter destructive tool with full schema coverage and annotations covering the safety profile, the description is minimally adequate. It omits what deletion does to dependent data and any alternative-path guidance, leaving real gaps for a destructive 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 description coverage is 100% with both contact_id and confirm fully documented, so the schema carries the parameter burden and baseline 3 applies. The description adds no format hints (e.g., where to obtain a contact ID) or semantics beyond what the schema states.

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

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

States a specific verb and resource ('Delete an additional account contact') and even cites the underlying API operation (whmcs/delete_contact). The word 'additional' usefully distinguishes this from deleting the primary client record, though it does not name sibling tools like add_contact or update_contact explicitly.

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

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

No guidance on when to use this versus update_contact, get_contacts, or other contact-management siblings, and no prerequisites or caveats are stated. The only implicit condition is the 'confirm' flag, which is already documented in the schema, not the description.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that: it discloses the exact blast radius (zone + domain + subdomains) and the pdns/edit authorization requirement, neither of which appears in annotations or 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?

Three tight sentences, front-loaded with the action and scope, then the destructive warning and permission requirement. Every clause earns its place, with no filler.

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

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

For a destructive mutation with no output schema, the description covers what an agent needs: scope of deletion, the destructive flag, and the required permission. Nothing material is left unstated.

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

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

Schema coverage is 100%, with domain_id, server_id, and confirm each documented in the schema. The description only adds 'by ID', which the schema already conveys. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb (Delete), resource (a domain), and precisely enumerates blast radius: the DNS zone, the domain itself, and all subdomains. This distinguishes it from siblings like delete_dns_subdomain and delete_dns_zone without needing to open schemas.

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?

Makes the destructive nature explicit and names the required permission (pdns/edit), which is genuine precondition guidance. It does not explicitly state when to choose this over delete_dns_subdomain or delete_dns_zone, though the enumerated scope implies the 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so 'DESTRUCTIVE' largely restates them. However, the description adds a concrete authorization requirement ('Requires pdns/edit permission'), which is real behavioral context not present in the annotations.

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

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

Two compact sentences with the destructive warning and permission requirement front-loaded; no filler or redundancy.

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

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

For a destructive mutation with no output schema, the description covers the safety profile and auth requirement. It stops short of stating irreversibility or behavior when the record does not exist, but annotations already carry the destructive signal.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter detail (zone, name, type, confirm) beyond what the schema already documents, so it earns no extra credit here.

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

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

States a specific verb (Delete) and resource (DNS record) scoped to a zone, and names the backing operation (pdns/delete_dns). The resource 'record' implicitly separates it from siblings like delete_dns_zone, delete_dns_domain, and delete_dns_subdomain, though no sibling is named explicitly.

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

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

Implies usage (removing a DNS record) and gives a prerequisite (pdns/edit permission), but offers no explicit when-to-use vs alternatives guidance among the many delete_dns_* and edit_dns_subdomain siblings.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so 'DESTRUCTIVE' is largely redundant. The genuinely additive content is the stated pdns/edit authorization requirement and the underlying API endpoint reference, which the annotations do not convey. It stops short of saying what else is affected (e.g. records under the subdomain) or that the deletion is irreversible.

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

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

Three tight fragments with zero filler, front-loaded with the action and resource. Both the DESTRUCTIVE warning and the permission requirement are placed where an agent will see them before parsing parameters.

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

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

For a 3-parameter destructive call with no output schema, the definition covers purpose, safety flag, required permission, and endpoint. It is nearly complete; only the blast radius of the deletion and any confirmation/lookup requirements are left unstated, which the confirm parameter partially mitigates.

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%: id, confirm and server_id are all documented in the schema, including the 'Must be true to run the operation' semantics for confirm. The description adds no parameter-level detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete a subdomain from the subdomains table') and even names the backing endpoint (pdns/delete_subdomain), so an agent can distinguish it from edit_dns_subdomain or add_dns_subdomain. It does not, however, explicitly contrast itself with the similarly named delete_dns_domain or delete_dns_zone 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 supplies the prerequisite 'Requires pdns/edit permission', which tells the agent under what conditions the call will succeed. It gives no when-to-use vs when-not guidance and does not route the agent to alternatives such as edit_dns_subdomain or delete_dns_domain.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds real value beyond them: it discloses that all records and metadata are cascaded away (not just the zone object) and that a specific permission scope (pdns/edit) is required. It stops short of stating irreversibility or confirmation 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?

Front-loaded with the action and its blast radius, followed by the risk flag and permission requirement in short fragments. Slightly telegraphic (three fragments rather than flowing prose) but nothing is wasted.

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

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

For a two-parameter destructive tool with no output schema and full annotation coverage, the description supplies the important extras: cascade scope, permission requirement, and the underlying endpoint. Only the absence of any return/error expectation or reversibility note keeps it from a 5.

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

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

Schema description coverage is 100%, so both 'zone' and 'confirm' are already documented in the schema, including the 'must be true' semantics of confirm. The description's 'by name' adds only marginal meaning over the schema, so the baseline 3 applies.

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

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

States a specific verb (Delete) and resource (DNS zone) with scope clarified: 'along with all records and metadata'. The named API call (pdns/delete_zone) further pins it down, and it is clearly distinguishable from siblings like delete_dns_domain, delete_dns_subdomain, and delete_dns_record.

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 signals the risk profile ('DESTRUCTIVE') and the required permission ('Requires pdns/edit permission'), which implies caution, but it never says when to prefer this over sibling deletes (e.g. domain vs zone) or any preconditions such as zone must be empty. Usage is implied rather than spelled out.

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

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

The 'DESTRUCTIVE' label duplicates destructiveHint=true, but the description adds genuinely new context beyond annotations: the authorization requirement and likely permission failure for clients. It stops short of describing irreversibility or effects on mounted ISOs.

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

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

Three short, front-loaded sentences with no padding; the destructive nature and auth caveat lead. The parenthetical endpoint reference is mildly redundant but compact.

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

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

For a destructive single-resource delete with annotations covering the safety profile and full schema documentation, the definition supplies the key extra detail (staff-only access). It omits whether deletion is reversible or how mounted ISOs are affected, a minor gap.

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

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

Schema coverage is 100%, so both id and confirm are fully documented in the schema. The description only echoes the 'by ID' concept and adds no syntax or format detail beyond what the schema already 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?

States a specific verb and resource ('Delete an ISO image by ID') and even names the underlying endpoint (iso/delete). The operation is unambiguous, though it doesn't explicitly contrast with nearby siblings like unmount_iso.

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 useful permission caveat ('available only to Hostkey staff — clients will likely get a permission error') that warns when the call will fail, but gives no positive when-to-use framing nor names an alternative operation.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so 'DESTRUCTIVE: the request will be cancelled' only restates structured data rather than adding context. Nothing is said about irreversibility, whether the rhr can be recreated, required permissions, or effects on related tasks.

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

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

Two short clauses, front-loaded with the action and immediately followed by the destructive warning. No filler or redundant explanation.

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

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

For a two-parameter destructive operation with full schema coverage and annotations covering the safety profile, plus no output schema to explain, the definition is close to sufficient. The remaining gap is the absence of any usage context distinguishing it from the other rhr and cancellation tools.

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

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

Schema description coverage is 100% for both parameters (id and confirm), so the schema already carries full parameter meaning. The description adds no syntax, sourcing, or format detail; baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb pair (cancel/close) and a specific resource (Remote Hands request), with the internal operation name 'rhr/discard' disambiguating it from create_rhr_request, list_rhr_requests, and add_rhr_comment. It does not explicitly name an alternative tool, but the resource+action combination is unambiguous within the sibling set.

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

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

No when-to-use guidance, no prerequisites beyond the schema-level confirm flag, and no routing to alternatives such as delete_cancellation_request or other rhr management tools. The agent must infer the context entirely.

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

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

readOnlyHint and openWorldHint already tell the agent this is a safe read that reaches outside. The description adds genuinely useful behavior: the API returns binary PDF but MCP returns JSON with base64 encoding, a non-obvious transport difference. However it omits error behavior (e.g., what happens for an invalid or unauthorized invoice_id).

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

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

Two dense sentences that front-load the action and include the endpoint and encoding detail. Efficient, though the parenthetical endpoint reference is slightly technical clutter.

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?

Complete for a single-param read tool: it says what is produced (PDF), how it arrives (base64 in JSON), and what to do with it. No output schema exists, and the description compensates by describing the return shape. Minor gap on failure modes.

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

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

Schema coverage is 100% and the single parameter has a clear description ('Invoice number'). The description adds no parameter-level semantics beyond the schema, so baseline 3 applies.

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

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

States a specific verb (download) and resource (invoice) with the output format (PDF). The sibling list contains get_invoice, get_invoices, and get_server_invoices, and this description makes clear this is the download-PDF variant rather than metadata retrieval.

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

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

The description implies use when a PDF is needed, but never explicitly contrasts with get_invoice/get_invoices to say when to prefer this over those. Usage context is inferable from the purpose, not stated.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the description's 'DESTRUCTIVE' label largely repeats structured data. It does add that this is an internal/ops action, which is meaningful context, but says nothing about reversibility, permission requirements, or the confirm guard.

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

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

Two compact clauses, front-loaded with the verb and resource. The endpoint parenthetical is a small but useful detail; the 'DESTRUCTIVE' restatement is mild redundancy given the annotations, but the text wastes little.

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

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

For a destructive mutation with no output schema, the description covers the what but not the how-it-interacts-with-siblings picture, and it never mentions the required confirm flag that the schema mandates. Annotations carry the safety profile, so this is minimally adequate rather than 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%, covering id, ip, and the required confirm flag, so the baseline is 3. The description adds no parameter guidance at all — notably it never explains that id or ip must be supplied to identify the record.

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

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

States a specific verb and resource: delete a NAT record, and even names the internal endpoint (nat/drop_nat). It does not, however, distinguish itself from closely related siblings such as remove_static_nat or clear_static_nat, so an agent could still hesitate between them.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the obvious alternatives (clear_static_nat, remove_static_nat). The phrase 'internal/ops action' hints at restricted usage but never states the condition that selects this tool.

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

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

Annotations already declare this as a non-read-only, non-destructive, open-world mutation, so the safety profile is covered. The description adds the auth requirement (pdns/edit), but says nothing about what is mutated, reversibility, or side effects beyond that.

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

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

Two compact fragments with no filler; the operation is front-loaded ahead of the permission note. Efficient, though the parenthetical endpoint reference is redundant with the tool name.

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

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

With 100% schema coverage and annotations carrying the safety profile, the essentials are present. It remains thin on the actual mutation surface — it never indicates which subdomain fields can be changed — leaving the agent to infer the edit scope.

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

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

Schema description coverage is 100%, with id, confirm, and server_id all documented in the schema, so the baseline is 3. The description adds no syntax or constraint detail beyond what the schema already states.

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

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

States a specific verb (update) and resource (subdomain), which cleanly separates it from the add_/delete_/list_ DNS subdomain siblings. It does not clarify which attributes of the subdomain are editable.

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 real prerequisite ('Requires pdns/edit permission'), which is genuine usage context. However, it gives no when-to-use vs alternatives guidance and no exclusions relative to add_dns_subdomain or delete_dns_subdomain.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation nature is partly covered. The description adds nothing beyond that: it omits the 'confirm must be true' guard, does not clarify idempotency (whether repeated calls generate duplicate invoices), and gives no billing side-effect context, which matters for an invoice-generating 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?

A single front-loaded sentence with no filler, which is efficient. It is arguably under-specified rather than padded, but as pure structure it is tight and wastes no 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 billing mutation tool with no output schema, the description should convey what the call produces and its consequences. It does not explain the resulting invoice, billing period, or side effects, leaving the agent without enough context to invoke it confidently.

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%, with both 'id' (Server ID) and 'confirm' documented in the schema, so the baseline of 3 applies. The description adds no extra meaning about the parameters beyond what the schema already states.

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

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

The description gives a verb+resource ('Create the next invoice for a server'), which is better than a tautology, but 'next invoice' is ambiguous about billing period and cycle, and it is not distinguished from the closely related sibling create_addfunds_invoice. The parenthetical '(whmcs/generate_due_invoice)' is just an internal identifier and adds no disambiguating value.

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

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

There is no guidance on when to use this tool versus alternatives such as create_addfunds_invoice, get_invoices, or mass_pay, nor any when-not or prerequisite conditions. The agent is left to infer the intended scenario entirely.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true), so the description only needs to add context. It does disclose the concrete returned fields (available calls, account type/role, linked server IDs), which helps the agent judge whether the call is worth making. It stops short of stating auth requirements or whether the token itself is echoed back, so not a full 5.

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

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

Two compact sentences, front-loaded with the resource and its contents, then the use case. No filler or restating of the name.

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

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

With no parameters, a read-only annotation, and no output schema, the description carries the burden of describing return content and does so with a concrete field list. Minor gaps (auth semantics, whether token value is included) keep it from being fully complete, but it is sufficient to call the tool correctly.

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

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

Zero parameters with 100% schema coverage, so there is nothing for the description to clarify; the baseline for a parameterless tool applies. Little to add or subtract here.

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

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

States a specific verb+resource ('get account info') and enumerates the payload ('available calls, account type and role, linked server IDs'), which distinguishes it from credential-management siblings like list_api_keys or get_billing_client. An agent can tell what this returns without opening the schema.

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

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

The closing sentence 'Useful to verify the connection' implies a usage context but names no alternatives and no when-not conditions. Nothing tells the agent whether to prefer this over get_billing_client or list_api_keys for account-level questions, so guidance is only implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only the endpoint path, disclosing nothing about auth/permission requirements, behavior on an invalid or foreign key ID, or sensitive-data characteristics of the returned key material.

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

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

One short, front-loaded sentence with no filler. It is efficiently sized for a trivial getter, though the parenthetical endpoint reference is of marginal value to an agent.

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

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

For a simple read-only getter with a fully documented single parameter and annotations covering safety, the minimum is met. However, with no output schema, the description could have said what the response contains (key token, permissions, creation date) and it does not.

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

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

There is a single parameter with 100% schema description coverage ('Key ID from list_api_keys'), so the schema already carries the semantic load. The description adds no format, range, or sourcing detail beyond what the schema states, making the baseline 3 appropriate.

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

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

States a specific resource ('a specific API key') and implies a retrieve verb via 'Details for', plus the underlying endpoint (api_keys/view). It is clear what the tool returns conceptually, but it never names the sibling it differs from (list_api_keys, get_api_key_history) to help an agent disambiguate.

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

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

Usage is only implied: fetch details for one key given an ID. The schema's 'Key ID from list_api_keys' hints at the workflow (list first, then get), but the description itself gives no when-to-use, prerequisites, or alternatives versus get_api_key_history/list_api_keys.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is clear. The description adds only the endpoint and the period-scoping concept, but does not describe return format, pagination, or rate limits. With annotations covering the safety profile, this is minimally acceptable additional 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?

A single, front-loaded sentence with no wasted words. It is appropriately sized for a simple read-only 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 tool has no output schema, so the description could usefully explain what 'usage history' returns (e.g., call counts, bandwidth, time-series data). It also omits any usage guidance. Given the simple read-only nature and complete schema, the description is adequate for invocation but leaves notable gaps for result interpretation and tool selection.

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

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

Schema description coverage is 100%, so all three parameters (id, period_from, period_to) are already documented in the schema. The description's 'for a period' phrase adds marginal contextual meaning but no syntax or format details 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 states a clear resource ('API key usage history') and scope ('for a period'), and the parenthetical endpoint reinforces the intent. It distinguishes itself from get_api_key and list_api_keys by focusing on historical usage, but does not explicitly name or contrast with those siblings.

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

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

The description offers no guidance on when to use this tool versus alternatives like get_api_key or list_api_keys. There is no mention of prerequisites, context, or exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the shape of the payload (contacts, currency, account status) but says nothing about auth requirements, rate limits, or 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?

A single front-loaded sentence with no padding; the parenthetical API endpoint is compact. Slightly telegraphic, but nothing is wasted.

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

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

With no output schema, the description compensates by listing the main returned fields, and with no parameters and read-only annotations there is little else an agent needs. Missing only guidance on how it relates to sibling billing/contact tools.

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

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

The tool takes zero parameters, so there is no parameter semantics for the description to explain; the baseline of 4 applies.

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

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

States a specific verb+resource ('Client data from billing') and enumerates the returned fields (contacts, currency, account status), which is more than a tautology. It does not explicitly distinguish itself from near-neighbors like get_contacts or get_server_billing_data, so it stops short of a 5.

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

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

There is no guidance on when to call this versus get_contacts, get_account_info, or get_server_billing_data. The reader must infer usage purely from the field list.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the 'active' scoping nuance (implying non-active/cancelled requests are excluded), but says nothing about pagination or result ordering.

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

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

A single tight sentence with the resource front-loaded. The trailing API endpoint path '(whmcs/get_cancellation_requests)' is marginally useful for traceability but slightly redundant.

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

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

For a simple read-only listing tool with annotations covering safety and full schema coverage, this is minimally adequate. It omits when-to-use routing and any return-shape hints, but nothing critical is missing for correct 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?

Only one optional parameter with 100% schema coverage ('Server ID (filter)'), so the schema already documents it fully. The description adds no additional meaning about how the id filter behaves (e.g., whether omitting it returns all requests).

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

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

States a specific verb ('List') and resource ('active service cancellation requests'), making the read intent unmistakable. The 'active' qualifier scopes it somewhat, though it doesn't explicitly contrast with siblings like delete_cancellation_request or request_cancellation.

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

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

No guidance on when to use this versus request_cancellation (to create one) or delete_cancellation_request (to remove one). The agent must infer from names alone that this is the read-only listing counterpart.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only the internal endpoint path (whmcs/get_contacts), with nothing about return contents, pagination, or whether the list is scoped to the authenticated account.

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

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

A single front-loaded sentence with no padding. The parenthetical API path is arguably noise for an agent, but it costs little and the whole description is one line.

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

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

For a zero-parameter, annotated read tool this is close to sufficient, but with no output schema the description could have named the contact fields returned (name, email, etc.) or clarified scope. Adequate but leaves a real gap.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the schema is trivially complete.

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

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

The description names a specific resource (account contacts) and implies the list/read verb, which cleanly separates it from the write siblings add_contact, update_contact, and delete_contact. The qualifier 'additional' hints these are secondary contacts rather than the primary billing client, though it is not spelled out.

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

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

There is no statement of when to use this tool versus alternatives such as get_billing_client or the contact mutation tools. No prerequisites, auth requirements, or filtering context are given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only the upstream endpoint hint (whmcs/getcredits); it says nothing about time range, pagination, or whether the id is a client or server identifier, which is the main behavioral ambiguity here.

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

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

A single front-loaded clause with the endpoint reference tucked in parentheses; no wasted sentences. It is efficient, though the endpoint detail is of marginal value to an agent.

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

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

For a simple one-parameter read tool with no output schema and read-only annotations, this is minimally adequate, but it omits the return shape (a list of movements) and any temporal/pagination behavior, leaving the agent to discover those at call time.

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

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

One parameter with 100% schema description coverage, so the schema already documents 'id' as Server ID. The description adds no syntax or interpretation beyond that, which is the expected baseline when the schema does the work.

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

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

The description names a specific resource (credit balance movement) and enumerates the two kinds of entries it reports (additions and deductions), which is more than a restatement of the name. It does not, however, differentiate itself from adjacent billing siblings such as get_transactions, apply_credit, or get_server_billing_data.

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

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

There is no statement of when to call this versus an alternative, no prerequisite (e.g. which id is expected), and no scope caveat. The agent must infer usage purely from the name.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful context by naming the authoritative backend (pdns/view_zone), which signals live rather than cached data, but it says nothing about pagination, error behavior, or result size for large zones.

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

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

A single compact sentence with the resource front-loaded and no filler. The parenthetical backend reference earns its place as provenance, though the colon fragment is slightly clipped rather than a clean declarative statement.

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

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

For a one-parameter read tool with no output schema and annotations covering safety, this is nearly complete: it states the input subject, the source system, and the shape of the returned data. It stops just short of the profile of a 5 because nothing addresses large-zone responses or failures.

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

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

Schema description coverage is 100% and the single 'zone' parameter is documented with an example (example.com), so the schema does the heavy lifting. The description adds no format constraints or naming rules beyond that, which is the expected 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 names the resource precisely (DNS zone contents) and enumerates what is returned (A, AAAA, CNAME, MX, TXT, etc.), which distinguishes it from list_dns_zones, add_dns_zone, and delete_dns_zone. Its only weakness is the noun-phrase framing – there is no explicit retrieval verb, though the intent is unambiguous.

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

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

Usage is implied by scope: fetch the record set for one zone, given a zone name. There is no explicit when-to-use vs. when-not or reference to siblings such as list_dns_zones, so the agent must infer the selection criteria itself.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. Beyond that, the description only adds the vague qualifier 'for payment', which is ambiguous rather than informative. It does not disclose what the response contains, whether unpaid invoices differ from paid ones, or any auth/scoping requirements.

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

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

A single short sentence with no padding, and the resource ('a specific invoice') appears early. It is well-sized for the tool, though the parenthetical API-method reference is marginally useful filler.

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

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

With no output schema and no real behavioral detail, the description leaves the agent guessing what 'data' is returned and how this differs from the large family of related billing/read tools. For a simple one-parameter read this is not catastrophic, but it under-serves a namespace crowded with near-neighbors.

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

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

Schema description coverage is 100% for the single required parameter (invoice_id, documented as 'Invoice number'), so the schema fully carries parameter meaning. The description adds nothing about the parameter's format or where the ID comes from, which is the baseline case for high-coverage schemas.

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

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

It names the resource (a specific invoice) and implies retrieval via 'Data for...', with the underlying API method 'whmcs/get_invoice' as a parenthetical. However, the verb is nominal rather than action-oriented, and with siblings like get_invoices, get_server_invoices, and download_invoice present, it does nothing to distinguish itself from those alternatives.

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

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

There is no statement of when to use this tool versus get_invoices (list all) or download_invoice (retrieve the document). The phrase 'for payment' hints at a billing context but never says whether this is a pre-payment lookup, a verification step, or what triggers its use. The agent must infer everything from the name.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds no behavioral context beyond that – no pagination behavior, no result-size expectations, and no auth prerequisites for a list tool that could return many invoices.

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

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

A single front-loaded sentence with no padding; the scope ('full list of account invoices') comes before the parenthetical endpoint reference, which is a minor but essentially harmless addition. Efficient and unambiguous.

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

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

For a parameterless list tool with annotations covering safety and no output schema, the description is close to adequate, but it omits any hint about result volume or pagination, which matters for a 'full list of invoices' call. Adequate but with a clear remaining gap.

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

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

The tool takes zero parameters (schema coverage 100% trivially), so per the rubric a baseline of 4 applies. There is nothing parameter-related for the description to compensate for.

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

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

States a clear verb and resource ('get_invoices') and scopes it as the full list of account invoices, which implicitly distinguishes it from get_invoice (single) and get_server_invoices. It does not explicitly name or differentiate against those siblings, but the 'full list' phrasing makes the scope legible.

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

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

There is no guidance on when to use this tool versus get_invoice, get_server_invoices, or download_invoice. It simply asserts what it returns, leaving the agent to infer selection criteria from sibling names alone.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and outside-the-sandbox behaviour are covered. The description adds nothing beyond a restatement of the resource plus the raw API path '(ip/get_ip)', giving no insight into what fields are returned or whether the IP must be owned by the account.

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

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

A single short line that is front-loaded with the resource and the lookup key, with no padding. The parenthetical API path is mildly extraneous but not harmful, and the whole thing is arguably under-specified rather than over-long.

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

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

For a one-parameter read tool with no output schema and annotations covering the safety profile, the minimum is met, but the agent is not told what the 'information' comprises (name, MAC, addresses, PTR) or any preconditions on the IP. Adequate but with clear 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?

Schema description coverage is 100% for the single 'ip' parameter, so the baseline is 3. The phrase 'by IP address' merely echoes the schema and adds no format or validation meaning.

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

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

States a specific resource ('network interface information') and the keying parameter ('by IP address'), so the agent knows this is a read lookup keyed on an IP. It is a noun phrase rather than a verb+resource sentence, and it does not distinguish itself from nearby siblings like get_network_status, get_port_graphs, or get_ptr_record.

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

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

There is no when-to-use guidance at all. With siblings such as get_network_status and get_port_graphs operating in the same networking area, the description never says which situation selects this tool, nor does it name an alternative.

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

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

With readOnlyHint and openWorldHint annotations covering safety, the description adds value by enumerating the fields returned and noting a behavioral quirk: another NIC may lack an upstream_id. It does not discuss error handling, rate limits, or permissions, but the added return-value context is substantial beyond the annotations.

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

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

The description is two sentences with zero waste: the first front-loads the purpose and returned fields, and the second provides a specific, actionable usage note. 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?

Given the read-only annotations and full schema coverage, the description is nearly complete for this tool. It lists return fields, which compensates for the lack of an output schema, though it could mention error behavior or upstream_id implications more explicitly. Still, it provides all essential context for an agent to call the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's note about `port` limiting the query to one interface (useful when another NIC has no upstream_id) largely repeats information already present in the schema's `port` description, adding no new semantic detail.

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

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

The description clearly states it retrieves server network interface status and lists the specific fields returned (port, switch, VLAN, speed, MAC, link status). It does not explicitly differentiate from any sibling tool, but no sibling appears to perform a similar network-status retrieval, so an agent can still easily identify its purpose.

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 offers a usage hint for the optional `port` parameter ('useful when another NIC has no upstream_id'), which implies when to use that parameter. However, it does not state when to use this tool versus alternatives (e.g., other network-related tools like `get_port_graphs` or `get_server`), leaving overall usage guidance implicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered, but the description adds nothing beyond the basic purpose: no indication of what the result contains (gateway list, statuses, availability), no auth or scoping notes. The bar is lower with annotations present, yet no extra behavioral context is supplied.

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

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

A single short sentence plus an endpoint reference; nothing is wasted and it is front-loaded. It is efficient, though the endpoint token adds little value to an agent selecting the tool.

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

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

For a single-parameter read tool with full schema coverage and safety annotations, the description is minimally adequate. It omits the action verb and any hint of return shape, which matters since no output schema exists.

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

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

Only one parameter exists and schema description coverage is 100% ('Invoice number'), so the schema carries the semantics. The description's phrase 'for a specific invoice' merely restates the parameter's role and adds no format or usage detail.

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

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

The description names the resource ('Payment methods for a specific invoice') but uses a noun phrase with no verb, leaving it ambiguous whether it lists payment gateways available to pay the invoice or methods already used. It also does not distinguish this from nearby billing siblings such as get_invoice or get_transactions. Understandable, but vaguer than a clean verb+resource statement.

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

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

There is no when-to-use guidance, no mention of prerequisites (e.g., the invoice must exist or be unpaid), and no reference to any alternative tool. The agent is left to infer the context entirely.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds only a cryptic source reference ('net/show_cacti') and the period granularity, but does not disclose return format, pagination, or any other behavioral trait beyond what annotations imply.

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

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

The description is a single, front-loaded sentence with no wasted words. It packs purpose, source hint, and period options efficiently.

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-only tool with full schema coverage and safety annotations, the description covers the core purpose. However, with no output schema, it could say more about what the returned graphs actually contain or how to interpret them.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description repeats the day/month/year options without adding syntax or meaning beyond the schema's 'graph' description.

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

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

The description states the resource clearly: port utilization graphs for a time period, with day/month/year options. It does not explicitly differentiate from sibling tools, but the resource is specific enough for an agent to identify the tool's function.

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

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

The description gives no guidance on when to use this tool versus alternatives such as get_network_status or get_power_status. It merely enumerates the period options, leaving usage context entirely implicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safe-read profile is covered. The description adds a small amount of behavioral value by naming the returned states (on/off), but says nothing about latency, freshness, or error behavior when the server is unreachable.

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

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

A single compact sentence with the resource and result domain front-loaded and no filler. It is slightly telegraphic and lacks a closing period, but every word 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?

For a one-parameter, annotation-covered read tool with no output schema, the description covers the essential purpose and the shape of the answer. A brief note on failure cases (unreachable/unknown server) would make it fully complete, but nothing critical is missing.

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

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

Schema description coverage is 100% for the single 'id' parameter ('Server ID'), so the schema already carries parameter meaning. The description adds no further qualifier such as whether the ID is a numeric server identifier versus a hostname, so the baseline 3 applies.

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

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

States a specific verb (get) and resource (server power status), plus the returned value domain (on/off), so the agent knows exactly what it retrieves. It does not, however, distinguish itself from lookalike siblings such as get_server or get_network_status, which it could have done in a phrase.

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

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

There is no statement of when to use this versus alternatives. Siblings like power_on, power_off, request_rh_power_on, and request_rh_power_off are close neighbors, and the description gives no cue about which to pick or any prerequisite (e.g., checking status before a power action).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds an auth caveat that annotations do not express, which is genuinely useful, but the hedge 'may require auth depending on permissions' is too vague to be actionable (which permission? what happens if unauthorized?).

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

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

Very short and front-loaded: the resource and scope come first, with a secondary note on auth. The endpoint breadcrumb '(presets/show)' is slightly gratuitous but harmless. Nothing is padded.

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

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

For a trivial one-optional-param read tool, the definition is adequate but thin. With no output schema, the agent gets no hint of what 'details' comprise (settings fields? pricing? configuration?), and the auth condition is left unresolved.

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

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

Schema coverage is 100%, and the single parameter's description ('Preset ID; omit for full list') already conveys the optionality semantics. The description's 'one preset or all presets' merely restates that, adding no format or constraint detail.

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

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

States the resource and scope precisely: details for a single preset or the full collection, with the underlying endpoint (presets/show) named. However, it never distinguishes itself from siblings like list_presets or search_presets, and 'or all presets' overlaps semantically with list_presets, leaving the agent to infer the boundary.

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

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

The only guidance is the weak conditional 'may require auth depending on permissions,' which gives no actionable rule. Nothing tells the agent when to pick this over list_presets, search_presets, or get_preset_pricing, despite four closely related preset siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety profile is covered. The description adds one useful behavioral fact not in annotations: 'No token required,' which is relevant for unauthenticated access. It does not, however, describe caching, currency defaults beyond the schema, or response shape.

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

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

A single compact sentence with the core purpose front-loaded, plus the endpoint hint and auth note. No wasted words, though it is arguably too terse to be maximally useful.

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-optional-parameter read-only tool with 100% schema coverage and clear annotations, the description covers purpose and the notable auth exemption. Since no output schema exists, return-value detail is not strictly required, though a hint about the pricing structure would help.

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

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

Schema description coverage is 100%, so the currencies parameter is already fully documented with format ('EUR,USD') and default ('EUR'). The description's 'in given currencies' only restates what the schema provides, so the baseline 3 applies.

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

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

Clear verb+resource combination: retrieves pricing for presets in specified currencies. Distinguishes itself as a pricing lookup rather than a preset listing, but does not explicitly differentiate from siblings like get_preset or list_presets, which could also be candidates for preset-related queries.

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

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

No guidance on when to use this tool versus alternatives such as get_preset (preset details) or list_presets (available presets). The only contextual note is 'No token required,' which covers auth rather than tool selection.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only that the value returned is the 'current' reverse-DNS record, with no note on whether a record may be absent or how the lookup fails.

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

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

A single sentence with zero padding, front-loading the resource and its reverse-DNS nature. It is arguably too terse to be maximally useful, but nothing is wasted.

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

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

There is no output schema, so the description should ideally hint at the return shape (e.g., a hostname string) or a not-found case; it only says 'Current PTR record'. For a simple two-parameter read covered by annotations, this is adequate but leaves a small gap.

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

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

Schema description coverage is 100% (both 'id' = Server ID and 'ip' = IP address are documented in the schema), so the baseline is 3. The description adds no format or syntax detail beyond the schema.

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

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

States a specific verb+resource: reads the 'Current PTR record (reverse DNS)' for an IP, and the '(ip/get_ptr)' note pins the underlying endpoint. It does not explicitly distinguish itself from the sibling update_ptr_record, which would be the obvious confusion point, so it falls short of a 5.

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

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

The description says what the tool returns but never states when to use it versus alternatives such as update_ptr_record or get_ip_info, nor any prerequisites. An agent must infer from the name that this is read-only retrieval.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description usefully enumerates the data domains returned (configuration, network, status, location), but adds nothing about permissions, freshness, or response shape.

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

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

A single front-loaded sentence with no filler. The parenthetical '(eq/show)' is opaque API jargon that costs a little clarity without adding value.

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

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

With no output schema, the description carries the burden of telling the agent what comes back, and it does list the major content areas. It stops short of anything on pagination, error cases, or the meaning of the '(eq/show)' token.

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

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

Schema description coverage is 100% for the single 'id' parameter, so the schema already documents it as the InvAPI server ID. The description's 'by ID' reinforces but does not extend that meaning, which is the baseline-3 case.

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

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

States a specific verb and resource ('Full server details by ID') and enumerates the returned content areas (configuration, network, status, location). It is clearly the single-server fetch, implicitly distinct from the plural sibling get_servers, though no sibling is named explicitly.

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

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

The phrase 'by ID' implies the precondition (you must already know the server ID), but there is no explicit when-to-use guidance or routing against alternatives like get_servers, get_power_status, or get_server_sensors.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds nothing beyond that – it doesn't say what billing data is returned (rates, renewal, payment status), whether it is cached/live, or whether it requires a billing-scoped API key.

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

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

A single, tight sentence with no filler; the resource is front-loaded. The parenthetical backend path is harmless metadata.

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

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

With no output schema, the description carries the burden of explaining what is returned, and it does not – 'billing information' is left undefined. For a billing-domain getter in a large sibling set, this leaves the agent unable to predict the response.

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

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

Schema description coverage is 100% and there is a single required integer 'id' fully documented in the schema, so baseline 3 applies. The description contributes no additional parameter meaning.

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

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

Names a resource (billing information for a server rental) and implies a getter via the tool name, but the phrase 'billing information' is vague about what fields are involved. It does not distinguish itself from close siblings like get_server_invoices or get_billing_client, which an agent must choose between.

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

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

There is no when-to-use guidance, no alternative named, and no prerequisite stated. With many billing-adjacent siblings (get_invoices, get_server_invoices, get_transactions, get_billing_client), the absence of routing guidance is a real gap.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds only the upstream API mapping (whmcs/get_related_invoices), which does not disclose pagination, ordering, result shape, or what counts as 'related'. Nothing behavioral beyond the annotations.

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

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

A single economical sentence with no waste, but it is arguably too terse: one short clause plus a parenthetical endpoint reference for a tool that could carry more routing detail.

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

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

For a one-parameter read tool with no output schema this is minimally viable, but it omits what is returned (count, fields, pagination) and how it differs from get_invoices/get_invoice in a large billing sibling group.

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

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

Schema coverage is 100% and the single parameter 'id' is documented as 'Server ID'. The description's 'specific server' phrasing reinforces this but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific resource (invoices) scoped to a specific server, which distinguishes it from the sibling get_invoices (all invoices) and get_invoice (single invoice). It lacks an explicit verb but the noun phrase plus scope is unambiguous enough to route correctly.

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

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

No guidance on when to use this versus get_invoices or get_invoice, nor any prerequisite or context. The scoping phrase 'related to a specific server' hints at the use case but leaves the agent to infer the alternative's condition.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered, but the description adds a real behavioral trait not present in structured data: an automatic inventory refresh (eq/update_servers) triggered before the first call. It also discloses that results are summary-level, which sets expectations for downstream calls. It does not mention pagination or result caps.

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

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

Three short sentences, front-loaded with identity and scope, then the side effect, then the routing hint. Nothing is padding and each sentence changes agent behavior.

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

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

With no output schema, the description correctly carries the burden of saying what comes back ('server IDs and brief data') and points to the richer sibling for full detail. The pre-call refresh side effect is also covered. Pagination/volume limits are the only notable omission.

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

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

Schema description coverage is 100% and every parameter (ip, mac, group, status, location) already documents its semantics, including the accepted comma-separated codes. The description only says 'with filters' and adds no syntax, precedence, or combination rules beyond the schema, so the baseline 3 applies.

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

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

The description names a specific verb and resource ('List Hostkey account servers') plus the filter scope, and explicitly separates itself from the sibling get_server by scoping its return to IDs and brief data. An agent can pick between get_servers and get_server without opening either schema.

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

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

It gives a concrete alternative and the condition that selects it ('use get_server for the full card'), which is exactly the routing decision an agent faces here. It stops short of stating when to use search_servers_by_tag or the stock-server listers, so it isn't fully exhaustive.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered structurally. The description adds the bare-metal eligibility constraint and the sensor categories, but says nothing about permissions, rate limits, or what a caller gets when sensors are unavailable on the target host.

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

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

Two short clauses, no filler, and the content enumeration is front-loaded ahead of the scoping caveat. Nothing could be trimmed without losing information.

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

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

For a single-parameter read tool with annotation coverage and no output schema, the description supplies the essential distinction (bare-metal) that an agent needs to call it correctly. It stops just short of clarifying behavior on hosts that lack exposed sensors.

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

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

Only one parameter (id) exists and the schema documents it fully (100% coverage), so the schema carries the burden. The description adds no format or constraint detail about the id beyond what the schema states, making the baseline 3 appropriate.

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

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

States a specific resource (hardware sensor readings) and enumerates the content types (temperatures, voltages, fans), which cleanly distinguishes it from neighbors like get_power_status and get_network_status. It lacks an explicit verb such as 'retrieve', but the intent is unambiguous.

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

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

'Bare-metal only' is an effective when-not condition that rules out virtual servers, so the scope is implied. However, it never names an alternative tool or states when a caller would prefer this over get_server or get_power_status, leaving routing to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful piece of context — that tags hold arbitrary key-value pairs — but says nothing about ordering, pagination, or the shape of the returned collection.

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

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

Two short sentences with no filler, and the primary purpose is front-loaded ahead of the elaboration. The endpoint parenthetical is marginally useful but slightly technical for a prose description.

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

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

No output schema exists, so the description should describe what comes back; 'arbitrary key-value pairs' partially covers that but leaves the return structure and empty-state behavior unspecified. Adequate but with visible gaps for a retrieval tool.

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

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

Schema coverage is 100% with a single documented 'id' (Server ID) parameter, so the schema carries the meaning. The description never references the required server id, adding no semantics beyond the schema — baseline 3 applies.

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

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

States a specific resource ('server tags') and scope ('all'), and the parenthetical endpoint ('tags/list') anchors the operation. It is distinguishable from siblings like search_servers_by_tag or get_server, though it never explicitly names them, so it lands just short of a 5.

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

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

There is no statement of when to call this versus alternatives such as search_servers_by_tag (which searches servers by tag) or get_server. The only contextual cue is the raw endpoint name, which assumes the reader already knows the API surface.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds essentially nothing behavioral beyond that: no pagination, ordering, volume, or permission context, and no statement of what happens for a VM with no snapshots.

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

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

A single tight sentence with the purpose front-loaded and the return fields listed compactly. It is efficient, though arguably under-specified rather than deliberately minimal.

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

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

With no output schema, the description usefully enumerates the returned fields (name, snapshot_id, date), which is the main thing an agent needs. However it omits pagination, ordering, empty-result behavior, and any routing to the sibling snapshot operations.

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

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

Schema coverage is 100% and the single parameter 'id' is documented in the schema as 'Virtual machine ID'. The description adds only the endpoint mapping, not format, range, or error semantics, so the schema does the heavy lifting.

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