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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description goes further by spelling out what is destroyed (targets not in the list are removed, since it 'replaces' and you 'send every target to keep'), the hard cap of 25, the network prerequisite, and the drain side effect. That is exactly the extra context the annotations cannot convey.

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

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

Three tight sentences, front-loaded with the destructive replace semantics and capped by the scope tag. Every clause carries information: replacement mode, cap, prerequisite, drain behavior, permission. Nothing is padding.

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, no-output-schema mutation, the definition covers the danger (omitted targets are removed), limits, prerequisites and the drain flag. It does not address atomicity/partial failure behavior or what 'weight' does, which an agent managing a live pool might want before calling.

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 67%, and the description fills a real gap by explaining 'drain: true stops new connections to a target before maintenance', which the schema leaves as a bare boolean. It also restates the 25-item cap that mirrors maxItems. The 'weight' field and the per-target vm/port meaning are left entirely 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 ('REPLACES the pool's targets') and immediately disambiguates the semantics that matter most: full replacement, not append. The uppercase-REPLACES plus 'send every target to keep' makes the operation unmistakable without needing the schema, and no sibling tool (upsert_pool, delete_pool) overlaps with this 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?

Gives the prerequisite ('Each machine must be in the load balancer's private network (connect_vpc first)') and a use context ('before maintenance' for drain), which tells the agent when this is the right call. It stops short of naming an explicit alternative or a when-not-to-use case, so a 4 rather than a 5.

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