mcp_opendaw_create_blues_arrangement

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

With no annotations, the description carries the full burden of behavioral disclosure. It mentions that notes are created and returns the count, but it does not disclose whether the tool overwrites existing notes on the specified tracks, whether tracks must pre-exist, or whether it is additive. This is a notable gap for a mutation tool.

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 heavily padded with music-theory background—shuffle feel, blue notes, 12-bar history—that is educational but not strictly necessary for tool invocation. While well-structured with headings and parameter list, the extra prose makes it longer than needed; a more concise version would be equally effective.

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 an 11-parameter tool with no annotations and no visible output schema, the description covers the core parameters, defaults, and return value. However, it is incomplete on operational expectations: it doesn't state prerequisites like whether tracks already exist, how existing notes on those tracks are handled, or what happens if track indices are invalid. Given the complexity, these gaps prevent a higher 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?

The schema provides no parameter descriptions (0% coverage), so the description compensates by explaining most parameters: bpm, bars, root, octave, unit_index, and track indices. It adds crucial meaning like 'bars must be multiple of 12' and 'bpm 70-160', but omits velocity and start_beat entirely, leaving those two 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?

The description opens with 'Create a full blues arrangement' and enumerates concrete components (shuffle drums, walking bass, dominant 7th chords, blues scale lead), making the tool's purpose unmistakable. It also distinguishes itself from sibling genre-arrangement tools by explicitly naming blues-specific elements.

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 context for when to use the tool (creating blues arrangements) and includes examples for different tempos and roots, showing usage flexibility. However, it does not explicitly state when not to use it or name alternatives, such as other genre-arrangement tools.

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