delete_device

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

With no annotations, the description carries the full burden and excels: it discloses the destructive gate (confirm=True), the dry-run reporting mode (confirm=False reports device details and parameter count), the side effect that subsequent device indices shift down by one, and even the Live 12.4.5 measurement date. This is exactly the behavioral context an agent needs before invoking a destructive operation.

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 action and the critical confirm requirement are front-loaded in the first two sentences, followed by scannable Args/Returns/Note sections. Each element — the index-shift warning, the pending-loss-report return, the version measurement — earns its place, and the whole description stays under roughly 100 words.

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 three-parameter destructive tool with no annotations and an output schema present, the description is essentially complete: action, safety protocol, all parameter semantics, return summary ('Dictionary reporting deletion status or pending loss report'), post-deletion side effect, and an alternative operation. The output schema covers the return structure, so the slightly cryptic 'pending loss report' phrase is an acceptable summary rather than a gap.

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 0%, but the Args section fully compensates: track is mapped to 'Track index in song.tracks', device to 'Device index within track chain', and confirm to 'Confirmation flag required to execute deletion.' Every parameter receives domain meaning beyond its raw type, and the confirm default-of-false interacts correctly with the stated 'Requires confirm=True' behavior.

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-resource pair — 'Remove a device from a track device chain' — and the 'device chain' scoping distinguishes it from sibling deletes like delete_clip and delete_track. It stops short of 5 because the phrasing closely mirrors the tool name itself, so the clarity leans partly on the function name rather than on original framing.

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 confirm=True requirement plus the explain-confirm=False-preview behavior imply a two-phase safe-usage pattern, and the note that devices can be reordered via song.move_device hints at an adjacent alternative. However, there is no explicit when-to-use versus when-not-to-use statement, and the move_device note covers reordering, not a competing deletion path.

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