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

With annotations already declaring destructiveHint=true and idempotentHint=true, the description adds valuable context beyond structured fields: it warns that mismatched DS records can prevent validating resolvers from resolving the domain, and states the API-key auth requirement. It does not describe what exactly gets destroyed or the queued operation's return behavior, but it meaningfully supplements 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 definition is three sentences and front-loads the core action. The warning and auth sentences are informative and earn their place, though the middle sentence is more directive than descriptive and could be tightened.

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 queued mutation tool with no output schema and full annotation coverage, the description supplies the key operational context: it is a write operation on the parent zone, requires domains:manage with an API key, and has a resolution-breaking failure mode if DS records do not match the child DNSKEY. Return-value behavior is not needed because 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?

Schema description coverage is 100%, so the schema already documents all three parameters with formats and constraints. The description adds no parameter-level syntax or semantics beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: 'Queue adding public DNSSEC DS records at the parent zone for an owned domain.' It is clear what the tool does, but it does not explicitly differentiate from close siblings such as delete_domain_parent_ds or set_dnssec.

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

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

It provides clear context and a prerequisite: 'Confirm the records match the child zone's DNSKEY' and 'Requires domains:manage when using an API key.' It does not name explicit alternatives or when-not conditions, but the conditions for safe use are stated.

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

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

Goes well beyond the annotations (which only cover read-only/idempotent/destructive/open-world flags) by disclosing permission scopes, SMTP port refusal, ownership/feature/2FA enforcement, the meaning of an accepted-but-pending operation, the in_progress/reason_kind/reason_code polling contract, and the no-auto-retry recovery rule.

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 action and constraints, and nearly every sentence carries actionable information. The polling paragraph is dense and long relative to the rest, but it is a deliberate operational contract rather than filler.

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

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

With no output schema, the description carries the return/outcome burden and does so: it explains that acceptance means pending, how to poll via in_progress and next_check_seconds, how to interpret reason_code/reason_kind, and how to recover from transport uncertainty. Complete for this mutation-plus-async tool.

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

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

Schema description coverage is only 40%, so the description must compensate. It adds real meaning for idempotencyKey (preserve key and unchanged body) and for port (SMTP refusal) and protocol capabilities, but says nothing about members, weight, or address shape, leaving part of the parameter set undocumented in both places.

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 listener and optional initial members'), which is clearer than the bare title. It does not explicitly contrast itself with the sibling add_network_load_balancer_member, which also touches members, so sibling differentiation is only implicit.

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

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

Gives explicit prerequisites: read capabilities and owned resource state first, obtain approval for the exact change, and note that reads need networking:read while changes need networking:manage. No alternative tool is named, but the when-to-use conditions are concrete.

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?

Annotation hints cover the safety profile (readOnly=false, idempotent=true, destructive=false, openWorld=true), and the description goes well beyond them: required scopes (networking:read/manage, not granted by full/read defaults), ownership and 2FA lock enforcement, the fact that acceptance means pending rather than connectivity, the polling contract (in_progress, next_check_seconds, reason_kind waiting vs failure), and explicit idempotency recovery rules (reuse the original key and unchanged request, never auto-retry). This is exactly the behavioral context an agent needs for a risky async 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?

Purpose and prerequisites are front-loaded and there is essentially no filler; every clause maps to a real constraint (permissions, approval, async semantics, idempotency recovery). It reads as one very dense block, and fragments like 'Preserve reason_code.' hurt scannability, keeping it from 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 5-parameter async mutation with no output schema, the description covers everything the agent needs: auth scope, approval workflow, non-destructive-but-pending semantics, how to interpret operation state, and how to behave under transport uncertainty. Nothing material is left to inference.

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 60%, so the schema carries most parameter documentation. The description adds meaning only for idempotencyKey (preserve the original key and unchanged body on uncertain recovery) and obliquely for address ('private server address', validated for network membership). It says nothing about how listener_id and load_balancer_id relate, so it does not compensate for the coverage gap.

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

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

The description gives a specific verb (add) plus resource (attached private server address on the selected listener) and adds a scoping constraint: the backend validates membership in this network. An agent can distinguish it from add_network_load_balancer_listener and remove_network_load_balancer_member by name alone. It stops short of explicitly differentiating itself from sibling tools, so 4 rather than 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?

It states concrete preconditions: read current capabilities and owned resource state first, and obtain approval for the exact change. It also implies the required permission scope, which effectively gates when the call can succeed. It does not, however, name an alternative tool or an explicit when-not-to-use 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 destructive and open-world, but the description adds concrete consequences: the written records can change public DNS answers, overwrite=true replaces conflicting records, all writes pass the same API validation, quotas, and conflict rules, and dns:write is required for API keys. It even recommends preview to inspect the exact changes before applying. This is rich disclosure beyond structured 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?

Five short sentences, each earning its place, with the core action front-loaded. No filler or redundancy; the progression from action to side effects to validation to preview to auth is logical.

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, open-world mutation with no output schema, the description covers the essential context: side effects on public DNS, destructive overwrite behavior, safety recommendation (preview), auth requirement, and validation/quotas. Nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents preview, overwrite, zone_id, template, and parameters. The description reinforces the meaning of preview and overwrite but adds no new syntax or constraints beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb and resource — 'Apply a backend-defined DNS template to a native forward zone' — and distinguishes the operation from manual record writes by noting records pass the same validation, quotas, and conflict rules. It does not name a specific sibling tool (e.g., list_dns_templates or upsert_dns_record), so it falls just short of the sibling-differentiation bar.

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?

Recommends 'Prefer preview=true first to show the user exactly which records a template would write before changing the zone,' which is a clear context and safe-order guideline. It also notes the dns:write requirement, but stops short of explicitly stating when to choose this tool over manual record writes or naming alternatives.

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

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

Goes well beyond the annotations: discloses that the operation recreates the gateway and interrupts connections, that it requires explicit networking:read/networking:manage scopes (and that default scopes do not grant networking), that the backend enforces ownership/feature/2FA locks, and how to interpret pending vs failed states. It also details idempotency-key recovery behavior on transport uncertainty, which annotations alone do not convey.

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

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

The purpose and its disruptive consequence are front-loaded, followed by auth, preconditions, and result-interpretation guidance. It is dense and long, but nearly every sentence carries actionable information for a destructive, idempotent operation, so little 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?

Annotations cover the safety/idempotency profile and the schema fully documents all three parameters, yet the description still supplies the missing operational context: interruption warning, auth scope requirements, pending-vs-failure semantics, polling cadence, and recovery rules. Nothing an agent needs to invoke this safely is absent.

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 nonetheless adds usage semantics for idempotencyKey ('reuse only the original key and unchanged request; never automatically retry') and implies that gateway_id/network_id must reference owned resources. This meaningfully extends the schema's field-level documentation.

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 ('Attach or move an account VPN to an owned network') and adds a gating condition ('only when standalone attachment is advertised'). It clearly implies the inverse of the sibling detach_network_vpn_gateway without naming it explicitly, so sibling differentiation is present but not stated outright.

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

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

Gives an explicit when-to-use condition ('only when standalone attachment is advertised'), a prerequisite sequence ('Read current capabilities and owned resource state first; obtain approval for the exact change'), and a confirmation requirement. It does not name alternative tools or spell out when not to use it, so it stops short of a 5.

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

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

Beyond the annotations (idempotentHint=true, destructiveHint=false), it discloses a great deal: the accepted attach is pending rather than confirmed, reserve/activate/detach take 13-81 s, the reason_code/in_progress state machine semantics, required networking:read vs networking:manage scopes, and backend ownership/2FA enforcement. Idempotency recovery behavior (reuse only the original key and unchanged body) is spelled out.

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 purpose and prerequisites are correctly front-loaded, but the polling instruction is stated twice ('poll it with get_networking_operation...' and later 'Poll the returned operation/resource on its in_progress flag...'), and the pending/reason_code guidance is repeated, making the description longer than it needs to be.

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

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

For an async, world-mutating tool with no output schema and partial parameter coverage, the description covers the full lifecycle: pre-flight candidate check, auth scopes, pending semantics, poll cadence via get_networking_operation, activation_operation_id chaining, failure-vs-waiting reason interpretation, and safe recovery on transport uncertainty. An agent has everything needed to invoke and follow up correctly.

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

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

Schema coverage is 60%, and the description fills the notable gap: ipv4 has no schema description, yet the description explains omitting it triggers automatic allocation while passing one requires a fixed usable address. It also reinforces the restart approval condition and idempotencyKey preservation, adding meaning beyond the schema for the parameters that matter most.

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 opening clause names a specific verb and resource ('Attach an eligible existing owned service to a private network') with an eligibility qualifier (port_intent_ready=true), which clearly separates it from siblings like attach_public_address_to_server or attach_network_vpn_gateway. It is slightly weakened by burying the core action under a long run-on sentence with operational detail.

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 explicit preconditions and ordering: check list_network_attachment_candidates for pagination and attachment_mode first, set restart=true only after user approval, omit ipv4 for auto-allocation, and poll with get_networking_operation rather than retrying blindly. This is textbook when-to-use and when-not guidance with named collaborating 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 destructive, open-world, and non-idempotent behavior, but the description adds critical context: moving removes the prior target's use, permissions do not come from full/read defaults, backend enforces ownership and 2FA locks, and an accepted operation is pending rather than proof of connectivity. It also explains polling semantics and safe retry guidance, which is substantial behavioral detail beyond 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 core purpose is front-loaded in the first sentence, and subsequent sentences carry important operational information given the absence of an output schema. However, the description is a dense wall of procedural text that could be more scannable with structure, so it falls short of ideal conciseness.

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

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

For a complex asynchronous mutation with no output schema, the description covers what is needed: permission requirements, approval prerequisites, pending-operation semantics, polling behavior with next_check_seconds and reason_code, failure interpretation, and safe handling of transport uncertainty. It is complete enough for an agent to invoke and monitor the operation 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 67%: address_id and network_id have schema descriptions, but expected_generation has none. The description mentions NETWORK generation, which hints at the generation parameter, but does not explain what expected_generation represents or how to obtain it. Baseline 3 is appropriate since the schema does most of the work and the description adds only marginal 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?

States a specific verb pair (attach or move) and resource (already-paid public address) with the exact target (owned network's NAT). It also clarifies scope by saying no purchase occurs, which distinguishes it from purchase or allocation tools and from sibling attach/detach operations.

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

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

Provides clear prerequisites and permission context: read current capabilities and owned resource state first, obtain approval, and use networking:read or networking:manage. It does not explicitly name alternative sibling tools or say when not to use this tool, but the operational context is clear.

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

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

Goes well beyond the annotations: it discloses that movement affects the previous target, specifies the networking:read vs networking:manage permission split (and that full/read defaults do not grant networking), notes backend enforcement of ownership/feature/2FA locks, and fully documents the async model (accepted = pending, in_progress/reason_kind/reason_code semantics, no automatic retry). This is unusually rich behavioral context for a destructive 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?

Front-loads the core action in the first sentence, and nearly every clause carries behavioral information. It is dense and somewhat run-on in the polling/retry section, with a few fragments ('Preserve reason_code.'), but there is little pure 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, non-idempotent mutation with annotations present and no output schema, the description covers permissions, pre-checks, side effects on the previous target, and the full async/error handling contract. An agent has everything needed to invoke and monitor it correctly.

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

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

Schema coverage is 100%, and both UUID parameters are fully described in the schema, so the baseline is 3. The description adds only indirect meaning (that address_id is an owned paid address and private_port_id belongs to the target server) but no formatting or lookup guidance 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 precise verb pair (attach or move), the exact resource (an owned paid public address), and the target (an eligible zero-public-IP server's private port). This distinguishes it immediately from siblings like attach_public_address_to_network and attach_private_network_port without needing to open 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?

Gives strong context: pre-read server_target_enabled and candidate state, obtain approval for the exact change, and the eligibility constraint (zero-public-IP server). It stops short of explicitly naming alternative sibling tools for non-server targets, so it is clear context rather than full when/when-not routing.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it constrains the target zone type (owned forward, not secondary/suspended), explains the IP ownership rule, and states the dns:write requirement. It does not clarify whether an existing record is overwritten or what happens on conflict, which is a minor gap given the destructive hint.

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, followed by tightly packed constraints, exclusions, an alternative, and an auth requirement. Every sentence earns its place; there is no filler or repetition.

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

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

For a mutation tool with no output schema, the description covers purpose, constraints, alternative, and permissions well enough for correct selection and invocation. However, it does not describe the return value or error behavior (e.g., what happens if the record already exists), which would be useful since no output schema is provided to fill that 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 the schema already documents all seven parameters. The description adds meaningful semantics beyond the schema by stating that the provided ip must belong to the service (a constraint not present in the schema) and that A/AAAA default to the service IP when ip is omitted. It does not elaborate on ttl, target, or name handling, but those are covered by 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 ('creates an A/AAAA/CNAME record') and immediately distinguishes the tool from siblings by naming upsert_dns_record for arbitrary record content. The scope ('owned forward DNS zone', 'using the service's own IP') further disambiguates it from generic DNS record creation 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?

Explicitly gives when to use (point a DNS name at a service), when not to use ('Not for secondary/suspended zones'), the alternative for other cases ('For arbitrary record content use upsert_dns_record instead'), and a required permission ('Requires dns:write when using an API key'). This is comprehensive guidance with no inference needed.

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

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

Adds substantial context beyond the annotations: exact scope requirements (networking:read vs networking:manage, with full/read defaults not granting networking), backend enforcement of ownership, feature availability and 2FA locks, and the crucial warning that an accepted operation is pending rather than proof of connectivity. It also fully specifies the polling contract (in_progress/reason_kind/reason_code, next_check_seconds) and the no-auto-retry policy on transport uncertainty.

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 purpose and the 'does not purchase' scope, then moves to prerequisites and the polling protocol; every sentence carries operational weight. It is dense and long, but for a tool with no output schema the polling/reason_code detail is not filler.

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

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

With no output schema, the description carries the full burden and does: it describes the returned operation/resource, the in_progress flag, reason_kind/reason_code semantics, next_check_seconds, and the failure condition. Combined with auth scopes and idempotent recovery rules, an agent has everything needed to invoke and follow up correctly.

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

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

Schema coverage is 75%, so the schema already documents binding_id, private_port_id and idempotencyKey. The description reinforces idempotency-key preservation and body-unchanged recovery, but adds nothing for expected_generation (optimistic-concurrency semantics are left unexplained), so it only marginally exceeds 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 (bind a floating public binding to a private port) and scopes it with 'already reserved' and 'does not purchase an address,' which separates it from purchase/attach siblings. It stops short of naming an explicit alternative tool, so it is clear but not fully sibling-differentiating.

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 concrete preconditions: read capabilities and owned resource state first, obtain approval for the exact change, and the operation only applies 'when supported.' No sibling tool is named as an alternative, but the when-to-use context is explicit and actionable.

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

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

Goes well beyond annotations: declares the call is asynchronous and returns a pending browse id, requires services:read and a write-capable API key because it is a POST, requires an idempotencyKey, and warns that 'partial'/'truncated' listings are bounded lower-bound slices that must never be presented as a whole folder. This is rich context the structured annotations do not 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?

Purpose and the 'does not' scope are front-loaded, but the body is a single dense paragraph that mixes paging, filtering, and async semantics. Nearly every clause earns its place, though breaking the paging and filter rules into separate sentences would improve scannability.

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

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

There is no output schema, so the description must carry the return contract — and it does: pending browse id, state polling via get_restore_file_browse, result.nextOffset, result.pageSize, truncated, and listingStatus 'complete' vs 'partial'. Complete for a 7-parameter async 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 already 100%, so baseline is 3, but the description adds relational meaning the schema fields do not: sourceBrowseId and directoryEntryId must be used as a pair from the same result, paths are never accepted, offset must be 0 when entering a directory, and pageSize should be read from the result rather than assumed. That is genuine added value over the per-field 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 and resource ('Create a persisted asynchronous browse job to list one directory inside a backup point') and immediately scopes what it is NOT ('does not restore files, change backup contents or the running server, or charge the account'). This cleanly separates it from list_restore_file_points and get_restore_file_browse.

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

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

Explicit entry conditions (root via backupPointId, subdirectory via sourceBrowseId + directoryEntryId), explicit paging loop (while result.nextOffset is non-null, call again with same sourceBrowseId/directoryEntryId and offset), the filter precondition (searchAvailable=true from list_restore_file_points), and the follow-up step (poll get_restore_file_browse until succeeded). Nothing 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 cover the safety profile (readOnlyHint=true, destructiveHint=false), and the description adds real behavioral context beyond them: the conversion arithmetic, that upgrades move expiry EARLIER while downgrades move it later, that paymentRequired=false, and the required permission scope. This is unusually rich disclosure for a read-only tool.

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

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

Front-loaded with the purpose, then value/semantics, then return fields, then the prerequisite, then auth. Every sentence carries distinct information — no restatement of the name or filler — despite being a single dense paragraph.

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 naming the exact returned fields (expirationDate, currentExpirationDate, expirationChangeDays with sign convention, paymentRequired) and telling the agent to surface both dates to the customer. Combined with 100% param coverage and read-only annotations, nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents orderNo format, plan ID sourcing, and the resources array semantics in detail. The description's only added param signal is the get_plan_resources pointer for resource IDs, which largely duplicates the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Preview a plan change') and immediately disambiguates it from the actual-change siblings (change_plan) by emphasizing 'No payment is taken' and the preview output. An agent can tell this is a read-only estimator rather than a mutation without opening any schema.

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

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

Gives explicit ordering guidance ('Use get_plan_resources first to see available resource IDs for the target plan') and states the auth scope ('Requires services:read when called with an API key'). It stops short of naming change_plan as the alternative when the customer actually wants to apply the change, so the when-not is only implied by 'Preview'.

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

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

Annotations only give broad hints (destructive, idempotent); the description adds critical context: backend eligibility verification, exact same-key retry replay semantics after advertised state changes, required applications:manage scope, fresh idempotency key rules, and that it is not a paid API-key operation.

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

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

Front-loads the core constraint (exact latest cancellable action) then layers eligibility, retry semantics, requirements, and scope. Every sentence carries distinct information with no redundancy.

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

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

For a destructive, precondition-heavy mutation tool with no output schema, the description covers eligibility prerequisites, idempotency behavior, permissions, and limitations – sufficient for an agent 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 coverage is 100%, so the schema already documents all four parameters including patterns and formats. The description reinforces the idempotencyKey 'fresh, not reused' rule and the action_id exactness, but adds only marginal value over 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 (cancel), scope (pre-dispatch, exact latest action), and resource (owned managed application). Clearly distinguishes from siblings like cancel_vm_operation or restart_application by naming the exact-action constraint.

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 conditions use on get_application_installation advertising latest_action.cancellable=true, names the exact required UUID, and states what it does not do (never stops a running worker job) – clear when/when-not guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description still adds real value beyond them: durability of the action, the explicit-approval requirement, the certificates:manage permission, and idempotency-key reuse discipline. It stops short of stating the downstream effect of cancellation (e.g., what happens to the associated certificate), which keeps it from a 5.

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

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

Three compact sentences, front-loaded with the action and its prerequisites, then the durability/idempotency rule, then the permission. No filler and no repetition of schema or annotation content.

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

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

For a destructive mutation with no output schema, it covers prerequisites, approval, permissions, and retry semantics adequately. The main remaining gap is what the cancellation actually does to the subscription's certificates and whether it is reversible.

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 75%, so the schema largely documents the parameters itself, setting the baseline at 3. The description reinforces idempotencyKey semantics ('instead of using a new key') and implies the acknowledgement/approval requirement, but adds no syntax or format detail for reason or certificate_subscription_id.

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

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

Specific verb+resource ('Cancel an owned Automatic SSL subscription') with the owning-scope qualifier, which cleanly separates it from cancel_certificate, cancel_free_certificate, and refresh_automatic_ssl_subscription. An agent can identify the tool's function and its target resource 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?

Explicit prerequisites: read get_automatic_ssl_subscription and list_automatic_ssl_actions first, obtain explicit approval, and hold certificates:manage. It also gives recovery guidance for the ambiguous-outcome case (refresh and read state rather than retry with a new key), which is precisely the when/when-not instruction an agent needs.

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

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

Annotations already mark this destructive, non-read-only and idempotent, so the safety profile is known. The description adds auth scope ('Requires certificates:manage'), a mandatory human-approval gate, and back-off behaviour on ambiguous results, all of which go beyond the annotations. It still says nothing about what state the order lands in after cancellation.

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?

Purpose is front-loaded in the first clause, followed by required preconditions and the permission requirement, with no filler. The intermediate 'read product capabilities / current order' enumeration is slightly procedural but each sentence carries an actionable instruction.

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 supplies the prerequisites, the approval gate, auth scope, and a retry discipline. The main remaining gap is the post-cancellation state and whether the action is reversible, which is minor given the rich 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 75%, so idempotencyKey, certificate_order_id and acknowledge_certificate_action are already documented in the schema; the description simply hints at approval and idempotent retries. The one undocumented parameter, reason, gets no added meaning from the description. Baseline 3 is appropriate.

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

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

Specific verb plus a tightly scoped resource: 'Cancel an eligible pending paid TLS certificate order.' The qualifiers 'pending' and 'paid' cleanly separate it from cancel_free_certificate, revoke_free_certificate and cancel_automatic_ssl_subscription without opening any schema.

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

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

Gives a clear pre-flight workflow (read product capabilities, current order, list_certificate_actions, then obtain explicit approval) and a retry rule for ambiguous outcomes, which is real when-to-use guidance. It stops short of naming an alternative action to take instead when the order is not eligible or when cancelling is the wrong move.

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 destructive=true, idempotent=false, openWorld=true, but the description adds genuinely new behavior: the required certificates:manage permission, the mandate for explicit user approval, and the instruction to poll get_free_certificate to observe the outcome. This is more than the annotations convey.

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

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

Three tight sentences with no filler; the destructive scope is front-loaded, followed by the approval/polling workflow and the permission requirement. Every sentence carries distinct, actionable information.

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

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

For a two-parameter destructive mutation with full schema coverage and annotations, the description supplies the missing operational context: permission scope, approval gate, and result-verification path. No output schema exists, so it correctly does not attempt to describe return values.

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 the UUID and the acknowledge boolean are fully documented in the schema. The description adds no syntax or format 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 (Cancel) and a precisely scoped resource: an owned pending free TLS certificate request, explicitly before issuance. This distinguishes it from revoke_free_certificate and cancel_certificate by lifecycle stage, though it does not name those siblings outright.

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

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

Provides a clear workflow: read current state, get explicit user approval, then poll get_free_certificate for the final result, which names an alternative retrieval tool. It does not, however, explicitly state when to prefer revoke_free_certificate instead of cancelling.

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

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

Annotations already declare destructive, idempotent and open-world behavior, so the bar is lower; the description still adds the certificates:manage permission requirement, the mandatory approval gate, and the retry rule (reuse the key / refresh and read state rather than minting a new key). It does not say what the change disrupts for in-flight validation, which would have pushed this higher.

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 preconditions, then the edge-case rule. No waste, though 'Read current validation' is slightly vague about which tool is meant.

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, 5-required-parameter mutation with no output schema, the description covers preconditions, approval, permissions and retry behavior. The main omission is the set of valid validation_method values and any statement of what the change affects, but the essential calling information is present.

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

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

Schema coverage is 60%, but the description compensates meaningfully: 'one authorized DNS name' clarifies domain, 'obtain explicit approval' maps to acknowledge_certificate_action, and 'instead of using a new key' explains idempotencyKey reuse semantics. It adds no guidance on acceptable validation_method values, which is the remaining gap.

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

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

States a specific verb (change), resource (validation method), and precise scope: one authorized DNS name on an owned paid TLS certificate order. The 'paid' and 'one DNS name' qualifiers distinguish it from free-certificate siblings and from recheck/resend/get validation 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?

Gives an explicit prerequisite sequence — read current validation and list_certificate_actions first, then obtain explicit approval — and a conditional rule for ambiguous outcomes. It does not explicitly contrast with siblings like recheck_certificate_validation or resend_certificate_validation, so the agent must infer when those are preferable.

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?

Substantial disclosure beyond annotations: reserved-name rules, the 422 reservedHostname error, hostname format constraints, required scope (services:manage) and full-access API key, and that the route is not idempotency-keyed. The async nature and tracking UUID are clearly explained, matching the destructiveHint and openWorldHint annotations without contradiction.

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?

Information is dense but front-loaded with the core action, then validation rules and the async return. It is a bit long, but nearly every sentence carries a distinct constraint, so waste is 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?

Given a mutation tool with no output schema, the description covers the action, side effects, error cases, required permissions, async tracking, and hostname validation—everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents both parameters with patterns and lengths. The description restates the hostname rule but adds no syntax or format detail beyond the schema, which is the baseline expectation at full coverage.

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

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

States a specific verb and resource ('Queue a customer-managed hostname change') for named service types (Container VPS, VPS, Cloud VPS). It is clearly distinguishable from siblings like get_hostname and reset_hostname.

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 by describing the operation, and mentions the returned noty UUID ties to get_event/wait_for_event, which hints at a follow-up pattern. However, it never explicitly states when to use this vs alternatives like reset_hostname, nor does it name any alternative 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?

Adds substantial behavioral context beyond the annotations: no payment is taken on plan change, remaining value is converted at the new price, and an upgrade shortens the service period. It also discloses required permissions (services:manage) and a full-access API key, which the structured fields do not convey.

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

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

Front-loads the core action and then adds prioritised behavioral and prerequisite information in tight, imperative sentences. Every sentence carries useful weight, though it is slightly longer than a minimal ideal.

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 a destructive mutation with no output schema and annotations that only flag destructiveness, the description covers the essential billing semantics, prerequisites, and authentication requirements an agent needs to invoke it correctly. 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%, so the schema already fully documents each parameter. The description references get_plan_resources for resource IDs, adding procedural guidance, but does not expand on parameter formats or meanings beyond what the schema provides, keeping it at the 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 and resource ('Change VPS plan') that unambiguously identifies the operation. The scope is narrowed to VPS plans, and related tools (calculate_plan_change, get_plan_resources) are named, so an agent can place it precisely in the plan-change workflow.

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

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

Provides explicit prerequisites: always call calculate_plan_change first, confirm new expiry with the customer, and use get_plan_resources for resource IDs. These are clear usage conditions, though it does not state when to use this tool versus alternatives like renew_service or order_service, so it falls short of a full 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, but the description adds substantial context: propagation replacement, trailing-dot removal, reserved VPSnet names being blocked, OAuth scope services:manage, API-key full-access requirement, and lack of idempotency-keying. This is rich behavioral disclosure beyond 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?

Front-loaded with the core action, then constraints, then auth, then idempotency. Every sentence carries distinct operational value 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 tool with no output schema, the description covers the action, value constraints, auth requirements, propagation behavior, and idempotency caveat. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100% and each parameter already carries a description, including the PTR validation rules. The description repeats the canonical length/label constraints and adds that reserved names are blocked, but does not add much new meaning for the individual parameters beyond the schema 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 ('Set'), resource ('customer PTR override'), and scope ('for an address returned by get_rdns'). Distinguishes itself from sibling read tool get_rdns and clear_rdns, so an agent can 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?

Clear context: use it to set a PTR override for an address returned by get_rdns, and notes the value replaces the previous public PTR after propagation. It does not explicitly name when-not to use it or contrast with clear_rdns, so it stops short of full routing guidance.

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

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

Annotations declare destructiveHint=true but say nothing about the operation's side effects. The description adds meaningful context: the password format constraints, the required permission scope, and the full-access key requirement. It does not state whether the old password is invalidated or the service restarted, so it stops short of full disclosure.

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, no filler, front-loaded with the action and immediately followed by constraints and prerequisites. Every sentence carries information the caller needs.

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

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

For a 2-param mutation with no output schema, it covers action, constraints, example, and auth prerequisites. The one gap is what happens to the instance afterward (e.g., whether a reboot or session invalidation occurs), but the core invocation needs are met.

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

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

Schema coverage is 100%, so the schema documents both parameters; the description nonetheless restates the password rules with a concrete example ('MyPass123'), which is useful for constructing a valid value. It adds no new meaning for orderNo, but the password guidance has practical value.

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

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

Specific verb+resource ('Change VPS root password') with no ambiguity, and 'VPS' plus 'root' clearly distinguish it from the many networking/SSL sibling tools. An agent can identify this as a server credential mutation immediately.

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

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

The description states prerequisites (services:manage, full-access API key) but gives no explicit when-to-use vs alternatives guidance. Since no sibling tool changes root passwords, the risk of misrouting is low, but the description relies on that inference rather than stating it.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so safety profile is partly covered. The description adds concrete auth requirements (services:manage, full-access API key) that annotations don't provide, which is genuinely useful. It does not explain what changes or side effects, but the auth disclosure exceeds the annotation bar.

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 efficient sentence with zero waste; the action is front-loaded. Could be structured with the prerequisite separated from the action, but it is tight and readable.

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

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

For a 2-param mutation with no output schema, the description covers the core action and auth requirements. It omits scope details (e.g., whether title must be unique, whether change is immediate) but annotations and schema carry most of the burden.

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

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

Schema coverage is 100%, so both parameters are fully documented in the schema including length constraints and patterns. The description adds no parameter syntax or format details beyond the schema. Baseline 3 is appropriate.

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

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

Clear verb+resource: 'Change service display title'. An agent understands it renames a service's visible title. It does not distinguish from sibling get_title or change_hostname, but the resource 'title' is specific enough to differentiate.

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 the prerequisite (services:manage and full-access API key), which is useful context, but provides no explicit when-to-use vs alternative (e.g., change_hostname, get_title) guidance. Usage is implied by the name only.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is clear. The description adds a valuable operational context: the required API key scope (domains:read), which an agent must know before invoking with an API key. It does not cover return behavior or rate limits, but the added auth need earns credit above the annotation baseline.

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: the first front-loads purpose, the second adds the key prerequisite. No filler or redundancy; 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?

For a simple one-parameter read-only check with rich annotations and no output schema, the description covers purpose and the key auth requirement. It does not explain what the returned availability result looks like, but with no output schema that is not strictly required, and the definition is otherwise complete for correct invocation.

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