delete_track

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

Annotations are absent, so the description carries full burden. It discloses the destructive action, index-shift side effect, the confirm gate, and the exact preview contents (track name, devices, filled Session slots, Arrangement clips). This is far more transparent than a bare mutation note.

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?

Well structured with Args/Returns/Note and the core action is front-loaded. Minor redundancy: 'renumber subsequent tracks' repeats in the Note, and 'Requires confirm=True' repeats in the Args.

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 two-parameter tool, it covers invocation, preview behavior, return type, and side effects; the output schema fills in the exact return shape. No critical missing context remains despite the lack of annotations.

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%, yet the description fully documents both parameters: track is the index into song.tracks, and confirm is the flag that must be true to delete while false yields a loss report. It compensates for the schema's bare titles.

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?

First sentence names the exact operation and resource: 'Delete a track' and adds the side-effect 'renumber subsequent tracks'. This distinguishes it from sibling delete_clip/delete_device and leaves no ambiguity about what is acted on.

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 makes the invocation condition explicit: execution 'Requires confirm=True' and confirm=False acts as a dry-run loss report. It doesn't explicitly mention when to prefer delete_clip or delete_device, so it stops short of full alternative guidance.

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