live_add_plugin

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 a solid job: it declares the operation is a live mutation, states what is returned ('the channel's inserts afterwards'), describes reversibility ('One live_undo removes it'), and explains the operation runs through the MCP Track Edit task, which tells the agent changes are grouped/undoable. It omits error behavior and any prerequisite state validation, which keeps it below a 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?

Three short sentences, front-loaded with the action and target, then return value, then undo/implementation context. Every sentence contributes information an agent needs, and there is no filler.

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, no-output-schema mutation tool, the description covers purpose, target scope, effective return value, and undo path. What is missing is behavior on invalid input (unknown plug-in, invalid channel label) and any confirmation of whether the channel must already exist, which is a modest but real 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 100%, so a 3 is the baseline; the description adds genuine meaning by tying the 'plugin' parameter to the vocabulary exposed by live_plugins, indicating the value must be a recognized plug-in name rather than arbitrary text. The 'channel' parameter is left entirely to the schema's 'Exact channel label', which is adequate but adds nothing in 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?

The description states a specific verb and resource ('Add a plug-in ... to a channel's inserts in the running Studio One') and even names where valid plug-in names come from ('from live_plugins'), which separates it from live_inserts and live_plugin_params. It stops short of explicitly contrasting itself with adjacent write tools such as live_add_send or live_add_instrument_track, but the operation is unambiguous.

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?

It gives clear context for use: the plug-in name must come from live_plugins, and the add targets an existing channel's inserts in the live session. The mention of 'One live_undo removes it' effectively tells the agent how to back out. There are no explicit exclusions or failure conditions (e.g. unknown plugin name, missing channel), so it falls short of full when-to-use/when-not guidance.

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