hcloud_zone_rrset_change_ttl_action

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

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, so safety is covered. The description adds real value beyond them with the primary-mode restriction and the specific 422/incorrect_zone_mode failure. It does not explain that the call is asynchronous, what the resulting action contains, or what happens to records when TTL changes.

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 sentence, and the error table is well-scoped to operation-specific failures. Minor redundancy: the second sentence largely restates the first, and the [#tag/...] anchor markup is noise for an agent.

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

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

For a 5-param mutation tool with full annotation coverage and 80% schema documentation, the description supplies the key precondition and the mode-specific error. The main gap is return behavior – no output schema exists, and the presence of a 'wait' polling parameter is left for the schema to explain.

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 80% and the ttl field already documents its range, default behavior and fallback to the Zone's default TTL, so the description need not repeat it. The description contributes nothing parameter-specific, which is acceptable at this coverage but not more than baseline.

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

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

The description names a specific verb+resource pair (change the TTL of an RRSet), which is clearly distinct from the zone-level TTL sibling hcloud_zone_change_ttl_action and from record-manipulation siblings like hcloud_zone_rrset_set_records_action. It does not explicitly name or route against those alternatives, keeping it below a 5.

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

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

It gives one genuine applicability constraint – 'Only applicable for Zones in primary mode' – which is useful routing context. But there is no guidance on when to pick this over hcloud_update_zone_rrset or the zone-level TTL tool, and no prerequisites beyond mode.

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