clean_drive

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses the multi-step physical action (load, wait, unload), a concrete timing bound (max 180 s), and a lasting side effect (setting P5 Device cleaning to 0). The confirm:true requirement is surfaced as a safety gate. It stops short of describing failure handling or what happens if the wait times out, which keeps it from 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 definition is a single dense sentence whose clauses follow the actual execution order, so the procedure is front-loaded and easy to scan. Every clause carries operational information; the only minor cost is that the sequence and the confirm requirement are packed into one long sentence rather than separated for readability.

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 mutating hardware tool with no annotations and no output schema, the description supplies the essential context an agent needs: what physical actions occur, how long they take, what state is changed afterward, and that confirmation is mandatory. The remaining gaps — the meaning of 'force', behavior on timeout or failure, and what is returned — are modest but real for a destructive-ish operation.

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 coverage is 100%, so all three parameters are already documented in the input schema, and the description largely restates them (drive as P5 name or L6/L9 generation, confirm must be true). It adds no meaning for the 'force' parameter, which overrides the busy-library check — a behaviorally significant flag that is left entirely to the schema's one-line note. Baseline 3 is appropriate given 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?

The description names a specific verb and resource ('Cleans a drive') and then spells out the exact physical procedure: load CLN* tape, wait for not-ready to ready, unload, reset the cleaning counter. That is far more specific than the name alone. It does not explicitly contrast with any sibling, but no sibling in the list appears to perform drive cleaning, so the lack of differentiation is a minor gap rather than a real ambiguity.

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?

Usage is implied rather than stated: an agent can infer this is the tool to call when a drive needs cleaning with a CLN* tape, and the 'Requires confirm:true' clause signals a guarded operation. However, there is no explicit when-to-use or when-not-to-use guidance, no mention of preconditions such as the drive being unloaded or the library being idle, and no alternatives are named.

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