track

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

No annotations are provided, so the description carries full burden. It discloses important behavioral traits: every mutation runs in a REAPER undo block (encompassing undo-ability), supports dry_run for previewing changes, and warns that delete is destructive and requires confirmation. However, it doesn't mention required permissions, rate limits, or the effect of operations on selected tracks beyond the 'exclusive' parameter.

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 extremely concise: one line listing actions, one line for behavioral notes, and one warning. It front-loads the action list and then key behaviors, with no wasted words. Each sentence serves a purpose.

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?

Given the tool's complexity (17 parameters, no annotations, no output schema), the description is only partially complete. It covers the actions and some critical behaviors (undo, dry_run, destructive delete), but omits guidance on targeting tracks (e.g., which parameters are mutually exclusive), error handling, or output. An agent would need to consult the schema heavily to use it correctly.

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 53%, so about half of the 17 parameters lack schema documentation. The description adds meaning for some parameters: set_volume (dB), set_pan (-1..1), and mentions dry_run, but doesn't explain others like track, track_contains, target_track_guid, use_selected_track, or exclusive in detail. The schema itself does provide descriptions for about half, so the description partially compensates but leaves gaps.

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 clearly enumerates the operations (add, delete, rename, select, set_volume, set_pan, mute, solo, arm, set_color), which are the exact enum values from the schema. It states a specific resource ('track') and verb set, making the tool's scope clear. However, it doesn't explicitly distinguish itself from siblings like mix_recipe or raw_command, though none of the listed siblings appear to overlap directly with basic track operations.

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 provides no guidance on when to use this tool versus alternatives. It mentions dry_run and confirms delete intent, but there's no indication of when this tool is preferable over raw_command, batch, or other track-related tools. An agent would have to infer usage from the action list alone.

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