Unit File Remove Tool

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 the multi-step destructive behavior, backup, optional masking, protected-list refusal, and best-effort semantics for stop/disable. It does not mention permission requirements or what 'back up' entails, which would strengthen transparency for a destructive operation, but it is far above the minimum.

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 sentences with no fluff. The main action is front-loaded, and the caveats (protected list, best-effort behavior) are placed immediately after. Each sentence earns its place and there is no redundant restatement of the title or schema.

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 multi-step tool, the description covers the essential context: what will happen, when it will be refused, and when partial failures do not block removal. An output schema is present, so return values need not be described. A bit more detail about backup location or required privileges would make it fully complete for an agent, but the current description is adequate.

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 baseline is 3. The description's 'optionally mask' matches the mask parameter and 'remove its file' maps to unit_name, but it adds little meaning beyond what the schema already explains. No extra parameter-level guidance is provided.

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 opens with a specific verb and resource: 'Decommission a unit', then lists the exact operations (stop, disable, optionally mask, back up, remove file). This clearly distinguishes the tool from siblings like unit_stop_tool, unit_disable_tool, and unit_mask_tool by marking it as the full removal/decommission operation. It also adds a scope constraint (protected-list refusal) that makes the tool's purpose more precise.

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 gives a clear when-to-use signal: decommissioning a unit, as opposed to merely stopping or disabling it. It also states an explicit when-not: 'Refused for units on the protected list.' However, it does not explicitly name alternative sibling tools such as unit_stop_tool for stop-only scenarios, so it stops just short of the highest level of routing guidance.

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