live_track_edit

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

With no annotations supplied, the description carries the full burden and does so: it discloses which actions are undoable ('remove, move, folder and renameEvents undo with live_undo'), which are not ('Rename and colour are not on the undo stack'), and how to reverse route by routing back to the 'before' channel the result gives. It also notes side effects an agent would otherwise not predict — the mixer channel is renamed with the track, a created folder is expanded so the track stays visible, and the track selection is kept. This is exactly the behavioral context annotations would normally provide.

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?

Every clause carries information and the key constraint (exact name, running Studio One) is front-loaded, so it is efficiently sized for seven actions. However, it is delivered as one long run-on sentence with nested parentheses and semicolons, which is hard to scan for an agent trying to map action to parameter. A short per-action structure would have cost no extra 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 an 11-parameter, seven-action mutation tool with no annotations and no output schema, the description covers undo semantics, prerequisites, side effects, and visibility. It is thin on failure behavior (what happens when the exact track name is not found, or when 'kind' is omitted and names collide) and on the shape of the returned result it twice refers to. Those are the only meaningful omissions.

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 already high (82%), so the baseline is 3, but the description adds real meaning: 'kind' is explained as the disambiguator when an audio stem and its MIDI render share a name, 'to' is a channel name, 'create: true' means create the folder if none exists, and 'numbered' produces (01), (02)… in time order. It also clarifies the before/after pair as a reorder anchor. Minor gaps remain (e.g., the exact 'track' matching rules beyond 'exact name').

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 ('Edit a track by exact name in the running Studio One') and then enumerates all seven actions (rename, color, remove, move, route, folder, renameEvents) with a one-clause gloss for each. An agent can tell this is the track-mutation tool rather than a listing or event tool. It stops short of naming siblings it overlaps with (e.g., live_select_track, live_set_channel, live_edit_events), so it is clear but not fully differentiated.

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 spelled out per action: rename targets the track and its mixer channel, move is explicitly top-level-only and not inside a folder, folder can create the folder with create: true, route takes a channel name. It also states the prerequisite that move/route/folder/renameEvents run through the 'MCP Track Edit task installed with the device'. There are no explicit exclusions or named alternatives for overlapping siblings, which keeps it below a 5.

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