add_fx

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

With no annotations, the description carries the full burden, and it does disclose the key behavioral fact — the return value is the new FX index, or -1 if not found. However, it says nothing about mutation side effects (undo/reversibility), whether the track must already exist, or what happens when the same FX is added twice.

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 front-loaded sentences; the purpose leads, then matching semantics, then the return value. The examples earn their place by clarifying a non-obvious matching rule. Slightly under-specified rather than bloated.

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 low-complexity, two-parameter tool with no output schema, the description covers the essentials: what it does, how the FX name is matched, and what it returns. Gaps are the undocumented track_index convention and the mutation/undo behavior, which keep it short of complete.

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%, so the description must compensate. It does add real value for fx_name by explaining the REAPER FX-browser matching convention with concrete examples, but track_index is entirely unexplained (0-based? selectable via list_tracks?), leaving half the parameters undocumented.

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 clear verb+resource ('Add an FX plugin to a track') that an agent can easily distinguish from the sibling tools remove_fx and list_fx. The fx_name examples ('ReaEQ', 'VST:Pro-Q 3') further pin down what kind of resource is being added. It never names a sibling explicitly, so it stops short of a 5.

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 only implied: the tool obviously requires an existing track, but the description never says so, nor does it point to list_fx as the way to discover valid FX names before calling. No when-to-use vs. alternatives guidance is given beyond the name-matching semantics.

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