stop_instances

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the description's real contribution is the consequence: instances serve no traffic and cannot be restarted through this API, plus the 502 failure mode and that the action is immediate. That is meaningful context beyond the annotations, though it says nothing about auth requirements or what happens when all=true only partially succeeds.

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 one-versus-all distinction, then consequences, then the alternative. Dense and mostly waste-free, though '502 if a stop is not acknowledged' is telegraphic enough to be slightly ambiguous and the sentences read as fragments rather than a coherent flow.

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 mutation with full schema coverage and annotations, the description covers purpose, exclusivity, side effects, irreversibility within the API, a failure code, and the sibling alternative. Remaining gaps (partial failure semantics with all=true, whether the response returns anything useful) are minor given there is no output 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?

Schema coverage is 100% and both parameter descriptions already state the mutual exclusivity, so the description's 'never both' clause largely restates structured data. No additional format or sourcing detail (e.g., that hostname must come from list_instances) is added beyond what the schema says.

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 ('Stop one instance (hostname) or every registered instance') plus the scope of effect, and explicitly names the sibling it is not ('Use reload_instances to apply config instead'). The clause about stopped instances serving no traffic separates it from delete_instances without the agent needing to open either 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?

Gives a clear selection rule between the two parameters ('never both') and an explicit alternative for a different intent ('Use reload_instances to apply config instead'). It does not cover when stop_instances should be chosen over delete_instances, which is the nearest sibling and a plausible confusion point.

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