mcp_opendaw_create_soul_arrangement

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

Without annotations, the description takes on the burden of explaining effects. It details the exact musical output per track, the default BPM's effect, and the constraint that bars must be a multiple of 4. It also states the return value ('Returns notes created per track and total'). However, it does not specify whether notes are appended or overwrite existing notes on the target tracks, which is a notable omission.

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-organized: a one-sentence summary, followed by per-track breakdown, stylistic rationale, parameter list, return value, and usage examples. While lengthy, every section adds useful information and the structure aids scanning.

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 complexity (4 tracks, 11 parameters), the description is largely complete: it covers most parameters, provides musical character, constraints, and examples. Gaps include the undocumented velocity and start_beat parameters and lack of detail on whether existing track content is preserved or replaced, preventing a perfect score.

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?

Despite the schema having zero parameter descriptions, the tool description compensates well: it explains bpm with a range and default, bars with a validity constraint, octave with MIDI note mapping, root with a suggested key, and the track parameters with their roles. It fails to mention the velocity and start_beat parameters, leaving those to defaults without explanation.

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 'Create a full soul arrangement — gospel drums + melodic bass + Rhodes chords + horn stabs across 4 tracks,' which clearly identifies the tool's function and distinguishes it from genre siblings by specifying the genre and instrumentation. It further lists each track's role, leaving no ambiguity about what the tool produces.

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 provides clear stylistic context by naming Motown/Stax/Atlantic soul and specific artists, and explicitly contrasts soul with funk and pop ('The I-IV-vi-V progression is the gospel quartet influence that separates soul from funk...'). It does not name alternative tools directly, but the genre distinction implicitly guides when to use this tool versus other arrangement creators.

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