Destroy a single Mass entity by its handle (Index:SerialNumber), returning whether it was destroyed or already gone.
Destroy a single Mass entity by its handle (Index:SerialNumber).
Returns: { entity_handle, destroyed: bool, already_destroyed: bool }
| Name | Required | Description | Default |
|---|---|---|---|
| entity_handle | Yes | "{Index}:{SerialNumber}" string returned by spawn/query. |
Changes observed during successful MCP inspections.
v1.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds real value by disclosing the return shape, including an 'already_destroyed' flag, which tells the agent that re-destroying an entity is reported rather than erroring. That is behavioral information not present in any structured field.
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?
Two sentences, zero waste. Purpose and identification key are front-loaded, and the return shape follows compactly. Nothing extraneous.
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 destructive tool there is no output schema, and the description compensates by stating the return shape. Combined with annotations and full schema coverage, an agent has what it needs; only error/failure behavior and prerequisites are left unstated.
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%, so the handle format is already documented ('{Index}:{SerialNumber}' string returned by spawn/query). The description only echoes that format, adding no extra syntax or constraints, which fits the baseline 3 when the schema does the heavy lifting.
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 (destroy) and resource (a single Mass entity) plus the identifying key (handle). The word 'single' scopes it against the sibling destroy_all_mass_entities, but the description never names that alternative explicitly, so differentiation is implied rather than spelled out.
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 when-to-use guidance and no alternatives named. The description never says when to prefer this single-entity destroy over destroy_all_mass_entities or despawn_mass_entities, nor does it note prerequisites such as the entity needing to exist. Usage must be inferred from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.