Destroy Environmental

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

While annotations already signal destructive behavior, the description adds confusion by mixing soft and hard delete language. The repeated 'cannot be undone' is redundant. The tool name suggests permanent destruction, but the description says 'sends to Recycle Bin', which is not final. This undermines the agent's ability to predict the tool's true effect.

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 about 4 sentences but repeats 'This cannot be undone' and 'Permanently removes' unnecessarily. It could be condensed without loss. The inclusion of the API endpoint is helpful but the repetition wastes space.

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?

Given the complexity (relationship with Incidents, recycle bin vs permanent delete) and the lack of output schema, the description is incomplete. It fails to clarify the ambiguity between soft and hard deletion, omits the optional parameter's role, and does not mention what happens after deletion (e.g., visibility in recycled list).

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?

The input schema has 100% coverage with clear descriptions for each parameter. The description redundantly lists the required parameters but does not explain the optional `incident_id`. Since the schema already provides sufficient meaning, the description adds marginal value.

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 contains an internal contradiction: it claims to 'send to Recycle Bin' (soft delete) but also 'permanently delete'. It also refers to deleting 'Incidents' rather than 'Environmental records', which is inconsistent with the tool name. This confuses the tool's core purpose.

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?

No guidance is provided on when to use this tool versus alternatives. Sibling tools include other destroy_* tools, but there is no comparison or explanation of scope (e.g., this deletes Environmental records within an Incident). The agent has to infer context from the endpoint alone.

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