live_add_instrument_track

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

With no annotations, the description does meaningful work: it discloses the live-session requirement ("running Studio One") and, notably, the reversibility contract — "One live_undo removes the track and the instrument." That is a concrete behavioral fact an agent could not infer from the schema. Remaining gaps, such as failure mode for an invalid instrument name, keep it below 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?

A single sentence with no filler, and the core action is front-loaded. The nested parentheticals carrying the plugin source, kind filter, and examples make it dense to parse in one pass, but nothing is superfluous.

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 two-parameter creation tool with no annotations and no output schema, the description covers what it creates, how to source the instrument, and how to undo it. It does not say where the track is inserted, what is returned (e.g. a track identifier), or what happens if the instrument name is unknown, leaving the agent under-informed for post-call handling.

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 only 50%, with `instrument` having no schema description, so the description must compensate — and it does, explaining the value source (live_plugins, kind "instrument") and supplying examples. The optional `name` parameter is covered only partially, since the default behavior (instrument name) lives in the schema rather than the description.

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?

States a specific verb and resource ("Add an instrument track") and narrows the scope precisely: it creates a track hosting a new instrument instance, sourced "by name, from live_plugins with kind 'instrument'". The examples ("Mai Tai", "Presence") make the expected value concrete and separate it from live_add_track and live_add_plugin.

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 routes the agent to live_plugins for valid instrument names and implies this is the tool for instrument tracks versus generic track creation, which is real selection guidance. It stops short of explicitly contrasting with siblings like live_add_track or live_add_plugin, so no exclusion statement is given.

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