Delete an environment

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

With no annotations, the description carries the full burden and does well: it discloses irreversibility 'beyond the platform's own backup retention', the destructive scope of deleted assets, the confirm-gating and dry-run fallback, and the auth profile used. It omits finer operational detail such as timeout/background behavior and what the response contains, keeping it just under a 5.

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 destructive scope and irreversibility are front-loaded and every clause is relevant. It loses a point for redundancy: 'requires confirm: true' is asserted in one sentence and then restated in the closing sentence as 'Mutates a live environment: requires confirm: true (a dry run otherwise)'.

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 no-annotation, no-output-schema destructive tool with fully documented parameters, the description supplies the key safety context an agent needs: irreversibility, confirm gating, dry-run default, and the underlying command/auth. Only the return-shape and long-running (async/background) semantics are left to the schema, which is acceptable.

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% with 8 documented parameters, so the schema already does the heavy lifting and 3 is the baseline. The description reinforces the confirm semantics but adds little beyond the schema, and its 'active pac auth profile' phrasing slightly undersells the profile parameter's documented CPS_ADMIN_PROFILE default.

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 (delete an environment) plus the full blast radius — 'with everything in it: agents, solutions, flows and data'. This scope distinguishes it from adjacent siblings such as cs_admin_reset_environment, cs_admin_copy_environment and cs_delete_solution without the reader needing to open those schemas.

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 the operative condition clearly: confirm: true performs the deletion, otherwise the tool returns a dry run, and it names the underlying 'pac admin delete' command with the active auth profile. It does not, however, explicitly route the agent between this and alternatives like reset or restore, so it stops short of a full when/when-not/alternative statement.

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