coolify_cancel_deployment

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

Annotations already indicate readOnlyHint=false (mutation), but the description adds valuable behavioral details: it explicitly says the operation is for queued/in-progress deployments and that terminal states yield UNSUPPORTED_OPERATION. The audit trail reference ('coolify.deployment.cancel') provides additional transparency about logging, exceeding what annotations 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?

The description is two short sentences: the first delivers the core action and scope, the second adds a critical edge case and audit context. No wasted words, and the key information is front-loaded.

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 single-parameter, low-complexity cancel operation, the description covers the purpose, applicable state, error behavior for terminal states, and audit logging. It does not elaborate on return formats or asynchronous behavior, but given the lack of an output schema and the simplicity of the operation, the context is sufficiently 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?

Schema coverage is 100%, with a single parameter 'deployment_uuid' fully described as 'Deployment UUID to cancel'. The description does not add additional parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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 uses a specific verb ('Cancel') and resource ('queued or in-progress deployment'), clearly distinguishing it from deployment listing, getting, or deploying tools. It also states the exact scope (non-terminal states) and notes the unsupported case for terminal states, making the 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 implies when to use the tool: when a deployment is queued or in-progress, not terminal. It also states that terminal states will return UNSUPPORTED_OPERATION, effectively informing users when not to attempt cancellation. However, it does not explicitly name alternative tools or provide broader context on when cancellation is appropriate versus other actions.

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