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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds that it hits POST /firewalls/{id}/actions/apply_to_resources and that the firewall may be selected by id or name, but it never says what the mutation actually does to existing firewall assignment on the server (replace vs. append) or what permissions are needed.

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, no filler, and the core action is front-loaded before the implementation note. Nothing here could be cut without losing information.

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

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

For a 3-parameter mutation with no output schema and a sibling that overlaps almost entirely, the description is thin: it omits replacement semantics, the id/name mutual-exclusivity rule, and why to pick this over hcloud_firewall_apply_to_resources_action. The endpoint reference is useful but is implementation trivia rather than agent-facing guidance.

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 0%, so the description must compensate, and it partially does by clarifying the id-vs-name selector for the firewall. It does not clarify that server_id and the firewall selector are separate concerns, nor whether firewall_id and firewall_name are mutually exclusive or which wins if both are supplied.

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 firewall ... to a server") and even names the underlying API endpoint. It does not differentiate from the sibling hcloud_firewall_apply_to_resources_action, which performs the same POST against arbitrary resources, so an agent has to infer the scoping difference.

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

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

No when-to-use guidance, no prerequisites, no exclusions. The presence of hcloud_firewall_apply_to_resources_action (a near-identical sibling) makes the missing routing guidance a real gap — nothing says to prefer this one when targeting a single server.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so safety profile is covered. The description adds meaningful context beyond that: the state preconditions and a table of operation-specific errors (e.g. `dns_zone_not_found`, `caa_record_does_not_allow_ca`) that tell the agent what failure outcomes mean. It does not describe whether a successful retry mutates the certificate's status or how the action is queued, 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?

Purpose and preconditions are front-loaded in the first two sentences, which is ideal. The error table adds bulk, but it is structured and directly relevant to diagnosing retry failures 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?

For a mutation tool with no output schema and fully covered parameters, the description supplies the key operational constraint (managed + failed) and the known error surface. What's missing is minor: no statement of required permissions or what the returned action represents, but nothing critical for correct invocation 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 both `id` and `wait` are fully documented in the schema. The description adds no parameter-level meaning beyond that, 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?

States a specific verb ('Retry') and resource ('Certificate issuance or renewal') with the exact scope of the operation. An agent can distinguish this from sibling tools like hcloud_get_certificate_action or hcloud_update_certificate 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?

Provides explicit preconditions: only applicable when the Certificate type is `managed` and the issuance/renewal status is `failed`. This is a clear when-to-use gate that prevents misuse, even though it doesn't name an alternative sibling for the non-failed 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 cover the safety profile (readOnly=false, destructive=false, openWorld=true), so the description's job is added context — and it delivers: managed certs are renewed automatically with email alerts, issuance is asynchronous and trackable via the response `action`, and `action` is always null for uploaded. It does not discuss failure modes or what happens if issuance fails, which keeps it short of 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?

Front-loaded with the core action, then mode-specific detail in a logical order. Slight waste in the duplicated 'Create a Certificate / Creates a new Certificate' opener, but the remaining sentences each carry real 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?

No output schema exists, and the description compensates by explaining the shape of the response's `action` field for both modes. Combined with mode requirements and renewal semantics, an agent has everything needed to construct a valid call and interpret the result.

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?

Goes beyond the schema's per-field 'Required for type X' notes by explaining the trade-off between the two types and the consequences of each (PEM upload + self-managed renewal vs Let's Encrypt issuance restricted to Hetzner DNS domains). It adds little for `name`, `labels`, and `wait`, which the schema already documents.

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 Certificate') and immediately splits the operation into its two distinct modes, uploaded vs managed, so an agent understands not just what it creates but which variant it is creating. The resource name cleanly separates it from the many get_/list_/update_/delete_ certificate 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?

Explicitly contrasts the two modes and the conditions selecting each: uploaded requires you to monitor expiration and renew yourself, managed requires domains hosted on Hetzner DNS. That is strong when-to-use guidance for the mode decision, though it gives no guidance on when to call this versus hcloud_update_certificate or hcloud_certificate_retry_action.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the mutation profile is covered. The description adds genuine value beyond that with a table of operation-specific 422 errors (server_already_added, incompatible_network_type, firewall_resource_not_found), which tells an agent what failure modes to expect. It still omits what the call returns, whether the firewall is created unattached, and any auth/permission context.

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

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

The error table is compact and useful, but the opening two lines ('Create a Firewall' followed by 'Create a Firewall') are pure duplication with no informational payload. The useful content (error codes) is not 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 create tool with a deeply nested body and no output schema, the description should at minimum say what is created and returned and how the firewall is attached. It covers failure modes well but leaves the success path and the apply_to attachment behavior entirely to 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?

Top-level schema description coverage is 0% — the single 'body' parameter has no description — and the description does not compensate by explaining the request body at all (name uniqueness, rules limits, apply_to semantics). The nested properties are well documented in the schema itself, but the description contributes nothing about parameters.

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

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

The description states a specific verb and resource ('Create a Firewall'), which is unambiguous against the many get/list/update siblings. However, the first two lines merely restate the tool name and title, and there is no explicit differentiation from related creation tools (hcloud_create_network, hcloud_create_server) or from hcloud_firewall_set_rules_action.

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

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

There is no guidance on when to use this tool versus alternatives such as hcloud_apply_firewall_to_server or hcloud_firewall_apply_to_resources_action, and no prerequisites are mentioned. Usage is only implied by the verb 'Create'.

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 write behavior (readOnlyHint=false), non-destructiveness, and open-world scope. The description adds lifecycle context: assignment can happen later and routing is optimized in the home location. It omits cost, quota, idempotency, and failure behavior.

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

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

The purpose is front-loaded, but the opening 'Create a Floating IP' is repeated as 'Create a [Floating IP]' and the many long markdown links make it noisier than needed. The substantive guidance is still reasonably compact.

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

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

For a creation tool with a nested body and no output schema, the description covers the core assignment model but leaves out the required `type` choice and wait behavior. Annotations cover safety, but an agent still needs the schema for key creation decisions.

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

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

The description adds meaning for `server` and `home_location`, including later assignment and routing implications. It never mentions the required `type` enum or `wait`, so it only partially compensates for the 50% schema description 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 'Create a Floating IP' with a specific verb and resource, so the operation is immediately identifiable. It does not explicitly distinguish itself from siblings such as hcloud_create_primary_ip or hcloud_update_floating_ip.

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

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

Explains conditional use of `server` versus `home_location` and notes that later assignment is possible, which gives some contextual guidance. It does not state when to choose floating IP creation over alternatives like primary IP creation, nor any exclusions.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the agent knows this is a non-destructive write operation. The description adds useful operation-specific errors, but it does not explain creation behavior, idempotency, required permissions, or what the 'wait' parameter actually changes beyond the schema.

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

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

The first two lines are redundant ('Create a Load Balancer' / 'Creates a Load Balancer'), wasting the only prose sentence on a restatement. The bulk of the description is an error table with no front-loaded explanation of what the tool does or how to call it correctly.

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 creation tool with nested targets, services, and health checks, the description provides only API error codes. It omits prerequisites, core creation semantics, how the wait parameter behaves, and any integration guidance with sibling tools like hcloud_load_balancer_add_target_action or hcloud_load_balancer_add_service_action.

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 is deeply documented for nested properties, with descriptions for fields like name, labels, network, targets, services, algorithm, and public_net. The description itself contributes no parameter meaning beyond the schema. At 50% schema description coverage, the schema still carries most of the semantic load, so a 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 is essentially a tautology: 'Create a Load Balancer' followed by 'Creates a Load Balancer.' It restates the tool name and title without adding scope, distinguishing it from siblings like hcloud_list_load_balancers or hcloud_update_load_balancer, or clarifying what a load balancer creation entails.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisites (e.g., required permissions, network/location constraints), and no exclusions. The operation-specific error table is not usage guidance; it only lists API failure cases.

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, openWorldHint=true), so the description's job is to add context — and it does: it discloses the key lifecycle constraint that `ip_range` can only be extended later, never reduced, which is a genuine irreversibility trait an agent should know before calling. It stops short of covering auth/permission needs or that creation is asynchronous and returns an action.

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 paragraphs, front-loaded with the verb+resource, followed by the constraints that matter most at call time and cross-links to the follow-up actions. No filler, and each sentence carries a distinct constraint or pointer.

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

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

For a single-`body` create tool with no output schema, the description covers the immutability of `ip_range` and the subnet default, which are the highest-value gaps. It does not mention that the call is asynchronous / returns an action to poll (relevant given hcloud_wait_action exists in the sibling set), nor any permission requirements, leaving the agent to infer the post-create workflow.

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?

Top-level schema description coverage is reported at 0% (the `body` wrapper is undescribed), but the nested properties are richly documented in the schema itself. The description adds real semantics on top: the extend-only rule for `ip_range`, and the default that an unspecified subnet `ip_range` gets the first available /24 — the latter is not present in the schema. It leaves name, labels, routes objects, vswitch_id and expose_routes_to_vswitch entirely to the schema, so a 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 and resource ("Create a Network"), so an agent can immediately distinguish it from hcloud_get_network, hcloud_update_network, hcloud_list_networks and hcloud_delete_network by name alone. The opening line is somewhat redundant ("Create a Network" followed by "Creates a [Network]"), and there is no explicit sibling routing, which keeps 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?

Usage is implied through the references to the add-subnet and add-route actions, telling the agent this is the creation entry point and later modifications go elsewhere. However, it never says when to prefer this over alternatives, nor states prerequisites or what happens on conflicts (e.g., duplicate names / overlapping ranges).

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, and the description adds no behavioral context beyond them — no note about quota limits, what action is polled by the `wait` flag, or what is returned. There is no contradiction with annotations, but the description contributes nothing extra.

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?

It is short and front-loaded, but the second line merely restates the first, so one of the two sentences does not earn its place. Brevity here comes at the cost of substance rather than from efficiency.

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

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

For a create/mutation tool with a nested request body, no output schema, and only 50% parameter coverage, the description omits what happens on success, whether the call is synchronous or action-based, and any resource semantics. Annotations cover the safety profile, but the definition is not complete enough for confident invocation.

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

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

Schema description coverage is only 50%: the nested body fields are documented in the schema, but the description adds zero meaning to any parameter — including the `wait` flag's polling semantics and the enum-restricted `type`. For a mutation tool with partial coverage, the description should compensate and does not.

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

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

The description states a concrete verb and resource ("Creates a new Placement Group"), which distinguishes it from the delete/get/list/update placement-group siblings. However, the two lines are essentially the tool title repeated and never say what a Placement Group is or what it does (e.g., spreads servers to avoid co-location), leaving the resource itself unexplained.

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

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

There is no guidance on when to create a placement group versus other resources, no prerequisites (project/permission context), and no mention that only the "spread" type is currently supported. The agent is told nothing about the conditions under which this tool is the right 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?

Beyond the annotations (which only declare non-destructive, open-world mutation) the description discloses operation-specific failure modes — server_not_stopped, server_has_ipv4, server_has_ipv6 — and the same-Location assignment constraint, which an agent could not infer from structured fields. It doesn't cover return shape or the wait/polling behavior, so not a 5.

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

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

The core content is front-loaded and the error table is genuinely useful, but the prose is bloated by repeated '[Primary IP](#tag/primary-ips)' link markup that adds no information for an agent. Several sentences restate the same location-required rule already present in 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 mutating create with a nested request body, no output schema, and two top-level params, the description covers the creation rules, assignment prerequisites, and error conditions an agent needs. Missing only return-value expectation and the meaning of the `wait` polling flag.

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 50%, and the description mostly restates what the schema already says about `location` and `assignee_id`/`assignee_type` (ID-or-name, omit when unassigned). It adds no new semantics for `name`, `labels`, `auto_delete`, or the `wait` flag, so it only partially compensates 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?

States a specific verb and resource ('Create a new Primary IP') and immediately qualifies the creation semantics (assigned vs unassigned). It is distinguishable from the many other create_* siblings, though it never explicitly contrasts with hcloud_create_floating_ip, the closest alternative.

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

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

Gives clear conditional guidance: an IP can be assigned via assignee_id/assignee_type, otherwise `location` is required, and a later assignment is restricted to the same Location. It omits explicit when-not-to-use/alternative routing (e.g. floating IP), so it falls 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 it is a non-read-only, non-destructive, open-world mutation, and the description adds real value beyond that: it states the return shape (preliminary Server info plus an Action object tracking creation progress) and enumerates operation-specific error codes such as primary_ip_version_mismatch (412) and placement_error (422). It does not explain the async action lifecycle in detail or what happens on partial failure, which keeps it below 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?

The core sentence is front-loaded and the error table is compact, high-signal content rather than prose padding. The redundant 'Create a Server' heading restates the tool name, a minor waste, but overall the definition is tight.

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

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

For a create tool with a deep nested body (20+ properties), no output schema, and high open-world impact, the description covers return shape and error modes but omits prerequisites, whether creation is billed or irreversible, and how the returned Action should be polled (the wait flag is only documented in the schema). This leaves meaningful gaps for an agent composing a correct call.

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

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

Schema description coverage is reported at 50%, and the description adds no parameter-level information at all — it never explains the top-level body/wait split or the meaning of the wait flag. However, the nested body properties are individually well documented in the schema (name RFC 1123 constraint, user_data 32KiB limit, IP enable flags), so the effective gap is modest; a 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 opens with a specific verb and resource ('Creates a new Server') and the input schema's required fields (name, server_type, image) confirm the scope. It is clearly distinguishable from sibling create tools such as hcloud_create_volume or hcloud_create_load_balancer, though it never explicitly contrasts itself with them.

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

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

There is no guidance on when to use this tool versus alternatives, no stated prerequisites (e.g. that the referenced Image, Server Type, Location, or Networks must already exist), and no mention of permissions or quota implications. The only context is the error table, which explains failures rather than when to call the tool.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the useful lifecycle note that the key becomes reusable by other calls, but says nothing about name uniqueness/conflict behavior, whether labels are persisted, or what the mutation returns.

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

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

Two short sentences, front-loaded with the action; the restated title line is mild redundancy but nothing is padded. It earns most of its space.

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 and no annotations gaps to fill, so the description should explain the mutation's outcome and payload shape. It covers the lifecycle but omits response contents, label handling and duplicate-name behavior for a nested-object mutation 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 reported as 0%, and the payload is a nested 'body' wrapper, so the description must carry the load. It names only 'name' and 'public_key', adds no format expectations for the public key (e.g. ssh-rsa/ed25519 prefixes) and ignores the 'labels' field entirely.

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

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

States a specific verb and resource ('Create an SSH key') and names the two required fields. It is distinguishable from hcloud_delete_ssh_key and hcloud_update_ssh_key by the verb, but it never explicitly references siblings or scope (project-wide vs. per-key uniqueness).

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 sentence 'Once an SSH key is created, it can be used in other calls such as creating Servers' gives downstream context and implies when to call it. There is no explicit when-not guidance, no prerequisites, and no mention of how this differs from hcloud_list_ssh_keys or hcloud_get_ssh_key.

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

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

Annotations cover the safety profile (destructiveHint=false, openWorldHint=true), and the description adds real behavioral context beyond that: automatic attachment after initialization, the `next_actions` array containing a single `attach_volume` action, and the 422 `no_space_left_in_location` error. It omits the meaning of the `wait` polling parameter and whether creation is idempotent, keeping it short of 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?

Content is front-loaded with the core create-and-attach behavior, then constraints, then an error table; nearly every sentence carries information. Slightly verbose in the naming-rules paragraph, but 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 creation tool with no output schema, the description covers the attach semantics, the response's `next_actions` hint, size/name constraints, and a documented error case. The gaps are the polling semantics of `wait` and post-creation state, but nothing critical for a 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 50%, and the description adds genuine value for `server` vs `location` (mutually substitutable, same-Location constraint) and for `size`/`name` (range, charset, uniqueness per Project). However, `format`, `automount`, and `labels` are left entirely to the schema, so it only partially compensates 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?

Specific verb + resource (create a Volume) with the key nuance that the Volume can be created attached to a Server or standalone in a Location. This implicitly distinguishes it from sibling hcloud_volume_attach_action, which attaches an already-existing Volume, though it never names that sibling explicitly.

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

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

Explicitly states the condition that selects each mode: provide `server` to create-and-attach, or `location` instead for a detached Volume, plus the constraint that the Volume must be in the same Location as the Server. It gives hard limits (10GB–10TB) and naming rules, but does not route the agent to alternatives such as volume_attach_action or volume_resize_action.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds genuinely useful behavior beyond them: the automatic creation of an SOA record and three NS records with Hetzner nameservers. It does not mention whether the call is idempotent, what happens on name collisions, or what the wait parameter's polling does, but the auto-provisioning disclosure is real added value.

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 lines, front-loaded with the operation and followed by the most important side effect. The one inefficiency is the duplicated opening ("Create a Zone" then "Creates a [Zone]"), which wastes a line without adding 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 creation tool with no output schema and rich nested input, the description covers what is created but not what is returned, nor the primary/secondary mode split that governs most optional parameters. Adequate to call the tool, but incomplete on the behavior an agent would want to confirm success.

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

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

With schema description coverage at 50%, the nested schema still documents body fields (ttl, mode, name, labels, rrsets, zonefile, primary_nameservers) and wait thoroughly, so the baseline of 3 applies. The description adds nothing about the mode-dependent mutual exclusivity of rrsets/zonefile versus primary_nameservers, nor about wait, 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?

States a specific verb and resource ("Create a Zone") plus a concrete side effect (default SOA and three NS records created automatically), so an agent knows exactly what the call produces. However, the first two lines are near-tautological ("Create a Zone" / "Creates a Zone") and it never differentiates itself from siblings such as hcloud_import_zonefile_action or hcloud_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?

No statement of when to use this versus alternatives, no prerequisites (e.g., that mode must be chosen and that rrsets/zonefile only apply to primary zones), and no mention of when not to use it. The agent must infer all routing decisions from the name and schema.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is known. However, the description adds zero behavioral context — no note on irreversibility, dependent resources, confirmation requirements, or what happens to certificates in use. It merely repeats the 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?

The description is two near-identical fragments ('Delete a Certificate' / 'Deletes a Certificate'), wasting the only sentence available on duplication rather than useful content. It is short but not efficient.

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

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

For a destructive one-parameter mutation with no output schema, the description should at minimum say what deletion entails and any failure/constraint conditions. With no annotations gap to compensate for on safety, the absence of any such detail leaves the definition incomplete.

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

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

Only one parameter (id) exists and schema description coverage is 100%, with the schema itself stating 'ID of the Certificate.' Baseline 3 applies since the schema fully documents the input and the description need not elaborate.

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 text is a near-tautology: 'Delete a Certificate' restated as 'Deletes a Certificate.' While the verb and resource are identifiable, the description adds nothing beyond the tool name and does not differentiate from the many sibling delete tools (hcloud_delete_firewall, hcloud_delete_zone, etc.) or say what distinguishes deleting a certificate.

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

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

No when-to-use, when-not-to-use, or alternative guidance is given. It does not mention prerequisites (e.g., certificate must not be attached to a load balancer) or point to hcloud_list_certificates for discovering IDs, so the agent gets no routing help beyond the name.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that by documenting the one operation-specific failure mode: a 422 when the firewall is still applied to a resource, which tells the agent it may need a detach step first. It does not state whether deletion is immediate/permanent or how the async action is polled.

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

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

Very short and front-loaded: the first line states the action, then the error table. Some text is redundant ('Delete a Firewall' / 'Deletes the Firewall') and the anchor-link markup is noise, but overall it is tight and well ordered.

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

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

For a one-parameter destructive delete with full annotation coverage and no output schema, the definition supplies the essential extra context (the resource_in_use failure). Missing only confirmation of irreversibility/async completion, which are minor given the destructiveHint annotation.

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?

Single required parameter with 100% schema description coverage ('ID of the Firewall.'), so the schema already carries the semantics. The description adds nothing about identifier sourcing (e.g., from hcloud_list_firewalls) or what happens with an invalid/missing ID, so baseline 3 applies.

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

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

States a specific verb and resource ('Delete a Firewall', 'Deletes the [Firewall]'), which is unambiguous against the many get_/list_/update_ firewall siblings. It does not explicitly distinguish itself from the nearby hcloud_firewall_remove_from_resources_action, which an agent could plausibly confuse with 'removing' a firewall.

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

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

There is no explicit 'use this when…' sentence and no named alternative, but the 422 resource_in_use error implicitly signals the prerequisite (the firewall must first be detached from all resources via the remove-from-resources action). That is useful implied guidance rather than stated 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 destructive=true and openWorldHint=true, so the description earns credit by adding the temporal unassignment behavior and the exact 422 must_be_unassigned failure condition. That is meaningful behavioral context beyond what the structured annotations provide.

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 content is front-loaded and logically ordered, with the critical caveat placed before the error table. However, 'Delete a Floating IP' and 'Deletes a Floating IP' restate each other, and the repeated markdown anchor links add some visual noise.

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

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

For a one-parameter destructive tool with annotations and no output schema, the description covers the main side effect and failure mode sufficiently. An agent has what it needs to call it correctly and interpret the likely error.

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

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

There is a single required id parameter and schema description coverage is 100%, so the schema fully documents it. The description adds no additional parameter syntax or meaning, making 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 first line and body both state a specific verb ('Delete') and resource ('Floating IP'), which clearly separates it from the many other delete_* siblings by resource. The only weakness is minor restatement between the title-like first line and the body.

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 the key context for when the call succeeds or fails: an assigned IP is auto-unassigned until 1 May 2026, after which deletion requires unassignment first. It does not explicitly name hcloud_floating_ip_unassign_action as the preferred alternative, 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 already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds a valuable behavioral constraint about allowed Image types, but it does not mention irreversibility, dependency handling, or what happens on an invalid delete request.

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 very short and front-loaded: it leads with the action and then immediately states the Image-type restriction. No sentence is wasted.

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

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

For a destructive single-parameter delete tool with annotations covering safety, the description is mostly adequate because it states the allowed Image types. However, it omits irreversibility and in-use/dependency behavior, leaving meaningful gaps for a destructive operation.

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

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

Schema coverage is 100% and the sole `id` parameter is fully described in the schema. The description adds no parameter-level meaning beyond what is already structured, so the baseline score of 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: delete an Image. It does not explicitly differentiate itself from siblings like hcloud_update_image or hcloud_list_images, but the delete action is unambiguous.

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

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

It provides a concrete eligibility condition: only Images of type `snapshot` and `backup` can be deleted. It does not name alternatives or elaborate on when not to delete, but the key usage boundary is explicit.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered elsewhere. The description adds nothing beyond that: it does not say the deletion is irreversible, what happens to attached targets/services, whether deletion protection blocks it, or that an async action results (relevant given the 'wait' parameter).

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

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

Extremely short, but the second sentence is a verbatim restatement of the first and of the tool name, so no sentence earns its place beyond the first line.

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

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

For a destructive two-parameter tool with no output schema, the annotations and schema carry most of the burden, but the description leaves real gaps: irreversibility, the asynchronous action/polling semantics tied to 'wait', and any deletion-protection prerequisite are unstated.

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

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

Schema description coverage is 100%, with 'id' and 'wait' fully documented in the schema, so the baseline of 3 applies. The description contributes no additional meaning about the id or the polling behavior of 'wait'.

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 text only restates the tool name twice: 'Delete a Load Balancer' followed by 'Deletes a Load Balancer.' There is no added scope, no mention of what a Load Balancer is here, and no differentiation from the many sibling delete_* tools beyond the name itself.

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

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

No guidance on when to use this versus alternatives such as hcloud_update_load_balancer, detaching targets first, or whether deletion protection must be disabled. The agent must infer all preconditions on its own.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known; the description nonetheless adds real behavioral value by stating that attached resources are detached automatically rather than blocking the delete. It stops short of saying whether the delete is irreversible, which resources are considered 'attached', or whether an async action is returned.

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

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

Very short and front-loaded, but the title line 'Delete a Network' and the body sentence 'Deletes a [Network](...)' are redundant restatements. Only the third sentence carries new information, so one of the three does not earn its place.

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

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

For a one-parameter destructive tool with no output schema, the description covers the core side effect (auto-detachment) but omits irreversibility and the shape of the response — the sibling presence of hcloud_get_network_action suggests deletion may return an asynchronous action, which is never mentioned.

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 single parameter 'id' is fully documented in the schema (100% coverage, with type, range, and example), so the schema carries the load. The description adds no meaning about how to obtain the ID or what happens if the ID is stale/not found, so baseline 3 applies.

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

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

Clear specific verb+resource: deletes a Network, identified by ID. An agent can distinguish it from hcloud_get_network, hcloud_update_network, and hcloud_create_network by name alone, but the description never explicitly contrasts with the network-scoped siblings (subnet/route deletion actions) or warns against using it when only a subnet should go.

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

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

There is no explicit when-to-use / when-not-to-use guidance and no mention of alternatives such as hcloud_network_delete_subnet_action or hcloud_network_delete_route_action for partial cleanup. Usage is only implied by the word 'Delete' and the auto-detach note.

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

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

The annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is known without the description. The description adds nothing beyond that: it does not say the deletion is irreversible, what happens to member servers, or whether the call fails when the group is still in use. For a destructive mutation, that is a real gap even though the baseline bar is lower.

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 short, but its second sentence is a verbatim restatement of the first, so it does not earn its place. Being under-specified rather than concise is its main problem; it conveys no information beyond the tool name repeated twice.

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 destructive resource-deletion tool with no output schema; the description should therefore cover irreversibility, preconditions, and the effect on dependent resources. None of these topics are addressed, so an agent has to guess about consequences that the structured fields do not capture.

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

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

There is a single parameter, id, whose schema description ('ID of the Placement Group.') has 100% coverage and includes type, format, example, and bounds. By the baseline rule, a 3 is appropriate: the schema does all the work, and the description adds no identifier semantics such as whether it is the numeric ID or the name.

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 only restates the tool name: 'Delete a PlacementGroup / Deletes a Placement Group.' The verb and resource are identifiable, but it gives no more information than the name already does. Because the name is prefixed with hcloud_ and followed by the resource, an agent can distinguish this tool from siblings such as hcloud_delete_server or hcloud_delete_network from the name alone; the description adds nothing to that distinction.

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

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

The description contains no statement about when to use this tool, when to avoid it, or which alternatives exist. It does not mention that the Placement Group must be empty, that servers assigned to it must first be removed (hcloud_server_remove_from_placement_group_action), or when to use hcloud_list_placement_groups first. No context is given beyond the bare action.

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

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

Adds substantial context beyond the destructive/openWorld annotations: the power-off prerequisite, the auto-unassignment grace period until 1 May 2026, and the specific 422 `must_be_unassigned` failure mode. That is exactly the kind of operational consequence an agent needs before invoking a destructive call.

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

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

The core action and the power-off prerequisite are front-loaded in the first two paragraphs, and the error table is genuinely actionable. However, the inline anchor links (#tag/primary-ips, #tag/servers) are noise that adds no information 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 single-parameter destructive delete with no output schema, the description covers the prerequisite, the transition-period behavior, and the specific error to expect. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100% and the single `id` parameter is already documented in the schema, so the description adds nothing about parameter meaning. Baseline 3 applies when the schema carries the full 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?

States a specific verb and resource ('Delete a Primary IP') with an unambiguous scope, and the body clarifies the precondition that distinguishes it from the assign/unassign siblings. It never explicitly names hcloud_primary_ip_unassign_action as the non-destructive alternative, 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 concrete usage context: the Server must be powered off (status `off`) for the operation to succeed, and the automatic unassignment behavior with its 1 May 2026 cutoff. It does not explicitly say when to prefer unassign over delete, which leaves the key decision to inference.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known, and the description adds genuinely new context: the deletion is immediate, the server becomes inaccessible, and attached resources (Volumes, Primary IPs, Floating IPs, Firewalls, Placement Groups) are detached as a side effect. That side-effect disclosure is exactly the extra value the description should provide. It falls short of 5 because it does not explain the consequence of detachment (whether IPs are released, whether volumes keep data) or how errors surface.

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 opening two lines are redundant, restating the tool name twice before any real content, which violates front-loading. The remaining sentence is dense and well-structured but carries awkward line breaks that add no 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 two-parameter destructive tool with no output schema, the description covers the essential consequences of invocation. The remaining gap is that it never ties in the 'wait' parameter or explains what happens on failure, though the schema handles the former.

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

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

Schema description coverage is 100%, with both 'id' and 'wait' documented inline, including the default and polling semantics of 'wait'. The description adds nothing about either parameter, which is acceptable but not additive under a fully covered 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 names a specific verb and resource (delete a Server) and is unambiguously distinguishable from the many sibling delete_* tools for other resources. However, the header plus the first body line ('Deletes a Server.') is a pure restatement of the name, so the real information only starts in the third sentence.

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 never says when to delete versus when to use an alternative such as hcloud_server_poweroff_action, hcloud_server_rebuild, or other lifecycle tools, nor does it state prerequisites like server protection being disabled first. The only guidance is an implicit permanence warning, which is inferred rather than stated.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the danger profile is known. The phrase "It cannot be used anymore" adds a small amount of post-condition context, but the description never says the deletion is irreversible, what happens to servers currently referencing the key, or what errors can occur.

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?

It is short and front-loaded, but the second sentence restates the first ("Delete" / "Deletes") and the only new information is the trailing consequence clause. Wasted duplication in a four-word description is a real cost.

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

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

For a destructive single-parameter operation, annotations and the schema cover safety and input, so the description is minimally sufficient. It still omits the operational consequences an agent would want before calling a delete: irreversibility, in-use constraints, and error conditions.

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

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

Only one parameter exists and schema coverage is 100%, with the schema already documenting `id` as "ID of the SSH Key" plus type and bounds. The description adds nothing about the identifier, which is acceptable given the schema does the work, but it is baseline rather than additive.

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 ("Delete an SSH key") and the tool name already separates it from create/update/get/list siblings. However, it offers no explicit differentiation text, and the second sentence largely repeats the first rather than sharpening 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?

There is no guidance on when to delete versus update, rotate, or detach a key, and no prerequisites such as whether the key must be unused by any server first. The agent must infer all of this from the tool name alone.

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

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

Annotations already declare destructiveHint=true, but the description adds valuable context beyond them: that all data is irreversibly destroyed and the two preconditions that cause failure. It does not describe error behavior when preconditions are unmet, but the added irreversibility and gating conditions are solid.

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

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

Front-loaded with the action and destructiveness. Minor redundancy between the title line 'Delete a Volume' and 'Deletes a volume', but the whole is short and every substantive 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 single-parameter destructive delete with full annotation coverage and no output schema, the description supplies everything needed to call it correctly: the id role is schema-documented, and the preconditions and irreversibility are spelled out.

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

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

Only one parameter (id) with 100% schema description coverage, so the schema already documents it fully. The description adds no syntax or format detail, which is acceptable given high coverage – baseline 3 applies.

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

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

States a specific verb and resource ('Delete a Volume') that unambiguously identifies the operation among the many hcloud siblings. An agent can immediately tell this is the volume-deletion tool.

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

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

Explicitly states preconditions for use: the volume must not be attached to a Server and must not have delete protection enabled. It does not name alternative tools (e.g. hcloud_volume_detach_action or hcloud_volume_change_protection_action) that would unblock those conditions, so it stops short of 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 destructiveHint=true and openWorldHint=true, so the safety profile is covered structurally. The description adds nothing beyond that: it never states that the deletion destroys all records in the zone, whether it is reversible, or how the `wait` polling parameter affects the call's behavior.

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

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

It is short and front-loaded, but the second sentence is a pure restatement of the first with a link, so not every sentence earns its place. The size is fine; the redundancy is the flaw.

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 should warn that all rrsets inside the zone are removed and note any protection/irreversibility concerns. It supplies none of that, leaving the agent dependent entirely on the destructiveHint annotation.

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

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

Schema description coverage is 100%, so both `id_or_name` and `wait` are already documented structurally. The description adds no extra meaning (e.g. accepted name formats, or what happens when `wait` is false), 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 first sentence names a specific verb and resource ("Delete a Zone"), which is clearly distinguishable from siblings like hcloud_delete_zone_rrset or hcloud_update_zone. The second sentence only restates the same fact with a doc link, so no additional differentiation is offered.

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

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

There is no guidance on when to use this versus alternatives (e.g. hcloud_delete_zone_rrset for individual records) and no prerequisites, such as whether zone protection blocks deletion. The agent must infer everything from the name.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real value beyond them: the primary-mode-only restriction and the specific 422 error code the agent should expect. It does not explain that the delete is permanent/irreversible in prose or what a successful response/action looks like, 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?

The core action and the scope restriction are front-loaded in the first two sentences, with the error table serving a clear purpose. The markdown anchor links (#tag/zone-rrsets, #tag/zones) add minor noise for an agent consumer but do not impede comprehension.

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

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

For a 4-parameter destructive zone operation with no output schema, the description supplies the essential gate (primary mode) and the failure signature. Missing pieces are minor: whether deletion is idempotent when the RRSet is absent, and what the 'wait' flag does on a delete (action polling vs. immediate return).

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%, including detailed rules for rr_name (lowercase, Punycode, '@' for apex) and an enum for rr_type, so the schema does the heavy lifting and baseline is 3. The description adds no parameter-level meaning, notably silent on the 'wait' parameter's polling behavior, which is the one field whose semantics are not fully spelled out.

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 ('Delete an RRSet') and immediately scopes it ('from the Zone'). It is clearly distinguishable from hcloud_update_zone_rrset, hcloud_post_zone_rrsets, and the record-manipulation siblings (add/remove/set records), which modify contents rather than remove the RRSet itself.

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 line 'Only applicable for Zones in primary mode' is an explicit precondition that rules out secondary-mode zones, reinforced by the 422 incorrect_zone_mode error row. It does not name an alternative tool (e.g., for secondary zones), so it stops short of full when-to-use routing, but the exclusion criteria are clear.

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

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

Goes well beyond the destructiveHint/openWorldHint annotations: it discloses the 5-firewall-per-server cap (including selector-matched ones), a few-second propagation delay for label-selector changes, and the async completion model (applied only once the apply_firewall Action succeeds). It also lists operation-specific failure codes such as firewall_already_applied and private_net_only_server, which an agent can act on.

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 content is front-loaded and substantive (limits, timing, async, errors), but repeated inline anchor markup such as '[Firewall](#tag/firewalls)' appears a dozen times and dilutes readability. The error table is valuable but makes the block heavier than necessary for a two-parameter call.

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 definition covers the async action model, the resource constraints, and the failure modes an agent must handle. The remaining gap is the absence of any note that removal requires the sibling remove action, or how to verify the applied state afterwards.

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 50%, and the description only reinforces the resource-type side (servers with a public interface, label selectors) plus the 'extends' semantics of apply_to. It adds nothing about the required firewall `id` or the selector string format, so the schema still carries most of the 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?

States a specific verb and resource: applies a Firewall to multiple resources, and enumerates the supported resource kinds (servers, label selectors). The 'multiple resources' phrasing implicitly separates it from the single-server sibling hcloud_apply_firewall_to_server, but that sibling is never named.

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

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

Supported resource types and the 'Extends existing resources' semantics are given, which implies when the tool is appropriate. However, there is no explicit routing guidance against the obvious alternative (hcloud_apply_firewall_to_server for a single server) or against hcloud_firewall_remove_from_resources_action, so the agent must infer the choice.

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 behavior the annotations do not carry: removal is asynchronous and only complete once the related Action with command `remove_firewall` finishes, plus a table of operation-specific 404/422 errors. Annotations already declare destructiveHint=true and openWorldHint=true, so this additional lifecycle context is genuine added value. It stops short of stating what the call returns (presumably an Action object) or that the action must be polled.

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 sentence and supported-resource list come first, followed by the async semantics and an error table, which is a sensible front-loaded order. There is minor waste in the redundant H1-style title "Remove from Resources" that merely restates the tool name.

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

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

For a two-parameter nested body with no output schema, the description covers the mutation semantics, valid resource types, and failure modes well. The main remaining gap is the return contract (which Action is produced and how to poll it) and the fact that `label_selector` entries in `remove_from` are effectively unusable.

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 50%, so the description needs to compensate. It does clarify that resources are plural and that only `server`-type entries with a public interface are meaningful, which is useful given the schema enum also allows `label_selector`. However, it never explains the `id` field or the shape of the `remove_from` array, leaving the nested body to 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 ("Removes a [Firewall] from multiple resources") and constrains the target set to Servers with a public network interface. The purpose is unambiguous, but it never references the sibling hcloud_firewall_apply_to_resources_action, so the inverse operation has to be inferred from the tool name.

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 when-not conditions: only Servers with a public network interface are supported, and a 422 `firewall_managed_by_label_selector` means the firewall is applied via a label selector and cannot be detached manually. That is real routing guidance, though the description never explicitly points to the apply counter-tool for adding resources.

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 is covered structurally; the description adds the critical nuance that ALL existing rules are replaced and that an empty array wipes the rule set, plus hard limits (50 rules / 500 effective). It does not disclose async/action-return behavior or permission requirements, keeping it short of 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?

Four short sentences, front-loaded with the action itself and immediately followed by the destructive overwrite semantics. The final limits sentence is partially redundant with the `rules` schema description, which is the only waste.

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

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

For a destructive, nested-body mutation with no output schema, the description covers replacement semantics and limits but leaves out operational context an agent would want: that this returns an async action, that rules are enforced on attached servers, and that the firewall must already exist. Adequate but with clear gaps.

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

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

Schema coverage sits at 50%, but the nested `rules` schema is richly self-documented (protocol enums, source_ips vs destination_ips, CIDR notes). The description only adds the empty-array semantics and the count limits, so it is the minimum-viable complement rather than a compensator.

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: 'Set the rules of a Firewall', with a note on overwrite semantics. An agent can distinguish this from hcloud_update_firewall (metadata edits) by the wording, but no sibling is named explicitly, so differentiation is inferred rather than stated.

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

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

The description says the existing rules are overwritten and that an empty array clears all rules, which is essential usage context, but it never states when to prefer this over hcloud_update_firewall or when it is inappropriate (e.g. firewalls already applied to servers). Usage is implied rather than guided.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is covered. The description usefully adds the specific failure mode ('422 floating_ip_assigned'), but says nothing about the resulting async action, the `wait` polling behavior, or whether reassignment disrupts existing traffic.

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 and short overall, but the title is duplicated verbatim as the first sentence and the markdown link/table formatting is carried over from the API reference rather than written for an agent. Every sentence earns its place, though the styling does not.

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, open-world action with no output schema and a nested body, the description omits the async action semantics, the wait/timeout behavior, and the preconditions that make the 422 error occur. Adequate to attempt the call, incomplete for anticipating the result.

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?

At 67% schema coverage the description should compensate, but it adds nothing about `id`, `body.server` or `wait` beyond what the schema already says. The `wait` parameter's default polling behavior, the most consequential knob, is left entirely to the schema text.

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 line states a specific verb and resource ('Assign a Floating IP to a Server'), which is unambiguous and clearly the inverse of the sibling hcloud_floating_ip_unassign_action. It doesn't explicitly name or contrast with that sibling, but the operation is clear enough to select 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?

No guidance on when to use this versus hcloud_floating_ip_unassign_action or hcloud_update_floating_ip, and no prerequisites are stated (e.g. the IP must be unassigned, server residency constraints). The only hint is the 422 'floating_ip_assigned' error row, which implies a precondition rather than stating one.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so safety is partly covered. The description adds only a restatement that PTR records are modified and does not explain the destructive effect of resetting/removing records, the asynchronous action model, or how the wait parameter changes behavior.

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

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

The description is short, but it repeats the same idea three times: changing reverse DNS records for a Floating IP. It is front-loaded but not efficient.

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

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

For a destructive, open-world action with a nested request body and a wait/polling parameter, the description is too thin. Annotations cover the safety profile, but the description does not help an agent choose this tool over same-purpose sibling DNS-PTR actions or understand the mutation's operational behavior.

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% and the description adds no parameter-level meaning beyond the schema. It does not clarify the role of id, the nested body fields ip and dns_ptr, or the effect of wait.

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: changing reverse DNS/PTR records for a Floating IP. It does not distinguish this tool from sibling DNS-change tools such as hcloud_load_balancer_change_dns_ptr_action, hcloud_primary_ip_change_dns_ptr_action, or hcloud_server_change_dns_ptr_action.

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

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

There is no explicit guidance on when to use this tool versus the closely named sibling change_dns_ptr actions for load balancers, primary IPs, or servers. The resource type is implied by the name, but the description provides no exclusions, prerequisites, or alternative 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 this is a non-read-only, destructive, open-world action. The description adds little beyond that: it does not explain reversibility, permission requirements, or the practical effect of toggling delete protection.

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 short and front-loaded, with no wasted text. Its brevity is appropriate, though the second sentence is largely a restatement of the first.

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 a nested body and no output schema, the description is minimally adequate but leaves out usage context and behavioral details that would help an agent choose it confidently over related tools.

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

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

Schema description coverage is 100%, so the parameters are already well documented in the input schema. The description adds no additional parameter semantics, 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 states a specific verb and resource: changing protection settings for a Floating IP. It is clear what the tool does, but it does not distinguish this action from related siblings such as update_floating_ip or other protection-changing actions.

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

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

The description gives no guidance on when to use this tool versus alternatives, prerequisites, or when not to use it. It only states the operation, leaving routing decisions to the agent.

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

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

Annotations already declare destructiveHint=true, so the bar is lower; the description earns credit by stating the concrete consequence ('Results in the IP being unreachable') and that reassignment remains possible. It omits what happens if the IP is not currently assigned and whether it fails or is a no-op.

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?

Short and front-loaded with the action and its effect. There is minor redundancy between the heading 'Unassign a Floating IP' and the body 'Unassigns a Floating IP.'

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

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

With no output schema and annotations covering destructiveness, the description is largely sufficient but leaves gaps on preconditions (must the IP be assigned?) and on whether an action object is returned for polling via `wait` or hcloud_wait_action.

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

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

Schema description coverage is 100%, with both the floating IP id and the `wait` polling flag documented in the schema, so baseline 3 applies. The description adds no further semantics about either parameter.

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

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

The description names a specific verb and resource ('Unassign a Floating IP') and its behavior contrasts implicitly with the assign sibling. It does not explicitly name hcloud_floating_ip_assign_action as the counterpart, but the operation is unambiguous.

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

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

Usage is implied rather than stated: the note 'Can be assigned to another resource again' suggests the purpose is to free the IP for reassignment, but there is no explicit when-to-use/when-not guidance, no mention of preconditions, and no named 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?

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that — notably it never mentions that `wait` defaults to true and will poll until success/error or timeout, which is the one behavior an agent most needs to anticipate (blocking, latency).

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?

It is short and front-loaded, but the second sentence merely repeats the first in passive form, so the only two sentences in a two-line description are redundant. Brevity here reflects lack of content rather than discipline.

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 should say something about the returned Action object (fields, status values) and about the default polling behavior of `wait`. Instead it leaves an agent guessing on both, which is inadequate for a tool whose main behavior is a blocking poll.

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

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

Schema description coverage is 100% and both parameters (id, wait) are documented in the schema, so the baseline of 3 applies. The description mentions no parameter semantics at all — not even that IDs are global action IDs rather than resource-scoped.

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?

"Get an Action / Returns a specific Action object" restates the tool name and title without adding specificity. It gives no way to distinguish this generic action getter from the many sibling getters (hcloud_get_server_action, hcloud_get_load_balancer_action, hcloud_get_certificates_actions_id, hcloud_list_actions) that also return Action objects.

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

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

There is no guidance on when to use this versus hcloud_list_actions or the resource-scoped action getters, and no mention of the relationship to hcloud_wait_action. The agent must infer all routing decisions from tool names alone.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: no mention of error behavior for unknown IDs, permissions, or what fields a Certificate object carries. For a read tool the bar is lower, but this text contributes essentially no new behavioral context.

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

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

The text is short and front-loaded with the verb, but the second sentence merely paraphrases the first. It contains no waste in length yet also no information density – concise but under-specified.

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 single-parameter getter with full schema coverage, annotations, and no output schema, so the description needn't explain return values. Still, nothing tells the agent about sibling alternatives or failure modes, leaving the definition only barely sufficient for correct invocation.

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

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

Schema coverage is 100% and the single id parameter is documented with type, range, and example (42), so the schema does the explanatory work. The description adds no naming or formatting guidance beyond what the schema provides, making 3 the correct baseline.

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

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

"Gets a specific Certificate object" restates the tool name with modest added specificity (single object, not a list). It does not distinguish itself from close siblings such as hcloud_list_certificates, hcloud_get_certificate_action, or hcloud_update_certificate, so the agent must infer the boundary from the name alone.

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

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

There is no statement of when to use this tool versus hcloud_list_certificates or hcloud_get_certificate_action, and no prerequisites such as authentication or required ID source. The only implied guidance is the word "specific", which the required id parameter already conveys.

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, destructiveHint=false and openWorldHint=true, so safety is covered; the description adds lifecycle context (deprecation) and a functional restriction (managed-only actions) that annotations do not carry. It does not describe what an Action object contains or how the `wait` polling behaves on failure.

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

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

Three short, front-loaded blocks: the deprecation warning leads, then the purpose sentence, then the scope caveat. No filler; a reader can stop after the first line if deprecation is disqualifying.

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

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

The tool has no output schema, so the description should say anything about the returned Action (fields, status values, terminal states) but says nothing. Given the deprecation and managed-only caveats are present, it is adequate but leaves a real gap for a read tool whose return value is undefined.

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

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

Schema description coverage is 100%, so all three parameters (id, action_id, wait) are already documented in the schema; baseline 3 applies. The description adds only the indirect constraint that `id` must reference a managed Certificate, no syntax or format detail beyond the schema.

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

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

States a specific verb and resource: 'Returns a specific Action for a Certificate', and adds a meaningful scope constraint that only `managed` Certificates have Actions. It does not distinguish itself from the near-duplicate sibling hcloud_get_certificates_actions_id, leaving the agent to guess between them.

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

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

The Deprecated banner with a changelog link is an explicit 'do not use / migrate away' signal, and the managed-only note tells the agent when the call will yield nothing. It stops short of naming the replacement endpoint or sibling tool, so routing is implied rather than explicit.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only that results can be sorted and filtered, and hints at returning Action objects, but says nothing about pagination defaults, ordering guarantees, or response shape beyond the schema. Adequate but thin given the low bar set by annotations.

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

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

Two short sentences with no waste and the capability statement is front-loaded. It loses a point only because the first line ('List Actions') is redundant with the tool name and conveys no scoping 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 paginated list tool with no output schema, the description must at minimum establish what collection is being listed, and it fails: it claims to return 'all Action objects' when the tool is certificate-scoped. Combined with the absence of any return-format or pagination context, the definition is not sufficient for correct selection.

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

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

Schema description coverage is 100%, so the schema already documents id, status, sort, page, and per_page in detail. The description echoes sort/status/id but omits pagination parameters entirely and adds no syntax or semantics beyond the schema; baseline 3 applies.

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

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

The description opens with the generic boilerplate 'List Actions / Returns all Action objects' and never mentions certificates, so the resource scope implied by the tool name is absent from the text. With siblings like hcloud_list_actions, hcloud_list_certificate_actions, and hcloud_get_certificates_actions_id in the namespace, an agent cannot tell from the description which one this is or what it is scoped to.

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 says sorting and filtering are possible but gives no when-to-use guidance, no exclusions, and no pointer to the alternative tools that return the same Action objects at different scopes. The agent is left to infer that this is the certificate-scoped variant from the name alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds no behavioral context beyond that — it says nothing about what an Action object represents, whether the wait/polling behavior applies, or any error case for a non-existent action id.

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

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

The definition is only two short lines with nothing extraneous, and the operative statement comes first. The second sentence partially restates the first, but the overall brevity is appropriate for a single-resource getter.

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

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

With no output schema and a large, heavily duplicated sibling set of `*_action` getters, the description should at minimum scope this to certificate actions and point out how it differs from hcloud_get_action and hcloud_get_certificates_actions. It provides no such routing information, leaving the agent to guess from the name alone.

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

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

Schema description coverage is 100%, with both id ("ID of the Action") and wait ("Poll the resulting action until success/error or timeout") documented in the schema itself. The description adds no syntax or format detail beyond that, so the baseline of 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 gives a verb and resource ("Get an Action", "Returns a specific Action object"), so the basic operation is understandable. However, it does not distinguish this certificate-scoped lookup from the many near-identical siblings such as hcloud_get_action, hcloud_get_certificate_action, and hcloud_get_certificates_actions; the adjective 'certificates' in the tool name is never reflected in the text.

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

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

There is no statement of when to use this tool versus the alternatives in the toolset — nothing tells an agent to pick this over hcloud_get_action or the list-style hcloud_get_certificates_actions. Usage is only inferable from the tool name and the required id parameter.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context with the deprecation timeline and removal date, which affects whether an agent should rely on this tool at all.

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 deprecation warning, then the one-line purpose. Minimal waste, though 'Returns a single [Data Center](#tag/data-centers)' is thin and the anchor link adds little 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 single-resource read with full annotation coverage and a fully documented schema, this is close to sufficient. With no output schema, though, the description does not sketch the return shape beyond 'a Data Center', leaving the agent to guess at fields like location or server types.

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

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

Schema coverage is 100% and the single 'id' parameter is fully documented in the schema, so the description adds nothing beyond it. Baseline 3 applies when the schema carries parameter semantics entirely.

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 and clarifies the scope as 'a single Data Center', which implicitly contrasts with the sibling hcloud_list_datacenters. It does not explicitly name the alternative, but the singular versus list distinction is inferable.

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 deprecation notice with concrete dates functions as a strong when-not-to-use signal, arguably the most actionable guidance here. However, it never names a replacement or tells the agent when fetching a single datacenter is the right call versus listing.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds nothing beyond a restatement of purpose — no mention of what a Firewall object contains, whether the call fails for missing IDs, or any rate/consistency traits.

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?

It is very short and front-loads the action. The two sentences are mildly redundant ('Get a Firewall' followed by 'Returns a single Firewall'), which keeps it from being maximally efficient, but there is no filler.

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

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

For a trivial single-resource get with no output schema, the agent knows it receives one Firewall object. However, without an output schema the description could usefully mention the returned fields or error cases, and it does not, leaving a 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% with a single well-documented 'id' parameter (including example, bounds, and description). The description contributes no additional parameter meaning, so the baseline 3 for schema-complete definitions 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 ('Get a Firewall', 'Returns a single Firewall') and the word 'single' implicitly distinguishes it from hcloud_list_firewalls. It stops short of naming alternatives such as hcloud_get_firewall_action or hcloud_list_firewalls, so the differentiation is only hinted at.

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

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

There is no information about when to use this tool versus the many siblings, no mention that the firewall's id is required, and no note about prerequisites or error behavior. An agent must infer all usage context from the name alone.

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

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

Annotations already declare readOnly=true, destructive=false and openWorld=true, so the description carries a lighter burden. The description adds genuinely valuable non-schema context: the operation is deprecated, with a pointer to the changelog. It stops short of mentioning the wait/polling behavior, but that is covered by the schema.

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

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

Short and generally front-loaded, though the deprecation warning sits below the title line rather than leading. Every sentence contributes something; nothing is wasted.

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

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

For a simple read getter with full annotation and schema coverage, the description is mostly adequate. The gap is that a deprecated tool should name its replacement or the preferred alternative (e.g., the list-actions or the newer action endpoint) so an agent can route correctly.

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

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

Schema description coverage is 100%, so all three parameters (id, action_id, wait) are already documented in the schema. The description adds no meaning beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Get an Action for a Firewall') with the parent firewall scope made explicit. However, it does not differentiate itself from the very similar sibling tools hcloud_get_firewalls_actions_id and hcloud_get_firewalls_actions, so an agent must open schemas to tell them apart.

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 deprecation notice with a changelog link gives useful context about when this tool should be avoided, but no replacement tool or alternative is named. Beyond that, there is no explicit guidance on when to prefer this over the near-identical list/get siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered externally. The description adds nothing beyond that — no note on default page size, pagination limits, or whether the list includes historical completed actions. For a 5-param paginated list endpoint, more behavioral context would help.

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

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

Three short sentences, front-loaded with the action, with no wasted prose. The repeated header "List Actions" is slightly redundant with the tool name, but overall the text is efficient.

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

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

Annotations and a fully documented schema cover the essentials for calling the tool. However, with no output schema and no differentiation from the near-identical hcloud_list_firewall_actions sibling, an agent cannot confidently choose this tool over the alternative from the definition alone.

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 filtering by id, status, sorting, and pagination are all fully documented in the schema itself. The description's "URI parameters" phrase hints at filtering but contributes no syntax or semantics beyond that. 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 gives a clear verb and resource: "List Actions... Returns all Actions for Firewalls." The scope (firewall-scoped actions) is understandable at a glance. It does not distinguish itself from very similar siblings such as hcloud_list_firewall_actions or hcloud_get_firewall_action, so it stops short of a 5.

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

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

The only guidance is "Use the provided URI parameters to modify the result," which describes capability, not when to choose this tool. There is no mention of when to use it instead of hcloud_list_firewall_actions or hcloud_get_firewalls_actions_id, despite near-duplicate siblings existing.

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=true, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond the obvious read operation, and does not explain the polling behavior implied by the wait parameter.

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 short and front-loaded, but the two sentences are largely redundant: "Get an Action" and "Returns the specific Action" convey the same generic idea.

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 get-by-ID tool with rich annotations and full schema coverage, the description still fails to clarify its firewall-specific scope among many similar action tools. It also lacks any note about the action object returned or the wait/polling behavior.

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

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

Schema description coverage is 100%, and both id and wait are fully documented in the input schema. The description adds no parameter meaning, so the baseline of 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 says only "Get an Action" and "Returns the specific Action," which mostly restates the operation implied by the tool name. It omits the firewall scope entirely, so an agent cannot distinguish it from generic action getters like hcloud_get_action or hcloud_get_firewall_action.

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

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

There is no guidance on when to use this tool versus the many sibling action-retrieval tools. It neither names alternatives nor states any selection criteria.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered and the description's only added context is the single-resource return and a link to the Floating IP docs. It says nothing about behavior for a nonexistent ID (error vs null) or what fields the object carries, which matters given there is no output schema.

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

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

Two short sentences, action first, zero filler. The second sentence partially restates the first ('Get' / 'Returns a single'), so it is slightly redundant rather than earn-every-word optimal.

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

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

For a one-parameter read with no output schema, an agent still lacks the return shape and not-found semantics, which the description could have supplied in a sentence. It is adequate to call correctly but incomplete about what comes back.

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

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

Schema description coverage is 100% and the single parameter 'id' is documented in-schema as the Floating IP ID with bounds; the description adds no format or sourcing guidance (e.g., where to obtain the ID). Baseline 3 is appropriate when the schema does all the work.

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

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

States a specific verb and resource ('Get a Floating IP') and clarifies cardinality ('a single'), which implicitly separates it from hcloud_list_floating_ips. It never names the sibling explicitly, so differentiation comes from the verb/plurality rather than an outright contrast.

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

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

Usage is only implied: 'Returns a single' signals this is the by-ID lookup rather than the list call, but there is no explicit when/when-not, no note that you need the numeric ID, and no pointer to hcloud_list_floating_ips for discovery of IDs.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context — that the endpoint is deprecated as of the linked changelog — but says nothing about the returned Action's states, error handling, or the wait/polling behavior exposed by the schema.

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

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

Two short sentences plus a deprecation note, no filler. Slight weakness in ordering: leading with the deprecation notice would front-load the most decision-relevant fact rather than burying it after the purpose sentence.

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

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

For a simple read tool with full schema coverage and annotations, the purpose and deprecation status are adequately conveyed. However, with no output schema, the description does not characterize the Action payload (status, timestamps, error fields) an agent would need to interpret the response.

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

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

Schema description coverage is 100%, so id, action_id, and the wait polling flag are all documented in the schema. The description adds no parameter-level meaning (e.g., what happens when wait is false or how timeouts surface), so the baseline of 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 ('Get an Action for a Floating IP') and clarifies it returns a single Action scoped to a Floating IP, which separates it from the generic hcloud_get_action and the list variant hcloud_get_floating_ip_actions. It never names those siblings explicitly, so the differentiation is implied rather than stated.

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

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

There is no explicit when-to-use/when-not section or named alternative, but the Deprecated banner with a changelog link implicitly steers the agent away or toward migration. That is useful but indirect guidance rather than a clear usage rule.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no further behavioral context such as pagination behavior, default page size, filtering semantics, or how the results relate to floating IPs.

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 short and front-loaded with "List Actions," but the first two sentences are redundant and the markdown link to a generic Actions tag adds little value for an agent. It is not bloated, but it also does not use its brevity to convey useful specifics.

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 list tool with no output schema and many sibling list/action tools, the description omits the crucial scope: that it lists floating IP actions. It also does not explain the relationship to hcloud_get_floating_ips_actions_id or hcloud_list_floating_ip_actions, leaving the agent to infer context from the name and schema alone.

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 schema fully documents all five parameters including filters, sorting, and pagination. The description only says to use URI parameters to modify the result and adds no parameter semantics beyond what the schema provides, so the baseline 3 applies.

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

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

The description says "List Actions" and repeats "Lists multiple Actions", which is essentially a restatement of the resource in the tool name. It never states that these are actions associated with floating IPs, so the agent cannot distinguish it from siblings such as hcloud_list_actions or hcloud_list_floating_ip_actions.

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

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

The only guidance is "Use the provided URI parameters to modify the result," which does not say when to use this tool versus alternatives. There is no mention of when to choose this over hcloud_list_floating_ip_actions, hcloud_get_floating_ips_actions_id, or hcloud_list_actions.

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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds nothing beyond that: it does not mention that the returned action may be in-progress, nor explain the polling behavior implied by the sibling hcloud_wait_action. With annotations present the bar is lower, but this text contributes no behavioral context at all.

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 lines with no waste, but the brevity comes from under-specification rather than efficiency. The space saved is not spent on anything an agent would find useful, such as endpoint scope or return shape.

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

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

For a simple read tool this could be adequate, but with no output schema and a large family of near-identical siblings, the description should at least say what this action lookup is scoped to and what it returns. As written, an agent must open the schema and infer intent from the name alone.

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 required 'id' (ID of the Action) and 'wait' (poll until success/error or timeout) are fully documented in the schema. The description adds no parameter meaning beyond that, which lands at the baseline 3 for high-coverage schemas.

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

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

The text is essentially a restatement of the tool name: 'Get an Action / Returns a single [Action]'. It never distinguishes this endpoint from near-identical siblings such as hcloud_get_action, hcloud_get_floating_ip_action, or hcloud_get_floating_ips_actions (the list variant). An agent cannot tell which action-retrieval endpoint is correct from this text alone.

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

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

No when-to-use guidance, no prerequisites, and no named alternatives. The agent gets no signal that list-vs-get-by-id or hcloud_wait_action exist as competing choices, and no hint about how this scoped floating-IP action lookup differs from the generic one.

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=true, and destructiveHint=false, so the safety profile is covered. The description adds only that a specific Image object is returned, without disclosing error behavior (e.g., missing ID), authentication needs, or response characteristics; with no output schema, this is a notable 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?

It is short and front-loaded, but the second sentence ("Returns a specific Image object") is redundant with the first and adds almost no information. The definition is under-specified rather than verbose, making conciseness feel accidental.

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 get-by-ID tool, the definition enables invocation but not understanding of the result: there is no output schema, and the description does not explain what fields an Image object contains or what happens on a missing ID. The annotations cover safety, but the description is too thin to complete the tool's contract.

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

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

Schema coverage is 100%, and the single parameter is documented as "ID of the Image." The description adds no formatting or semantic detail beyond the schema, so the baseline of 3 applies when the schema fully carries parameter 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?

The description states a verb and resource ("Get an Image") and adds that it returns "a specific Image object," which faintly distinguishes it from hcloud_list_images. However, it is largely a restatement of the tool name and does not mention lookup by ID or explicitly differentiate it from siblings such as hcloud_get_image_action.

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

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

There is no guidance on when to use this tool versus alternatives like hcloud_list_images or hcloud_get_image_action. The description provides no prerequisites, no when-not conditions, and no routing to a sibling.

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, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds the deprecation status, which is genuine extra context, but omits that the action must belong to the given image and says nothing about the 'wait' polling behavior exposed by the schema.

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

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

Short and front-loaded, with the deprecation callout before the functional sentence. The opening heading and the closing sentence restate the same fact ('Get an Action for an Image' / 'Returns a specific Action for an Image'), which is mild redundancy but not harmful.

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

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

For a 3-parameter read tool with full annotations, no output schema, and a schema that documents every field, only light prose is needed. A hint about what an Action object contains or when a 404 occurs would help, but nothing essential to correct invocation is missing given the deprecation warning 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 description coverage is 100%, so id, action_id, and wait are all documented upstream; baseline 3 applies. The description adds no semantics about the id/action_id pairing or what polling means for a read call beyond what the schema states.

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

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

States a specific verb and resource ('Returns a specific Action for an Image'), which is unambiguous. It does not distinguish itself from nearby siblings such as hcloud_get_action, hcloud_get_images_actions_id, or hcloud_list_image_actions, so an agent still has to infer which retrieval shape to pick.

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 deprecated notice and changelog link effectively say 'prefer something else,' which is useful when-not-to-use signal. However, it never names the replacement endpoint, so the agent knows to avoid this tool but not what to call instead.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond restating the sort/status/id parameters from the schema, and critically leaves unresolved whether the result set is scoped to an image or global — the single most consequential behavioral question here.

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

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

Two short sentences, front-loaded with the operation and followed by the filtering note. No wasted text, though the filtering sentence largely duplicates structured schema content rather than carrying new 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?

With full schema coverage, annotations, and no output schema, the mechanics are adequately covered. But for a tool whose name suggests image scoping and whose description says 'all actions', the description should resolve that scope question — and does not.

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

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

Schema description coverage is 100%, so the schema already documents page, per_page, sort, status, and id thoroughly. The description merely names sort/status/id, adding no format, default, or interaction semantics beyond the schema — baseline 3.

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

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

It says "List Actions" and "Returns all Action objects", which gives a verb and a resource, but the tool name (hcloud_get_images_actions) implies image-scoped actions while the description claims it returns ALL actions. An agent cannot tell whether this is scoped to images or global, and the description never differentiates it from hcloud_list_actions or hcloud_get_images_actions_id.

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

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

No when-to-use guidance, no prerequisites, and no mention of the obvious siblings (hcloud_list_actions, hcloud_get_action, hcloud_get_images_actions_id). The only usage hint is how to sort and filter, which is invocation mechanics rather than selection 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, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that – it doesn't say what happens if the ID doesn't exist, what fields an Action carries, or that the `wait` parameter triggers polling behavior. It is essentially a restatement of the tool name.

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?

It is short and front-loaded, which is good, but the second sentence ('Returns a specific Action object') merely repeats the first ('Get an Action'), so one of the two sentences does not earn 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 read-only lookup with full schema coverage and clear annotations, this is barely adequate. With no output schema, the description could reasonably hint at the shape of an Action object or its relation to image operations, but it doesn't, leaving the agent to infer scope from the awkward tool name.

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

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

Schema description coverage is 100% and both parameters (`id` and `wait`) are documented in the schema, so the baseline of 3 applies. The description contributes no additional meaning about the ID's scope (image action ID vs. generic action ID) or the polling semantics.

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

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

States the verb 'Get' and the resource 'Action object', so the basic operation is clear. However, it never says this is specifically the image (or image-resource) action endpoint, and with roughly a dozen near-identical siblings (hcloud_get_certificates_actions_id, hcloud_get_servers_actions_id, hcloud_get_volumes_actions_id, etc.) the description does nothing to distinguish this tool from them.

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

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

There is no guidance on when to use this tool at all. It doesn't mention the sibling list endpoints (hcloud_list_image_actions, hcloud_get_images_actions), the single-action sibling (hcloud_get_image_action), or the generic hcloud_get_action, nor any prerequisite such as already having obtained an action ID from a prior mutation.

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, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered externally. The description adds nothing beyond them — no note on error behavior for a nonexistent id, no mention of what identifiers the returned object exposes (which matters since ISOs are passed to hcloud_server_attach_iso_action).

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?

It is short and front-loaded, but the second sentence ("Returns a specific ISO object.") is a pure restatement of the first and earns no place. Brevity here comes from under-specification rather than efficient communication.

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 full annotation and schema coverage, this is minimally sufficient: the agent knows it fetches one ISO by id. It stops short of explaining how the fetched object is used downstream (attaching to a server) or how to discover ids, leaving a real gap in a large sibling set.

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