mcp_opendaw_set_vaporisateur_osc_param

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

With no annotations, the description carries the transparency burden. It does disclose that the tool returns old and new values, which is helpful, and provides value ranges for parameters. However, it does not mention side effects, error behavior on invalid inputs, or whether the operation is reversible. This is a moderate level of transparency for a write operation.

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 well-structured and information-dense, using bullet-like formatting to list each parameter and its allowed values. The purpose statement is front-loaded, and every sentence provides useful detail. No fluff or redundancy beyond the minor 'value: New value' line, which is still functional.

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 moderate complexity (4 required parameters, no annotations, output schema present), the description covers param semantics, value domains, and return behavior (old and new values). It is complete enough for an agent to invoke it correctly without additional lookup. Missing only explicit usage context and edge-case handling, which are minor gaps.

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 fully document parameters, and it does. It explains the valid range for osc_index (0,1), enumerates all accepted param_name values with exact mappings (waveform: 0=Sine, etc.), describes volume dB range, octave integer offset, tune float offset, and the special auto-detect behavior of unit_index. This adds substantial meaning beyond the bare schema.

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 'Set a parameter on a Vaporisateur oscillator,' which clearly identifies the action (set), the target resource (parameter on a Vaporisateur oscillator), and distinguishes it from other set_* tools that target different resources (e.g., set_effect_parameter, set_instrument_param). The parameter details further clarify the scope.

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?

No explicit guidance is provided about when to use this tool versus alternatives like mcp_opendaw_list_vaporisateur_params or set_instrument_param. The description implies usage for any Vaporisateur oscillator parameter change, but does not mention prerequisites (e.g., looking up valid param names via the list tool) or scenarios where a different tool would be more appropriate.

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