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

The annotations already mark the tool as idempotent and non-destructive. The description adds valuable behavioral context beyond those hints: 'Existing records are kept' and 'Creates the RRSet if it does not exist yet — so denying create_rrset does not remove the ability to create one.' This explains side effects and permission implications without contradicting 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 no filler. The main action is front-loaded, and the second sentence earns its place by explaining an important side effect and a permission nuance.

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 schema and annotations, the description covers the key behavioral distinctions an agent needs: additive semantics, implicit RRSet creation, and non-destructive behavior. It could be slightly more complete by explicitly directing agents to set_records for replacement workflows, but the core calling context is well covered.

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 83%, and the input schema already provides detailed descriptions for parameters like ttl, name, type, zone, records, and confirm_token. The tool description adds no extra parameter-level semantics, so the baseline of 3 is appropriate.

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

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

The description states a precise action, 'Add records to an RRSet', and clarifies the scope with 'Existing records are kept.' It further distinguishes itself by noting it creates the RRSet if it does not exist, which differentiates it from create_rrset and set_records.

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

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

The description gives clear context for when to use the tool: it is additive rather than replacing, and it can create the RRSet implicitly. However, it does not explicitly name sibling alternatives like set_records or remove_records or state when not to use them, so the guidance is clear but not 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?

Despite annotations already marking this destructive, the description adds crucial behavioral context: on the next transfer the entire zone content will be taken from the new primaries. It also discloses the two-phase token mechanism, that the token is short-lived, and that it is bound to exactly this nameserver list.

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, each earning its place: purpose, consequence, and confirmation protocol. No filler or redundancy with the schema.

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

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

For a destructive two-step operation, the description gives the agent the critical facts: secondary-only applicability, full zone replacement, and the first-call token workflow. With a rich input schema, an output schema, and annotations covering idempotency and destructiveness, no essential guidance 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 schema carries the parameter detail, and the baseline is 3. The description adds meaning by explaining the confirmation token flow and framing primary_nameservers as the source of the next full zone transfer, which is not fully captured in the property descriptions.

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

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

The description opens with a specific verb ('Replace') and names the exact resource: the primary nameservers of a secondary zone, with a parenthetical clarifying these are the servers Hetzner transfers the zone from. This clearly distinguishes it from zone creation, deletion, TTL, and RRset tools among the 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?

It explicitly constrains use to zones in secondary mode, which is a clear when/when-not condition, and describes the two-call confirmation flow as the expected way to invoke it. It does not name an alternative tool, but the sibling set makes the alternative (normal zone updates) reasonably obvious.

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 indicate this is a mutating, non-destructive, idempotent operation, and the description adds meaningful behavioral detail beyond that: enabling takes effect immediately, disabling requires a follow-up token, and the operation's purpose is a safeguard against deletion and record replacement. No contradiction with annotations was found.

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 no filler; the immediate-vs-guarded distinction is front-loaded and every clause carries operational meaning.

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 tool with a confirm-token flow, the description plus the detailed schema and annotations are largely sufficient. The only minor gap is that the description itself doesn't spell out that a disabling first call returns a token without applying the change, though the confirm_token schema field covers this.

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

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

With 100% schema description coverage, the baseline is 3, but the description adds value by explaining the semantic link between the `change` and `confirm_token` parameters: disabling requires a token while enabling does not. The schema also documents the first-call/token behavior, so the description is a complement rather than a replacement.

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 opens with the specific action 'Enable or disable' and names the exact resource, 'the change protection of an RRSet,' so an agent immediately knows what the operation does. This clearly distinguishes the tool from the zone-level sibling change_zone_protection and other RRSet mutation 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 gives clear usage context: enabling is immediate and needs no token, while disabling is guarded by a confirm_token because it removes the last protection against delete_rrset and set_records. However, it never explicitly names alternatives or states when not to use this tool versus change_zone_protection or other 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds the null-fallback behavior, which is useful context, but it does not disclose additional side effects or prerequisites. No contradiction with annotations exists.

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

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

The description is two short sentences with no filler. The core action is front-loaded, and the null behavior is stated immediately after, making it easy for an agent to parse.

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

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

Given the rich input schema, output schema, and annotations, the description covers the essential purpose and the one non-obvious behavior (null fallback). Nothing critical is missing for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description's null-fallback note is also present in the ttl parameter description, so it adds no new meaning beyond the schema.

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

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

The description states a specific verb ('Change') and resource ('Time To Live (TTL) of an RRSet'), making the tool's function immediately clear. It also distinguishes itself from siblings like change_zone_ttl (zone-level) and update_rrset (general RRSet update) by focusing specifically on TTL.

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 is provided on when to use this tool versus alternatives such as update_rrset or change_zone_ttl. The only usage-related note, 'Pass null to fall back to the zone's default TTL,' addresses parameter behavior 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?

The description discloses the non-obvious confirm_token requirement for disabling and notes the immediate effect of enabling. It does not mention idempotency explicitly, but the annotation already indicates it, and the description does not contradict it.

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

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

Two concise sentences with no fluff. The key points (enable immediate, disable requires token) are front-loaded, and the 'exactly like a deletion' analogy adds clarity without excess.

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

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

The description covers the main workflow and the token requirement, but does not describe possible errors or the exact return value. Given the moderate complexity, it is sufficiently complete for an agent to invoke the tool correctly.

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

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

The schema already describes all three parameters, and the description adds crucial context for confirm_token—explaining the first-call omission and server-issued token—which goes beyond the schema and fully clarifies usage.

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

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

The description clearly states the action (enable/disable) and the specific resource (delete protection of a DNS zone), distinguishing it from sibling tools like delete_zone or update_zone.

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 explains the two modes (enable immediate, disable requires confirm_token) and the two-step confirmation flow, but does not explicitly contrast with alternatives; still, the behavior is clear enough for an agent to know when to use it.

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

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

Annotations already establish this is a mutating, non-destructive, idempotent operation. The description adds meaningful behavioral context beyond those annotations: it changes only the zone default and does not override RRSets that already have explicit TTLs. This helps the agent predict the tool's actual effect.

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 tight sentences with no filler. The primary action is front-loaded, and the crucial scoping condition ('Applies to RRSets without an explicit TTL') is placed immediately after the main statement, making the definition easy to parse.

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

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

For a simple two-parameter mutation tool with full schema coverage, an output schema present, and safety-relevant annotations already provided, the description covers everything needed to select and invoke the tool correctly. No critical behavioral or scoping information 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?

Input schema coverage is 100%, so both parameters are already well documented with types, ranges, and examples. The description does not need to add parameter-level detail, and it does not; it stays at the operation level, which is acceptable given the schema coverage.

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

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

The description states a specific verb ('Change') and resource ('default Time To Live (TTL) of a DNS zone'), and adds the key scope detail that it applies only to RRSets without an explicit TTL. This differentiates the tool from the sibling change_rrset_ttl without needing to inspect 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?

The description clearly indicates this tool is for setting the zone-level default TTL, and the phrase 'Applies to RRSets without an explicit TTL' signals when this tool is not appropriate. It does not explicitly name an alternative like change_rrset_ttl, but the intended use case is clear from the sibling list and wording.

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 indicate a non-read-only, non-idempotent operation, and the description adds a critical behavioral detail: creation fails rather than overwriting when the same name/type exists. It does not spell out the confirm_token flow, but that is documented in the input schema, so the description adds meaningful context beyond annotations without contradicting them.

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

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

The description is two short sentences with no fluff: the primary action is front-loaded, followed immediately by the key failure condition and routing to alternatives. 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 tool with seven parameters, dense schema descriptions, an output schema, and a confirmation-token mechanism, the description plus schema is complete: it defines what the tool does, the main trap (existing RRSet), and the right alternatives. No critical calling context 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?

The schema already provides rich descriptions for 86% of parameters, including the relative-name and zone-file-syntax examples. The description's example A record for 'www' mostly repeats schema content, and the uniqueness constraint is more behavioral than parameter-level, so it adds only modest semantic value.

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

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

The description uses a specific verb and resource: creates an RRSet in a zone, with a concrete example (A record for 'www'). It also states the central constraint (fails if same name and type already exists), which clearly differentiates it from update_rrset and set_records/add_records.

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

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

It explicitly tells the agent when not to use this tool: if the RRSet already exists, use set_records or add_records. This is a direct when/when-not statement with named alternatives, so an agent can route correctly without opening sibling schemas.

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, the description discloses a non-obvious behavior: creating a zone with primary_nameservers or a zonefile requires human confirmation because those parameters carry the entire zone content. This is critical for an agent to anticipate a multi-step interaction and is not evident from the schema alone.

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

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

The description is compact and front-loaded with the core action, then provides mode selection guidance, then the important confirmation caveat. Every sentence adds value, and the reference to sibling tools is efficient rather than 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?

Given the tool's complexity (7 parameters, nested objects, output schema), the description covers the most decision-critical aspects: mode choice, primary_nameservers usage, zonefile initialization, and the human confirmation requirement. Remaining details like labels, ttl, and exact response format are adequately handled by the schema and output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics for mode, primary_nameservers, zonefile, and the confirmation flow, going beyond the raw schema definitions. It does not discuss ttl or labels, but those are already well described in the schema.

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

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

The description opens with a specific verb and resource: 'Create a new DNS zone.' It further distinguishes the two modes (primary vs. secondary) and explicitly references sibling tools change_primary_nameservers and import_zonefile, making the tool's unique role clear.

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

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

The description gives explicit guidance on when to use each mode: primary for Hetzner-managed zones, secondary with primary_nameservers for external transfer. It also warns that primary_nameservers and zonefile trigger a human confirmation step, and compares this behavior to related sibling 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?

The description discloses the most critical behavior beyond annotations: deletion is permanent and irreversible, and a two-step confirmation flow is required. This adds key context that destructiveHint and idempotentHint alone do not provide, such as the token lifetime and the need to ask the 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?

The description is two sentences with no filler. The first sentence states purpose and consequence, and the second explains the required confirmation workflow. 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 destructive tool with a confirmation workflow, the description covers the essential behaviors: irreversibility, token request, user confirmation, and second call. The output schema is present, and the annotations cover safety flags, so nothing critical is missing for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, and the input schema already documents every parameter, including the confirm_token behavior. The tool description reinforces the two-step flow but does not add significant new parameter meaning 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 specific verb ('delete'), a specific resource ('RRSet'), and clarifies that it removes all records in the set. It also distinguishes this from partial record removal operations like remove_records by emphasizing 'with all its records'.

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

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

The description gives explicit operational guidance: the first call obtains a confirmation token, the user must be asked, and a second call with confirm_token completes deletion. It does not explicitly compare against sibling tools, but the 'with all its records' and irreversible framing make the correct context clear.

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

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

Beyond the annotations, the description discloses the two-call confirmation behavior, irreversibility, and that all records are deleted with the zone. This is precisely the kind of behavioral context an agent needs to avoid accidental destructive actions.

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

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

Two tight sentences front-load the destructive consequence and then explain the required confirmation flow. Every word earns its place and no unrelated details are included.

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

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

For a mutating two-step tool, the description fully covers what will happen, the safety mechanism, and how to complete the operation. The output schema and annotations cover the remaining structural details.

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

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

Schema coverage is 100% and confirms the meaning of zone and confirm_token. The description adds critical behavior for confirm_token — omit on first call, include on second — which goes beyond the schema's field 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 clearly states a specific verb and resource: permanently delete a DNS zone including all its records. It distinguishes this from sibling tools like delete_rrset by specifying the zone-level scope.

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

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

It provides explicit usage context: the first call returns a token, the user must be asked, and the second call must include the token. It doesn't explicitly name alternatives or when-not-to-use cases, but the intended invocation flow is unambiguous.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context by specifying that it returns the full zone content in BIND format, but does not disclose additional behavioral details such as size limits or whether the export includes all record types.

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, direct sentence conveys the action, the object, the scope, and the output format with no wasted words. The most important information is front-loaded.

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

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

For a simple one-parameter, read-only tool with an output schema and strong annotations, the description is sufficient. An agent can understand what the tool does, what input it needs, and what kind of result to expect.

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 the zone parameter already documented as 'ID or name of the zone' plus an example. The description does not add further parameter-level meaning, so the baseline of 3 is appropriate.

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

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

States a specific verb (export), the resource (DNS zone), the scope (full contents), and the output format (BIND zone file). This distinguishes it from similar tools like get_zone and list_rrsets without needing to inspect 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?

The description implies the tool is for retrieving the entire zone in BIND zone-file format, which is distinct from listing zones or individual RRsets. However, it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is fully covered. The description adds no additional behavioral nuance beyond the basic 'get' semantics, such as missing-record behavior, pagination, or response details.

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

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

The description is a single well-structured sentence that front-loads the action and resource, with no filler. Every word contributes to scope, target, and lookup criteria.

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 lookup with a rich input schema, full annotations, and an output schema, the description is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%: zone, name, and type each have descriptive text with examples, constraints, and enum values. The description adds little parameter-level meaning beyond referencing name and type, 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 clearly states a specific verb and resource: 'Get a single RRSet' of a zone by name and type. The word 'single' differentiates it from list_rrsets, while the get operation distinguishes it from create/update/delete 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 phrase 'a single RRSet ... by name and type' gives clear context for when to use this tool: fetch one specific record set. It does not explicitly name list_rrsets as the alternative for listing all record sets, 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds little beyond 'full details', but there is no contradiction or hidden destructive behavior to disclose.

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. Every word contributes meaning, and the singular scope is stated up front.

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 one simple parameter, an output schema, and strong annotations, the description is sufficient for an agent to understand the tool's purpose. No critical behavioral or usage context is missing for a read-only single-zone lookup.

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

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

The input schema has 100% description coverage for the single 'zone' parameter, including an example. The description does not need to add parameter semantics, so the baseline of 3 is appropriate.

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

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

The description clearly states a specific verb ('Get') and resource ('a single DNS zone'), and explicitly scopes it to one zone. This distinguishes it from list_zones (plural) and from rrset/action tools even 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 singular phrasing implies this is for retrieving one specific zone by ID/name, while list_zones covers listing. However, it does not explicitly name any alternative or state when not to use this tool, leaving usage mostly 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, idempotentHint, and destructiveHint, covering the safety profile. The description adds that the tool is used to check status and result, implying an asynchronous action may be queried, which is useful. However, it does not go deeper into response behavior, but the output schema mitigates that gap.

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

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

The description is a single, front-loaded sentence with no filler. Every element earns its place: the action, the resource, the lookup key, and the purpose. It is efficient without sacrificing clarity.

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

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

This is a simple single-parameter getter with a rich annotation set and an output schema. The description, combined with the schema and annotations, gives an agent everything needed to select and invoke the tool 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 documents action_id as 'ID of the action'. The tool description merely says 'by ID' and does not add further parameter meaning. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description uses a specific verb ('Get') with a clear resource ('a single zone action') and the lookup key ('by ID'), which cleanly distinguishes it from sibling tools like list_zone_actions and get_zone. It also states the intended purpose ('check its status and result'), leaving no ambiguity about what the tool 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?

The description conveys a clear use case: retrieve one specific zone action by its ID to inspect status/result. It does not explicitly name alternatives or exclusion conditions, but the 'single' wording implies this tool is for targeted lookups, not listing or zone-level operations. This is clear context without formal 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?

Beyond the annotations' destructiveHint, it specifies the exact destructive scope ('REPLACES the current records'). It also discloses the two-step confirmation flow, the token being 'short-lived', and being 'bound to exactly this zone file' — none of which are captured in the structured annotations. No contradiction with readOnlyHint, idempotentHint, or destructiveHint.

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

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

Four short sentences, each carrying essential information: what the tool does, the destructive consequence, the confirmation protocol, and the backup recommendation. There is no filler, and the most important warning appears immediately after the main purpose.

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

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

For a destructive, two-step import tool, the description covers the input format, the target zone type, the replacement behavior, the token workflow, and a safety suggestion. With an output schema available and annotations covering safety hints, nothing critical is missing for an agent to invoke this tool responsibly.

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 meaning by clarifying 'BIND format' for zonefile and 'existing primary zone' for zone, and by emphasizing that confirmation requires asking the user. However, much of the confirm_token lifecycle (omit on first call, valid for a few minutes, identical arguments) is already present in the schema description, so the added value is moderate.

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 ('Import'), a precise resource ('a zone file (BIND format) into an existing primary zone'), and immediately flags the critical effect ('This REPLACES the current records of the zone'). This clearly differentiates it from siblings like export_zonefile, create_zone, or set_records without needing to inspect 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?

It explicitly names an alternative action with 'Consider export_zonefile first as a backup' and scopes usage to 'an existing primary zone'. It also prescribes the required confirmation workflow ('ask the user, then call again with confirm_token'), telling the agent exactly when to issue the second call.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context about the returned content (records, TTLs, protection status) but does not disclose pagination or filtering behavior, which are relevant given the page and per_page parameters.

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

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

The description is a single, front-loaded sentence with no filler. It states the action, the resource, and the key included fields 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?

The description, combined with the rich input schema and output schema, gives an agent enough to select and invoke the tool correctly. It could mention pagination or filtering, but those are already documented in the schema, and the annotations cover the read-only safety profile.

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 fully documents all six parameters. The description does not add additional parameter-level meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('List') and resource ('RRSets of a zone'), and clarifies what is included: records, TTLs, and protection status. This clearly distinguishes it from single-record tools like get_rrset and zone-level tools like list_zones.

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 the tool is for retrieving all RRSets in a zone, but it does not explicitly state when to prefer it over get_rrset or export_zonefile. There is no direct mention of alternatives or exclusion criteria, so the usage guidance is only 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?

The readOnlyHint, idempotentHint, and destructiveHint annotations already cover the safety profile, so the description does not need to restate that this is safe. It adds useful context that actions are asynchronous operations like zone file imports, but it does not elaborate on status values or pagination behavior beyond what the schema and output schema already expose.

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 entire description is one compact, front-loaded sentence with no filler. The parenthetical defining actions as asynchronous operations earns its place and improves clarity without adding bulk.

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

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

For a read-only list tool with fully documented parameters and an existing output schema, the description covers the key decision: all zones versus a single zone. It could be slightly more complete by pointing to get_zone_action for retrieving an individual action by ID, but the current definition is not missing any critical calling information.

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

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

Schema description coverage is 100%, so page, zone, status, and per_page are already documented with their meanings and constraints. The description contributes only the 'single zone if one is given' nuance, which is a minor addition 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?

The description opens with a specific verb 'List' and a clear resource, 'actions,' and further defines them as asynchronous operations like zone file imports. The 'all zones, or of a single zone if one is given' scope makes it easy to distinguish this from zone-listing and single-action retrieval 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?

It explicitly states the condition for using the zone parameter: list actions for all zones, or just one zone if a zone is provided. It does not explicitly call out an alternative like get_zone_action for fetching a single action by ID, so it stops short of full when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds project scope and response fields, but does not disclose pagination behavior or filtering semantics beyond what the schema already provides.

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

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

The description is a single, front-loaded sentence with no filler. It names the action, resource, and key output attributes 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 list operation, the description is largely complete: it states the project scope, the included fields, and the annotations cover safety. The output schema handles return values. The only notable gap is the lack of explicit routing to get_zone for single-zone lookups, but this is not a blocking 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%, with all five optional parameters documented (mode, name, page, per_page, label_selector). The description adds no parameter-specific meaning, so the baseline 3 is appropriate.

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

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

The description uses a specific verb ('List') and resource ('DNS zones of the Hetzner Cloud project'), and enumerates the returned fields (status, mode, default TTL, nameservers, record counts). This clearly distinguishes it from get_zone and the mutation-focused sibling tools.

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

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

The description gives no guidance on when to use this tool versus get_zone or the filtered/export variants. It does not mention alternatives, exclusions, or scenarios where another tool would be more appropriate.

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

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

The description discloses the destructive nature (RRSet deletion when last record removed) and the two-step confirmation token mechanism. It also notes that lacking delete_rrset permission does not prevent this deletion, which is a significant behavioral nuance beyond the destructiveHint annotation.

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

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

The description is three concise sentences that convey all essential information without verbosity or repetition. It is well-structured and easy to parse.

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

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

The description covers the main behavior, the confirmation token flow, and the critical side-effect of deleting the RRSet. It is sufficient for an agent to understand when and how to use the tool, especially given the output schema and parameter descriptions in the schema.

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

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

The schema already provides descriptions for all parameters (name, type, zone, records, confirm_token), covering 80-100% of them. The tool description adds little beyond the schema, only mentioning that records are matched by value and the confirm_token is from a previous call, which is already implied in the schema 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 clearly states the tool's purpose: removing records from an RRSet by value. It also distinguishes it from other operations like adding or setting records, and explains the side-effect of deleting the RRSet when the last record is removed.

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 useful usage context: mentions the confirmation token flow and the consequence of removing the last record. However, it doesn't explicitly contrast with alternatives like add_records or set_records, though the 'matched by value' phrasing makes the intended use clear.

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

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

Beyond the destructiveHint annotation, it states exactly what gets destroyed ('Existing records not listed are removed'). It also discloses the two-step confirmation-token behavior and that the token is bound to the exact record list, which is important safety 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?

Three short sentences with no wasted words. The most important behavioral constraint is front-loaded, and the sibling alternative and confirmation flow follow naturally.

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 replace operation with an output schema and a well-documented input schema, this is complete. It covers scope, exceptions (add_records), and the confirmation-token protocol, leaving no critical gap for an agent to call it correctly.

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

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

Schema descriptions already cover 80% of the parameters well. The description adds value by defining the semantics of 'records' (full replacement) and explaining the role of confirm_token in the first/second call, though it does not need to repeat the detailed field-level schema descriptions.

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

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

The description begins with an explicit verb and resource: 'Replace ALL records of an RRSet with the given records.' It clarifies that existing records not listed are removed, which precisely scopes the operation and distinguishes it from add_records.

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

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

The description directly gives the alternative tool for the opposite behavior: 'Use add_records to append instead.' It also describes the confirmation-token workflow, so an agent can determine whether one call or two calls are 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?

Annotations already mark destructiveHint=true, and the description adds the specific replace-all behavior, which is concrete context beyond the boolean hint. It also confirms idempotentHint behavior by implying the same labels can be reapplied. No contradiction with annotations, though it does not detail what happens to record data or whether the operation can fail.

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

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

Two short sentences with no filler. The main purpose is front-loaded, and the crucial replacement semantics and sibling differentiation are packed into the second sentence. 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?

The tool has an output schema, so return values need no description. Annotations cover safety hints, and the description names the relevant sibling tools for adjacent operations. The only slight gap is that it does not mention prerequisites such as the RRSet needing to already exist, but the schema identifies the zone/name/type locators and this is a moderate 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%, so parameters are already documented. The description adds meaning to the labels parameter by stating that the given set replaces all existing labels, which is not in the schema. This clarifies that labels is a full replacement map, not a merge or partial update.

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: 'Update the labels of an RRSet.' The sentence 'The given set replaces all existing labels' clarifies the exact scope. It distinguishes from sibling tools by explicitly pointing to set_records/add_records/remove_records and change_rrset_ttl for records and TTL changes.

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

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

The description explicitly tells the agent when not to use this tool: records and TTL are changed via other named tools. This creates a clear decision boundary between update_rrset and its siblings. The semantics of 'replaces all existing labels' further clarifies the intended use case.

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 show destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds valuable behavioral context by stating that the provided set replaces all existing labels, which explains the destructive nature and confirms this is not a merge operation. This goes beyond the annotations without contradicting them.

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. The main operation and its replacement behavior are front-loaded, and the pointer to change_zone_* tools is a single parenthetical that earns its place by preventing misuse.

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 only two parameters and an output schema, the description fully covers what the tool does, how it behaves, and how it relates to sibling tools. The destructive 'replaces all existing labels' warning is included, and no critical usage information is missing.

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

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

Schema coverage is 100% and both parameters have descriptions, so the baseline is 3. The description adds extra semantics by clarifying that the 'labels' parameter replaces the entire existing label set rather than merging with it, which is crucial for correct invocation.

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

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

The description clearly states the verb and resource: 'Update the labels of a DNS zone', and immediately clarifies the critical semantic that the given set replaces all existing labels. This distinguishes it from the many sibling change_zone_* tools by explicitly naming them as the route for other zone properties.

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 explicit context on scope: it is for labels only, and other zone properties should go through the dedicated change_zone_* tools. This effectively routes the agent away from alternatives, though it does not provide explicit 'when not to use' conditions beyond the labels-vs-other-properties distinction.

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