remove_instances

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

Without annotations, the description fully discloses behavioral traits: it starts with 'DESTRUCTIVE', details how each strategy affects instances (graceful drain vs. abrupt kill vs. permanent removal), mentions safety guard confirm, and notes cloud-specific restrictions. This goes beyond typical transparency expectations.

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 well-structured with a warning header, recommendation line, strategy bullets, and parameter list. Every sentence adds value without redundancy, and key points are front-loaded (destructive nature, recommended, confirm requirement).

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 description covers usage, parameters, and strategies thoroughly. However, it does not describe the return value or output schema (which exists), leaving a minor gap for agents expecting result details. Otherwise, it is complete for the tool's destructive purpose.

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 0% schema coverage, the description adds complete semantics for all 7 parameters: format examples, defaults, strategies list, batch size context, cloud provider limits, and environment variable fallback. This compensates fully for the sparse 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 clearly states the verb 'remove instances', resource 'Ocean cluster', and method 'using a named strategy'. It also distinguishes itself from siblings by claiming 'this is the RECOMMENDED tool for instance removal', making its purpose 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?

The description provides explicit guidance on when to use each strategy (e.g., drain_and_replace for production safety, replace for speed, remove_permanently for downsizing), and requires confirm=true. It does not compare with sibling tools like detach_instances, but the recommendation serves as a clear usage directive.

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