mcp_opendaw_create_appoggiatura

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains the tool's behavior: plays a neighbor note first, resolves to the main note, defaults to a 2/3–1/3 duration split, accents the approach note, and supports above/below approaches. It also discloses the return value ('Returns notes created, pitches used'). Missing are edge-case behaviors like what happens if no AU with note tracks is found or whether existing notes are affected, but the core behavior is well documented.

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 moderately long but well-structured: an opening definition, a comparative explanation, interval-direction examples, a duration-ratio explanation, and then a parameter list. Each sentence adds value, though the stylistic references ('Think Bach cello suites, Mozart operas, Chopin nocturnes') are somewhat tangential. The front-loaded purpose ensures the agent immediately knows what the tool does before diving into details.

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 (8 parameters, empty schema descriptions, no annotations, no output schema details), the description is remarkably complete. It covers the musical concept, the pitch relationship (above/below), the rhythmic behavior (ratio and defaults), velocity characteristics, and the target selection (unit_index/track_index). The output is mentioned, and the parameter semantics are fully explained. The only minor omission is explicit error behavior, but for a creation tool this is acceptable given the level of detail provided.

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 — and it does, comprehensively. Every parameter is explained: main_pitch and approach_pitch with defaults and pitch class (60=C4, 62=D4), duration_beats with a range (0.5-8), appoggiatura_ratio with a range and musical meaning (0.5-0.9, higher = more tension), velocity with accent behavior, unit_index and track_index with targeting semantics, and start_beat. This goes well beyond the bare schema and gives the agent actionable meaning for each field.

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 a specific verb+resource: 'Create an appoggiatura — leaning grace note that resolves to the main note.' It clearly defines the tool's purpose and distinguishes it from the sibling tool mordent by contrasting the expressive, resolving appoggiatura with the quick-flick mordent. It also places it within the baroque ornament family (trill, mordent, turn, appoggiatura), making its scope 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?

The description provides clear usage context by explaining when an appoggiatura is appropriate (expressive, tension-and-release) and explicitly contrasts it with the mordent ('Unlike a mordent (quick flick)...'). This gives the agent a decision rule for at least one alternative. However, it does not discuss when not to use the tool for other ornament types (trill, turn) or mention any preconditions such as needing an existing note track, so it falls short of fully comprehensive guidance.

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