pool_member_disable

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

Annotations indicate destructiveHint: true and idempotentHint: false. The description goes beyond annotations by explaining the graceful drain behavior, that no new traffic is sent, and the safety mechanism requiring confirmation. It adds behavioral context that annotations do not cover, such as the preview behavior when confirmed=False. No contradiction with annotations.

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

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

The description is extremely concise, using a single line to state purpose, then providing usage and safety info in a structured bullet format. Every sentence adds value, and the info is front-loaded with the key action and behavior.

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

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

Given the tool has an output schema (covering return values), the description focuses on inputs and behavior. It explains when to use, what happens, and the safety mechanism. All critical aspects are covered: purpose, usage, parameters, and behavioral traits. Despite moderate complexity (3 params, 2 required), the description is complete.

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?

Despite schema description coverage being 0%, the description explains all three parameters: 'pool' (pool name), 'server' (server IP address), and 'confirmed' (must be True to execute, default False returns preview). This fully compensates for the lack of schema descriptions, adding semantic meaning beyond the schema types.

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

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

The description clearly states the action 'Disable a pool member' with the specific behavior 'graceful drain — existing connections complete, no new traffic'. It also explicitly labels the tool as '[WRITE]', distinguishing it from read-only tools. The sibling tool 'pool_member_enable' provides a clear contrast, ensuring the agent knows this is the disable counterpart.

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

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

The description explicitly states when to use the tool: 'Use during maintenance windows or rolling deployments.' It also provides crucial usage guidance about the 'confirmed' parameter, explaining that default False returns a preview and True executes the action. This clear when-to-use and when-not-to-use guidance is exemplary.

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