hcloud_load_balancer_add_service_action

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

The annotations already declare this as a non-destructive, open-world mutation, so the safety profile is covered. The description adds one valuable operational fact - the 412 source_port_already_used error - but says nothing about the asynchronous action model, whether wait defaults to true, or what state the Load Balancer is left in 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?

The content is front-loaded and short: a one-line statement of purpose followed by an error table. The redundant 'Add Service' heading is minor waste but the rest 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 mutation tool with three parameters and no output schema, the description covers the happy path and one error but omits the action/polling semantics implied by the wait parameter, return shape, and any constraints on combining protocol and health_check settings. Adequate but with clear gaps.

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

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

Schema description coverage is 67%, so many field meanings are already documented. The description adds only the source-port conflict hint, which maps loosely to listen_port; it says nothing about the body's required protocol, destination_port, health_check, or the wait parameter's polling behavior.

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: 'Adds a service to a Load Balancer.' That is unambiguous and lets an agent distinguish it from siblings like update_service or delete_service by implication, though it never names them 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?

There is no guidance on when to use this versus hcloud_load_balancer_update_service_action or hcloud_load_balancer_delete_service_action, nor any prerequisites such as needing an existing Load Balancer or listeners. The agent must infer the use case 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.