deployment_delete_deployment

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered structurally. The description still adds real value beyond that by disclosing what gets destroyed — the deployment plus its associated Cloud Provider resources — which is exactly the kind of blast-radius context annotations do not convey. It stops short of saying whether the call is asynchronous or returns a request to track, which is the main remaining gap.

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?

It is short and front-loaded with the verb, which is good, but the second sentence restates the first ('Delete a deployment' / 'Deletes the deployment with the supplied ID') and the phrase 'Effectively triggers a Delete Day2 operation' is internal jargon that adds no actionable meaning for an agent.

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, open-world mutation with no output schema, the description covers what is deleted but omits what the caller gets back (a request/task handle for an async deletion?), required permissions, and how this differs from the iaas_ and onboarding_ delete variants. Adequate to invoke, not adequate to invoke confidently in a crowded namespace.

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 description coverage is 100%, and the forceDelete parameter is already fully documented in the schema including its caveat about leaving provisioned infrastructure behind. The description only echoes 'the supplied ID' and adds no syntax, format, or interaction detail (e.g., whether forceDelete is required for stuck deletions), so baseline 3 applies.

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 states a specific verb and resource ('Delete a deployment... with the supplied ID') and the underlying endpoint, so the action is unambiguous. However, the sibling list contains closely competing tools (iaas_delete_deployment, onboarding_delete_deployment_by_id) and the description makes no attempt to distinguish this deployment-API delete from those, leaving the agent to infer the boundary.

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?

There is no guidance on when to choose this tool over the similarly named delete siblings, nor on when forceDelete should be set versus omitted. The only usage signal is implicit — you supply a deployment ID and it is deleted — with no prerequisites, exclusions, or pre-conditions (e.g., must the deployment be powered off first?).

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