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

No annotations are provided, so the description carries the full burden. It explains the core behavior (accent strength from beat position), lists all accent patterns with meanings, describes interpolation for off-beat notes, and states the return value ('Returns count of notes accented and per-level breakdown'). It does not explicitly state that existing velocities are overwritten or whether undo is possible, but the behavior is well disclosed for a creative 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 longer than average but earned every sentence: it uses clear headings, bullets for patterns, a compact parameter list, and a concise example. It is front-loaded with the main purpose and never wastes words on tautology or repetition of schema info.

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?

With 7 parameters, no annotations, and an output schema the description still covers all essential aspects: what the tool does, all patterns, interpolation behavior, parameter explanations, use cases, and return value. The example further grounds the abstraction. This is complete for an agent to invoke it correctly.

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 fully compensates by defining every parameter: unit_index, track_index, accent_pattern with allowed values, strong/medium/weak_velocity with ranges (0-1), and region_index with default meaning. The example additionally demonstrates usage, making parameter semantics exceptionally clear.

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 and resource: 'Apply beat-aware velocity accents to notes based on their position.' It clearly differentiates from the sibling tool apply_velocity_pattern by explicitly noting the difference (beat position vs. note index), so the agent can select it correctly.

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 explicitly contrasts with 'apply_velocity_pattern (which cycles by note index)' and provides a use cases list ('Make drum patterns feel groovy', 'Add natural dynamics to programmed basslines', etc.). This gives clear guidance on when to use the tool and names an alternative, satisfying the 'when/when-not/alternatives' criterion.

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

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

With no annotations, the description carries full burden. It discloses the algorithm (finds notes on strong beats, inserts anticipation before them), the structural transformation '[original note shortened] → [anticipation on weak beat] → [strong beat note]', and cross_track behavior that preserves original notes when set. This exceeds typical transparency.

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 long but appropriately so for an 11-parameter tool. It is logically structured: definition, comparison, structure, operational summary, genres, and parameter details. Every sentence adds value with no redundancy.

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?

The description covers the musical concept, algorithm behavior, all parameters, genre applicability, and cross-track options. An output schema exists, so not describing return values is acceptable. This is a complete, self-sufficient description.

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 coverage is 0%, yet the description compensates thoroughly by documenting all 11 parameters with ranges, defaults, and musical rationale, e.g., anticipation_offset '0.0625-0.5, default 0.25 = sixteenth note before' and direction options with meanings. No parameter is left unexplained.

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 opening line 'Add anticipation notes before strong-beat notes' is a specific verb+resource statement. The description further distinguishes this from sibling tools like passing tones, suspensions, and neighbor tones, making it unmistakably the anticipation ornament tool.

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?

Explicitly contrasts with 'passing tones (which connect two different pitches stepwise), suspensions (which hold a note into the next chord), and neighbor tones (which ornament a single note)' and names applicable genres (jazz, pop, Latin), providing clear when-to-use context and differentiation from similar tools.

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

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

No annotations are provided, so the description must carry the transparency burden. It does disclose that the tool creates an automation track, value clip, and value events, and states the prerequisite that the parameter must be automatable. However, it does not mention potential side effects such as overwriting existing automation, whether the operation is destructive, or error behavior if the parameter is not automatable.

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 concise and well-structured. It leads with a one-sentence purpose, then a brief behavioral note, followed by a clear bulleted parameter list and a closing constraint. No redundant information; every sentence earns its place.

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 tool with 4 params and no schema descriptions, the description is thorough: it covers all parameters, provides an example, states the automatable requirement, and mentions what it creates. It doesn't elaborate on return values, but an output schema exists, so that is acceptable. Minor gaps are not explaining how to discover valid effect_index/parameter_name values, but sibling tools cover that.

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 compensate. It does so admirably: each parameter is individually explained (unit_index, effect_index, parameter_name, points), including the expected format for 'points' with an explicit JSON example. This adds meaning well beyond the raw 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 a specific verb + resource: 'Add parameter automation to an effect on an audio unit.' It further clarifies by listing what is created (automation track + value clip + value events), distinguishing it from sibling tools like add_instrument_automation and create_automation_event by specifying the target is an effect on an audio unit.

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 clearly implies when to use this tool: when you want to automate a parameter on an effect. It does not explicitly name alternatives or state when not to use it, but the context is strong and the 'to an effect' scoping implicitly separates it from instrument automation or individual event creation.

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

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

With no annotations, the description explains what it creates (Revamp EQ → Compressor → Waveshaper), returns effect indices and parameter values, and describes the drive_amount range. However, it doesn't disclose whether it appends to or replaces existing effects on the target unit, which is a notable gap.

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 appropriately sized: it starts with the core function, then covers parameters in a clear list, states what it creates and returns, and finishes with practical examples. Every sentence adds value with no repetition.

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 and the presence of an output schema, the description covers all essential aspects: purpose, parameters, return values, examples, and relationship to alternatives. It is complete enough for an agent to select and invoke the tool correctly.

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 has no descriptions (0% coverage), but the tool description fully compensates: unit_index is explained, style lists all five presets with musical characteristics, and drive_amount includes range, default, and usage guidance. 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 clearly states the tool adds a ready-made bass processing chain (EQ → Compressor + optional Waveshaper) to an audio unit. It uses a specific verb and resource, and the explicit chain structure distinguishes it from sibling tools like add_effect or add_mastering_chain.

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?

It explicitly says 'One call replaces 2-3 individual add_effect + set_effect_parameter calls,' naming the alternative. It also notes it's designed for bass but works on any low-frequency content, giving clear context for when to use it.

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

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

With no annotations provided, the description carries the transparency burden. It discloses that the extension is calculated from the chord root, how the chord is found (root = lowest note), and includes return values. However, it omits error/failure behavior and whether the operation is reversible, leaving some uncertainty for a mutating 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 long but well-structured: a summary, detailed extension list with musical rationales, parameter specs, return statement, and a concrete example. Each section adds value, and the content is front-loaded with the core purpose. Slight verbosity in the extension list is justified by its usefulness.

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?

The description fully addresses the musical logic and returns, and includes an example call. However, it misses explanation of the three locator parameters (unit/track/region indices) and does not cover failure conditions or how the user obtains these indices. Given the tool's complexity and absent annotations, this is a notable gap.

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 coverage is 0%, so the description must fully explain parameters. It does well for extension, chord_position, octave, and velocity, but completely omits unit_index, track_index, and region_index — three required parameters. These are essential for targeting the chord, and the schema only lists them as titles with no additional meaning.

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 opening sentence 'Add a tension/extension note to an existing chord — jazz harmony' clearly identifies the action and target resource. It further explains the purpose ('This is how triads become jazz chords') and is distinct from sibling tools like add_suspension or add_passing_tones.

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?

Provides clear usage context with per-extension guidance on musical character and appropriate scenarios ('The most common jazz extension', 'Can clash with 3rd — use carefully'). It does not explicitly name alternatives or state when not to use, but the contextual guidance is strong enough.

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

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

With no annotations provided, the description carries the full burden and does a good job by detailing the exact signal chain created ('Gate → Revamp EQ → Compressor (→ Reverb)'), the return value ('Returns effect indices and parameter values set'), and the optional reverb behavior. It does not disclose edge cases like invalid unit_index or whether existing effects are preserved, but the level of disclosure is substantially above average.

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 front-loaded with the core purpose. It uses clear sections for parameters, chain construction, and examples. Every sentence contributes value—no filler—and the code examples at the end effectively illustrate usage patterns.

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 tool with an output schema and moderate complexity, the description is exceptionally complete: it covers the signal chain, all parameters, presets, return behavior, and provides three usage examples. The only minor gap is lack of error handling details, but that does not detract from overall completeness given the rich context.

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 has 0% description coverage, so the description fully compensates by documenting all three parameters: unit_index as 'Target audio unit', style with five named presets and musical character, and reverb_amount with range and suggested values. It adds semantic richness beyond bare type information, including genre examples for each style.

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 clearly states the tool's function with a specific verb and resource: 'Add a ready-made drum processing chain to an audio unit — Gate → EQ → Compressor (+ optional Reverb).' It also distinguishes itself from sibling tools by explicitly mentioning that one call replaces 3-4 individual add_effect + set_effect_parameter calls, making it unique among effect-related operations.

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 when-to-use context: designed for drum tracks but works on any rhythmic content, and an explicit efficiency advantage over manual effect chaining. However, it does not mention exclusions or alternatives like add_vocal_chain or add_mastering_chain, so usage guidance is strong but not exhaustive.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the basic action and return value, but does not disclose preconditions (e.g., how to determine unit_index), side effects (e.g., effect chain order, default state), failure modes, or reversibility. For a mutation tool, this is insufficient.

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 concise and front-loaded with the action. The effect_type list and return-value hint are useful, but there is minor redundancy in listing effect types after already naming the source tool. Overall, it is well-structured with no fluff.

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?

The tool is simple and the description provides valid effect types and the return value, as well as a connection to parameter-setting tools. However, it omits guidance on how to obtain unit_index and any behavioral caveats. The presence of an output schema and the description's return-value mention reduce the need for further return details, but the unit_index gap keeps it from being 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 thoroughly explain effect_type with a full list of valid values and a cross-reference to mcp_opendaw_list_effects. However, unit_index—a required integer—receives no explanation at all, leaving a critical gap for the agent.

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 clearly states the verb and resource: 'Add an audio effect to an audio unit's effect chain.' It distinguishes from related tools like mcp_opendaw_add_midi_effect by explicitly targeting audio effects. The enumeration of valid effect types further clarifies the exact scope of the tool.

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 references mcp_opendaw_list_effects for obtaining valid effect_type values and mentions using the returned effect_index with mcp_opendaw_set_effect_parameter, implying a clear workflow. However, it does not explicitly state when not to use this tool (e.g., for MIDI effects) or mention alternative tools like mcp_opendaw_remove_effect.

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

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

With no annotations, the description must fully disclose behavior. It adds valuable context about sample_level vs top-level parameters and the return value, but it does not mention potential side effects (e.g., whether existing automation is overwritten) or any required permissions, leaving meaningful gaps.

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 front-loaded with the purpose, then succinctly covers supported fields, parameter semantics, and return value. Every sentence provides useful information without unnecessary repetition or verbosity.

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 moderate complexity (4 parameters, conditional behavior) and lack of annotations, the description covers the core workflow effectively and even notes the return info. It could optionally mention prerequisites like instrument existence, but the presence of an output schema fills some 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?

The schema has no per-property descriptions (0% coverage), so the description's explanations of unit_index, parameter_name, points (including a JSON example), and sample_index (with default value -1) add essential meaning beyond the schema's raw types and names.

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 ('Automate a parameter on the instrument connected to an audio unit') and provides concrete examples of target instruments and fields (Vaporisateur cutoff, Playfield mute, etc.), clearly distinguishing it from sibling automation tools like add_automation or create_automation_event.

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?

It clearly establishes the context (automating instrument parameters on an audio unit) and explains the conditional usage of sample_index, but it does not explicitly name alternative tools or state when not to use this tool, stopping short of a 5.

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

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

With no annotations provided, the description discloses the exact effect chain created ('Revamp EQ → Compressor → Reverb (→ Delay)') and the return value ('Returns effect indices and parameter values set'). However, it doesn't state whether the chain is appended to existing effects or replaces them, nor does it mention error conditions (e.g., non-instrument units). This is a minor transparency gap.

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 front-loaded with a clear purpose, then uses bullet-style parameter explanations and illustrative examples. Though relatively long, every sentence adds functional value—no fluff or repetition. The structure makes the information easy to scan.

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?

The tool has moderate complexity (4 parameters, 5 style presets). The description covers purpose, parameter semantics, style selection, defaults, the exact effect chain, and return values. With an output schema present, this is sufficient for an agent to invoke the tool correctly across diverse use cases.

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 descriptions are entirely absent (0% coverage), so the description carries full responsibility for parameter meaning. It thoroughly explains unit_index, style (with five detailed preset definitions), reverb_amount (0-1, default), and delay_amount (0-1, default). The examples further illustrate parameter combinations, adding value beyond the empty 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 first sentence clearly states the action ('Add a ready-made instrument processing chain') and the exact resource ('EQ → Compressor → Reverb (+ optional Delay)'). It also specifies the target usage ('guitars, keys, synth leads, strings, pads'), distinguishing it from related chain tools like add_drum_chain or add_bass_chain.

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 explicitly frames when to use this tool: 'One call replaces 3-4 individual add_effect + set_effect_parameter calls.' It also gives concrete style recommendations for different instruments, making the use case clear. Although it doesn't name sibling alternatives directly, it defines its scope as 'any melodic/harmonic instrument,' which implies exclusions.

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

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

With no annotations provided, the description clearly states the mutation (adds a marker) and notes that markers are visible on the ruler. However, it does not disclose behavior around duplicate positions, validation, or success/error return, which would be valuable but is not critical for this simple 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 compact and well-structured: a one-sentence action summary, a brief explanatory note about markers, and parameter definitions. No filler or redundant content; every line serves a purpose.

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 simple two-parameter add tool, the description covers purpose, parameter semantics, and basic visibility behavior. An output schema exists, so the omission of return details is acceptable. It could mention duplicate handling or prerequisites, but overall it's complete for the tool's complexity.

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 input schema has 0% description coverage, but the description compensates fully by documenting both parameters: position_beats (Position in beats) and label (Marker text with examples). This is exactly the compensation needed when schema descriptions are absent.

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 'Add a timeline marker at a position', a specific verb + resource + location. It clearly distinguishes this from sibling tools like list_markers, delete_marker, and set_marker_label by stating it performs an add operation.

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 explains that markers label song structure points and are visible on the timeline ruler, giving clear context for when to use this tool. It doesn't explicitly mention alternatives or exclusions, but the intended use case is well implied.

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

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

With no annotations, the description carries the full disclosure burden. It does clearly state that the tool creates a chain (Revamp EQ → Compressor → Maximizer) on the output/master AU and returns effect indices and parameter values. However, it does not disclose whether this addition replaces or coexists with existing effects on the master bus, nor does it mention any destructive side effects or undo behavior—important for a mutating 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 front-loads the core purpose in the first sentence, then uses bulleted lists efficiently for parameter details. The final 'Creates' and 'Returns' lines summarize the behavior without redundancy. Every sentence adds value, and the structure is easy to scan.

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?

The output schema exists and the description states what is returned, so that area is covered. It clearly defines the target (output bus), the exact effect chain, and the meaning of both parameters. The missing piece is side-effect transparency (whether existing master effects are overwritten), which is not specified but might be inferred from 'add.' Given the tool's moderate complexity, the description is largely complete but leaves this one behavioral gap.

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 descriptions are empty (0% coverage), but the description fully compensates by explaining both parameters. target_lufs is given concrete examples (-14 = Spotify, -16 = Apple, -10 = loud), and style is documented with four distinct preset names and their sonic characteristics. This provides far more semantic meaning than the raw 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 a precise action: 'Add a ready-made mastering chain to the output bus — EQ + compressor + maximizer in one call.' It specifies the resource (mastering chain), the target (output bus), and the composition (EQ + compressor + maximizer), clearly distinguishing it from sibling tools like add_effect or add_vocal_chain.

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 gives clear context for when to use this tool: when the user wants a ready-made mastering chain on the output bus, saving the need for multiple effect-adding steps. It does not explicitly compare with alternatives like manually adding effects or using apply_full_mix, but the 'in one call' phrasing implies a preferred workflow. No exclusions are stated, which prevents the score from reaching 5.

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

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

With no annotations, the description carries the full burden for behavioral context. It discloses the chain location, the processing role of MIDI effects, the allowed effect_type values, the instrument-AU requirement, and the return value. It does not cover failure modes, but for an additive operation this is a strong set of disclosures.

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 concise and front-loaded: first sentence states the action, then provides context, parameter details, and return value. Every sentence earns its place with no redundancy.

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?

The tool is relatively simple with two parameters, and the description covers both parameters, the conceptual distinction, and the return value. It is sufficiently complete for an agent to invoke the tool correctly, though it could optionally mention the effect's position in the chain or error handling.

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 has zero coverage, so the description fully compensates by explaining both parameters: effect_type lists the allowed values and unit_index clarifies it must be an instrument AU. It also adds semantic meaning by describing what MIDI effects do, which is absent from the 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 begins with 'Add a MIDI effect to an audio unit's MIDI effect chain,' which is a specific verb and resource. It distinguishes MIDI effects from audio effects by referencing au.midiEffects vs au.audioEffects, setting it apart from sibling tools like add_effect.

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 explains that MIDI effects process note data before the instrument and are chained separately from audio effects, providing clear context for when to use this tool. It also notes that unit_index must be an instrument AU, not an output, acting as a prerequisite. However, it does not explicitly name alternatives or state when not to use it.

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

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

No annotations are provided, so the description carries full burden. It explains parameters and return value, but does not disclose side effects, error cases, or whether the operation is destructive. For a mutation tool, this is a significant gap.

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 a compact bulleted list with no filler. Every line provides necessary parameter or return information, earning its place.

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?

All parameters and the return value are covered, and an output schema exists. However, missing prerequisite context (e.g., device must already exist, index validity) and edge-case behavior make it not fully 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%, and the description compensates fully by explaining every parameter, including enumerating valid module_type values and clarifying x/y as grid positions.

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 clearly states 'Add a module to a Modular device' with a specific verb and resource. It distinguishes from sibling modular tools like list, connect, remove, and set param by focusing on the creation action.

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 guidance is given on when to use this tool versus alternatives, such as list_modular_modules or connect_modular_modules. No prerequisites are mentioned, like needing an existing Modular device or valid AU/effect indices.

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

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

With no annotations, the description carries the full burden of behavioral transparency. It clearly explains the three-part note splitting structure, parameter effects (e.g., neighbor_offset position, min_duration_beats skipping short notes), and cross_track behavior that preserves original notes. However, it does not explicitly state the destructive/reversible nature of the default operation on the source track.

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 front-loaded: a one-sentence summary, definition, structural breakdown, context, and then a thorough Args list. Every sentence serves a purpose—the music theory context and usage examples help the agent select the tool, while the Args section adds essential semantics not found in the schema. No redundancy or wasted words.

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?

This is a complex 11-parameter tool with no annotations or schema descriptions. The description covers the algorithm, all parameter semantics, behavioral nuances (skipping short notes, cross-track placement), and musical context. Since an output schema exists, the lack of return-value explanation is acceptable. The description is complete enough for correct selection and invocation.

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), but the description's 'Args' section compensates exceptionally well. Every parameter is explained with ranges, defaults, and musical reasoning (e.g., neighbor_velocity: 'default 0.6 — softer than the main note, as is traditional for ornaments'). This is more than sufficient for an agent to understand each parameter's meaning.

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: 'Add upper/lower neighbor tones to embellish existing notes.' It further distinguishes itself from similar tools by explaining the difference from passing tones and positioning it as the third of four non-chord tone techniques, making it clear which sibling tool this is.

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?

It explicitly contrasts with passing tones ('Unlike passing tones which connect two different notes, neighbor tones ornament a single sustained note'), giving the agent a clear decision point among ornamentation tools. It also mentions musical styles (Bach, jazz, country) but does not explicitly state when not to use this tool or provide a direct comparison to say add_suspension.

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

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

Annotations are absent, so the description fully carries the burden of behavioral disclosure. It explains the placement on weak beats, the direction options, the cross_track behavior (placing on another track to preserve original melody), and the default velocity being quieter. It does not explicitly state whether notes are inserted or modified in place or if it's reversible, but the cross_track option implies a non-destructive path. The level of detail significantly exceeds minimal transparency.

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 longer than average but well-structured: a lead sentence, an explanatory paragraph, a bulleted condition list, and a detailed Args section. Every part contributes to understanding. The musical examples (Bach, jazz, pop) add context but could be trimmed without losing core meaning. It is front-loaded with the essential purpose and maintains focus throughout.

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 tool with 10 parameters, no annotations, and a schema lacking descriptions, this description is exceptionally complete. It covers the musical goal, the exact conditions for operation, every parameter with meaning and defaults, and a notable behavioral option (cross_track). The presence of an output schema is not critical here since this is a mutation tool; the description fully equips an agent to decide when and how to use it.

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 input schema has 0% description coverage, but the description's Args section provides comprehensive semantics for all 10 parameters. It explains units, ranges, defaults, and even musical rationale (e.g., velocity default 0.6 'slightly quieter than melodic notes, as is traditional'). This goes far beyond the minimal schema types and titles, giving the agent everything needed to invoke the tool correctly.

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 clear, specific statement: 'Add passing tones between existing notes for smoother melodic lines.' It names the exact resource (passing tones between existing notes) and verb (add), and distinguishes itself from sibling tools like add_anticipation or add_neighbor_tones by focusing on interval-filling with scale steps. The musical context and conditions further clarify its unique role.

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 concrete conditions for when the tool is applicable (interval > 2 semitones, enough time gap, not exceeding max_interval) and gives musical examples (Bach, jazz, pop). It does not explicitly mention alternatives or when not to use it, but the conditions strongly imply the appropriate context. While not as explicit as naming alternative tools, it offers clear usage guidance beyond a vague 'use this for counterpoint.'

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

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

No annotations are provided, so the description carries the full burden. It explains the underlying mechanism (creating a SignatureEventBox on the signature track) and clarifies that this is different from setting a global default. However, it doesn't disclose whether this operation mutates existing events, whether there are constraints (e.g., position must be positive, denominator limited to powers of 2), or potential side effects on adjacent measures. The description adds some behavioral context but leaves these gaps.

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: a one-sentence summary, a paragraph contrasting with the sibling tool, and a compact bullet-style list of parameters. Every sentence earns its place, and the key info is front-loaded. No fluff or repetition of schema fields.

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?

The tool has 3 required parameters, an output schema, and no annotations. The description covers the core purpose, the key distinction from the sibling tool, and all parameters. It also mentions the return value ('Returns the created signature event details'), and since an output schema exists, it doesn't need to detail the exact structure. Minor gaps exist (e.g., no mention of validation, edge cases, or interaction with existing signature events), but given the tool's moderate complexity and the output schema, the description is largely sufficient.

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 coverage is 0%, so the description must compensate, and it does. It explains each parameter in plain language: position_beats is 'Position in beats where the change occurs,' numerator is 'Number of beats per bar (top number),' and denominator is 'Note value per beat (bottom number: 4=quarter, 8=eighth).' This adds musical meaning beyond the raw schema, though it could go further with acceptable ranges (e.g., numerator 1-32, denominator powers of 2).

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 clearly states the tool's function: 'Add a time signature change at a specific position in the track.' It specifies the verb (add), the resource (signature change), and the location (position in the track). It also explicitly distinguishes itself from set_time_signature by noting that it creates a SignatureEventBox on the timeline's signature track rather than setting the global default, which differentiates it from its sibling tool.

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 explicitly contrasts this tool with set_time_signature: 'Unlike set_time_signature (which sets the global default), this creates a SignatureEventBox on the timeline's signature track, allowing time signature changes mid-track.' This gives clear when-to-use vs. when-not-to-use guidance. It also provides a concrete example (4/4 → 3/4 → 4/4) illustrating the intended mid-track use case.

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

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

No annotations are provided, but the description compensates with detailed behavior: it specifies that notes on strong beats are targeted, preparatory notes are placed a step above/below and snapped to scale tones, velocities are given with musical rationale, and cross_track behavior is explained. However, it does not explicitly state whether original notes are modified or preserved on the source track, which 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 starts with a concise purpose sentence, then builds context with the suspension definition, structure, and algorithm. The Args section is logically ordered. The cultural flourish about Bach chorales and film scores adds context but is not strictly necessary, making it slightly less concise than ideal.

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 complex tool with 11 parameters and no schema descriptions, the description provides thorough documentation of the algorithm, parameter effects, and musical intent. It does not mention error cases or prerequisites such as needing metrical information to find strong beats, but overall it is highly complete for an AI agent to invoke the tool correctly.

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 input schema provides zero descriptions, but the Arg list covers all 11 parameters with types, defaults, ranges (e.g., preparation_beats 0.25-2.0), scale list, and musical context (e.g., 'down' = classic 4-3, 9-8 suspension). This fully compensates for the schema's lack of detail.

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 opening line 'Add suspension-resolutions to existing notes' clearly states the action and resource. The subsequent explanation of the suspension structure (Preparation → Suspension → Resolution) and the algorithm makes it easy to distinguish from sibling ornament tools like add_passing_tones or create_appoggiatura.

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 explains that the tool operates on existing notes, targets strong beats, and creates suspensions, giving clear context for when to use it. However, it never explicitly mentions alternatives or states 'use this instead of X,' so it lacks explicit exclusions.

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

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

With no annotations, the description carries the full burden. It discloses that a ValueEventBox is created, explains the normalized value mapping and automatic conversion, and states the return value (created event and tempo map). This is informative, though it doesn't mention idempotency or effects on existing tempo changes.

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 with a brief overview, internal details, and a parameter list. It is reasonably concise, though it could trim some redundancy (e.g., repeating 'BPM' multiple times). Overall, every sentence adds value.

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 moderate-complexity tool, the description covers purpose, parameters, internal behavior, and return value. The output schema exists, so the return format is already structured. The description is complete for selection and invocation.

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 coverage is 0%, so the description fully compensates by explaining each parameter: position_beats (position in beats), bpm (target BPM, 60-240), and interpolation ('linear' vs 'hold'). This exceeds the raw schema and provides clear meaning and valid values.

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 clearly states the tool adds a tempo change at a specific position, using a specific verb ('Add') and resource ('tempo change'). It distinguishes itself from siblings like set_bpm and create_tempo_ramp by focusing on mid-track automation and explicitly mentions creating a ValueEventBox on the tempo track.

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 implies usage for mid-track BPM automation with examples (120→90→140 BPM) and explains interpolation options. It lacks explicit 'when not to use' or alternative tool mentions, but the context is clear enough for an agent to infer appropriate use.

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

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

With no annotations, the description takes on full disclosure responsibility. It details the exact chain created ('Revamp EQ → Compressor → Reverb (→ Delay)'), states the return value ('Returns effect indices and parameter values set'), and explains preset behavior. However, it does not explicitly state whether the chain is appended to existing effects or replaces them, nor does it mention error scenarios (e.g., invalid unit_index), which would be useful for full transparency.

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 thorough yet well-organized: opening summary, benefit statement, parameter details in structured bullet-like lines, chain output, and three practical examples. Every sentence contributes useful information without redundancy, making it easy for an agent to parse quickly.

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 params, 5 presets, output schema) and zero annotations, the description is remarkably complete. It covers purpose, parameter semantics, behavioral details, return values, and usage examples, leaving no significant gaps for an agent to guess about. The output schema handles formal return structure, so the description's mention of return contents is sufficient.

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 coverage is 0%, so the description must fully document parameters, and it does. Every parameter is explained: unit_index ('Target audio unit'), style with five detailed preset descriptions, and both amount parameters with ranges and defaults. This far exceeds what the schema provides, making invocation behavior predictable.

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 first sentence clearly states the tool's function: 'Add a ready-made vocal processing chain to an audio unit — EQ + compressor + reverb (+ optional delay).' It also distinguishes itself from siblings by explicitly noting 'One call replaces 3-4 individual add_effect + set_effect_parameter calls' and specifies scope ('Designed for vocal tracks but works on any melodic content').

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 explicit guidance on when to use this tool: it replaces multiple add_effect and set_effect_parameter calls, making it the efficient choice for standard vocal chains. It also differentiates from other chain tools (mastering, drum, bass, instrument) by focusing on vocal/melodic content, giving clear context for appropriate usage.

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

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

The readOnlyHint annotation already declares the tool safe, and the description adds substantial context about the metrics, the 10-segment RMS contour, and compression suggestions. It also clarifies the input format (WAV file in exports directory or absolute path). No contradictions with annotations. A 5 would require even richer operational detail, but this is solid.

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 structured logically: a one-line summary, a bulleted metric breakdown, compression guidance, argument explanation, and return summary. Every sentence carries useful information—no fluff. Despite length, it is efficiently organized and scannable for an agent.

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 multi-metric analysis tool, the description covers everything: what the tool does, the meaning of each metric, interpretation thresholds, input specification, and return content. The output schema further enriches context, so the description need not restate structured return types. This is complete for informed selection and invocation.

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 input schema has no description for 'filename', but the description fully compensates: 'Name of the WAV file in the exports directory (without path), or absolute path to any WAV file.' It resolves ambiguity about path resolution and file type, adding meaning beyond the schema's bare 'Filename' title.

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 clearly states the tool performs 'Dynamics analysis' with specific metrics (crest factor, loudness range, transient density, segment RMS) and 'Measures the dynamic character of a track.' This specific verb+resource combination distinguishes it from siblings like analyze_spectrum, analyze_stereo, and measure_lufs.

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 detailed compression decision guidance with quantitative thresholds (e.g., 'crest_factor < 6 dB → heavily compressed'), which implies when to use the tool for dynamic evaluation. However, it does not explicitly name alternative tools for other analysis types, so it stops short of the 'explicit alternatives' bar for a 5.

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

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

Annotations declare readOnlyHint=true, and the description discloses several behavioral traits beyond that: it identifies chords using the same logic as identify_chords, returns specific analysis outputs (chord change positions, durations, rate, density, stable/active sections, total events), and notes the data source is MIDI notes. This adds substantial context about what the tool does with input and what it produces.

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 appropriately structured with a clear summary, bullet-point output list, comparison to related tools, usage suggestions, parameter definitions, and a return value statement. Each section earns its place without redundancy.

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?

The tool has an output schema (though its content is not shown in the provided context), so return values may already be documented there. The description covers usage context, input semantics, and output types at a level appropriate for the tool's complexity. It could be improved by explaining why region_index defaults to -1 meaning 'first' rather than all regions, but overall it is complete for selection and invocation.

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%, but the description includes a brief parameter list with defaults and meanings (unit_index, track_index, region_index with -1 = first and -2 = all regions, group_tolerance as beats of tolerance, min_notes as minimum notes). Though concise, it provides essential semantics for all five parameters.

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 clearly states the tool's purpose: analyze harmonic rhythm (how fast chords change and where), listing the specific outputs. It distinguishes itself from sibling identify_chords by explicitly focusing on the temporal pattern of harmony.

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 explicitly says when to use this tool vs alternatives, naming identify_chords as complementary and listing three specific sibling tools to use with it: analyze_song_structure, reharmonize_progression, and create_arrangement_variation.

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

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

Annotations declare readOnlyHint=true, so the tool is known to be safe. The description adds meaningful behavioral detail beyond the annotation: it explains how phrases are grouped (by rests > 1 beat) and what the return object contains. This is useful context without contradicting the annotation.

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 long but well-organized with sections and bullet points. Every sentence adds value, but the output feature list (10 items) and use-case list (5 items) could be tightened without losing meaning. Front-loaded core statement ensures quick comprehension.

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 (detailed musical analysis) and the presence of an output schema, the description is remarkably complete. It covers what the tool does, what it returns (even beyond the schema, e.g., phrase analysis details), when to use it, and parameter explanations. The inclusion of an example call reinforces correct invocation.

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 has 0% description coverage, but the description compensates with a clear param section: 'unit_index: AU index, track_index: Note track index, region_index: Region (-1 = first region).' It also provides a code example showing positional usage, making parameter semantics explicit and actionable.

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: 'Analyze melodic content — contour, intervals, direction, climax.' It then enumerates a detailed list of outputs (contour profile, interval histogram, step/leap ratio, etc.), making the tool's function unmistakable. The specificity distinguishes it from broader sibling tools like mcp_opendaw_analyze_track or mcp_opendaw_note_stats.

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?

A dedicated 'Useful for:' section lists five concrete scenarios, such as 'understanding a melody before variation/reharmonization' and 'feeding analysis to create_motif_variations.' This provides clear context on when to use the tool, though it does not explicitly mention when not to use it or name alternative tools for comparison.

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

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

Annotations provide readOnlyHint=true, and the description adds substantial context: it runs four analysis modules, produces 'prioritized mix_suggestions' and a 'master_check' with platform-specific LUFS targets. This goes beyond the annotation's safety signal, though it doesn't discuss error handling or performance characteristics.

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 front-loaded: a one-sentence summary, followed by a numbered list of modules, output details, and an Args section. Every sentence provides value, and the formatting makes it easy to scan quickly. No redundant or filler content.

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 complex tool combining four analyses with one parameter and an output schema, the description is thorough. It covers the purpose, the constituent modules, the output (suggestions, master_check, LUFS targets), and the filename parameter. Since an output schema exists, the description doesn't need to detail return fields, and it provides enough context for correct usage.

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 input schema has one parameter (filename) with no description (0% coverage), but the description fully compensates: 'Name of the WAV file in the exports directory (without path), or absolute path to any WAV file.' This clearly explains the format and accepted alternatives, leaving no ambiguity.

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 clearly states it provides 'complete mix diagnosis in one call' by combining track, spectrum, stereo, and dynamics analysis. It distinguishes itself from the individual analyze_* siblings by explicitly listing the four modules it aggregates, making the tool's purpose specific and 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?

It offers clear guidance: 'The agent can call this single tool instead of 4 separate calls, getting a complete picture for mix decisions.' This implies using it when a holistic analysis is needed and names the individual alternatives, though it doesn't explicitly state when to use the separate tools (e.g., when only one analysis is needed).

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

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

Beyond the readOnlyHint annotation, the description adds substantial behavioral context: the specific phase checks performed, the rationale (mono compatibility), frequency-dependent risks, and what the return value contains. This is genuinely useful information that helps an agent interpret results safely.

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 tightly structured: a one-line summary, bulleted list of checks, two lines on frequency context, and a final parameter explanation. Every sentence contributes information, with no filler or repetition.

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 single-parameter analysis tool with an output schema, the description is complete. It covers what the tool does, what it detects, how to specify the input, and what the result is about. The output schema handles the exact return format, so no additional detail is needed.

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?

With schema description coverage at 0%, the description fully compensates by explaining the filename parameter in detail: 'WAV file in exports dir, or absolute path.' This is essential guidance that turns an otherwise opaque string parameter into a usable one.

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 and resource: 'Per-band phase analysis — coherence, polarity, inter-channel delay.' It then lists concrete checks and the final output (mono compatibility score), clearly distinguishing this from sibling analysis tools like analyze_stereo or analyze_spectrum.

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 clearly implies when to use this tool by explaining what problems it detects (phase issues that damage mono compatibility) and provides contextual guidance about low vs. high frequency behavior. However, it does not explicitly name alternatives or state when NOT to use this tool.

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

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

Annotations declare readOnlyHint=true, and the description consistently presents this as a read-only analysis operation, so no contradiction. It adds behavioral detail beyond the annotation: the algorithm (scans bar-by-bar, computes features, groups consecutive bars, classifies segments) and the output structure (per-segment classification with bar range, density, energy, feature summary). This is useful context, though it could also mention edge cases or data requirements.

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 with a clear opening, algorithmic overview, use-case list, and parameter breakdown. It is somewhat long (multiple paragraphs), but each section adds value and the information is front-loaded. A tighter version could combine the algorithm and use cases, but the current format is readable and 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?

Given the tool's moderate complexity and presence of an output schema, the description is complete: it explains what it does, the algorithm, the parameters, the output type, and typical use cases. It does not need to describe return values in detail because an output schema exists. The description fully equips an agent to decide when and how to call this tool.

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 carry the burden. It does: 'unit_index: AU index (-1 = all AUs)' and 'bars_per_segment: Minimum bars per structural segment (default 4)...' This adds meaning beyond the plain integer types and defaults in the schema. It could be richer (e.g., valid ranges for unit_index) but is adequate.

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 clearly states a specific verb+resource: 'Analyze song structure by segmenting MIDI content into structural parts.' It details the method (bar-by-bar feature extraction, grouping, classification into intro/verse/chorus/etc.), and distinguishes from siblings by focusing on analysis and structural segmentation, not creation or editing.

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?

Provides explicit use cases: 'Essential for: understanding existing arrangements, finding where sections change, verifying song form, and planning variations or extensions.' This gives clear context on when to use. However, it does not mention when NOT to use it or contrast with alternative analysis/creation tools, so it misses the 'when-not' part for a full 5.

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

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

The readOnlyHint annotation already declares it as a safe read operation. The description adds substantial context: input requirements (WAV file in exports directory or absolute path), the exact return content (band-by-band analysis, global descriptors, mix suggestions), and semantics of each metric (e.g., spectral_centroid as brightness). No contradiction with annotations.

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?

Well-structured with a clear opening line, bullet-point frequency bands, metric definitions, and usage examples. The length is justified by the density of useful information; every sentence contributes value, and critical information (purpose, workflow, args) is front-loaded.

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?

Covers input expectations, output content (band-by-band analysis, global descriptors, mix suggestions), and interpretation guidance. With an output schema present, it doesn't need to detail exact return types, but it provides sufficient context for correct invocation and result usage.

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?

Although schema coverage is 0%, the description fully compensates with the Args section: 'filename: Name of the WAV file in the exports directory (without path), or absolute path to any WAV file.' This precisely specifies the single parameter's format and acceptable values, going beyond the bare schema definition.

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 clearly states the tool's purpose: 'Spectral analysis of audio across 7 ISO frequency bands' followed by detailed band definitions and metrics. This distinguishes it from sibling analysis tools like analyze_stereo, analyze_dynamics, and analyze_mix by focusing specifically on spectrum analysis.

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?

Explicitly provides usage context: 'Use after analyze_track for mix decisions' and gives concrete interpretation rules (e.g., high low_high_ratio → bass-heavy mix, low spectral_centroid → dark/muffled). This tells the agent when to invoke the tool and how to act on the results.

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

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

Annotations provide readOnlyHint=true, and the description adds behavioral context by explaining it reads a WAV file and computes stereo metrics. It also clarifies filename semantics (exports directory or absolute path) and gives detailed metric definitions, going beyond the minimal read-only annotation.

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 long but well-structured with a summary header, detailed metric bullet points, mix decision guidance, and an Args section. The information density is high and each section serves a purpose, though it could be slightly trimmed without losing value.

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?

The description covers input (filename), output (stereo descriptors, per-region width, mix suggestions), and interpretation (decision thresholds). Even though an output schema exists, the description goes beyond by explaining metric ranges and actionable guidance, making it complete for an agent to invoke correctly.

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 only provides the parameter title with no description (0% coverage), but the description's Args section fully explains the filename parameter: 'Name of the WAV file in the exports directory (without path), or absolute path to any WAV file.' This fully compensates for the lack of schema detail.

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 clearly states 'Stereo analysis of audio' and lists specific outputs like stereo_width, lr_balance, and phase_correlation. It distinguishes itself from sibling tools such as analyze_mix or analyze_dynamics by focusing on stereo-specific metrics and per-region width.

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 'Mix decision guidance' section provides explicit thresholds (e.g., stereo_width < 0.1 means narrow) that indicate when to act on results. However, it does not explicitly mention when not to use this tool or how it compares to other analysis tools, so it lacks explicit exclusions.

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

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

The annotation declares readOnlyHint=true, and the description adds substantial behavioral context: it runs multiple analyses in a single call, returns a comprehensive set of audio metrics, and requires a filename. It does not describe failure modes, but given the read-only annotation, the description adds enough useful context beyond what annotations provide.

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 somewhat long, but it is well-structured: purpose, pipeline context, parameter explanation, return fields, and a usage example. Each section adds practical value, though the example repeats some return-field info. It is appropriately sized for the tool's composite nature.

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?

The description covers all essential aspects: what it does, when to use it, how the parameter is specified, what it returns, and a concrete usage example. With an output schema present, the return-value listing is extra but helpful. There are no significant gaps for an agent to invoke it correctly.

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 input schema provides zero description for the filename parameter (schema description coverage is 0%). The description fully compensates by explaining both accepted forms: a filename relative to the exports directory or an absolute path to any WAV file, and includes an example. This is excellent parameter-level guidance.

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 'Full audio analysis in one call — BPM + key + LUFS + duration + dynamic range' which explicitly states what the tool does. It further clarifies that it is a composite of detect_bpm + detect_key + measure_lufs, clearly distinguishing this integrated tool from its single-purpose siblings.

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: it is a composite tool that eliminates three separate calls and is essential for the Suno remix pipeline. It names the individual tools being combined, but does not explicitly state when one would prefer the single-purpose alternatives over this composite, though that is implied by the efficiency rationale.

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

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

With no annotations, the description carries the full burden and does well: it explains that the tool deterministically reshapes note durations, details each articulation's specific effect (e.g., 'staccato — shorten notes to fraction of their grid slot'), and states the return value. However, it does not explicitly mention irreversibility or in-place modification, though the sibling undo tool exists; this small gap keeps it from a 5.

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 long but appropriately so for a tool with 5 parameters and 4 articulation variants. It uses clear sectioning, bullet lists for parameters, and concrete examples. No sentence is superfluous; each adds either definitional precision or practical guidance, making the length justified.

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?

Despite no annotations and zero schema descriptions, the description covers the tool's purpose, parameter semantics, return type, examples, and relationship to sibling tools. It even explains the algorithmic behavior for each articulation and the impact of amount. The tool is complex, but the description leaves little ambiguity about what will happen when invoked.

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%, but the description fully compensates by explaining every parameter: unit_index, track_index, region_index (with the -1 special case), articulation (with per-type behavior), and amount (with per-articulation meaning and examples). This far exceeds what the bare schema provides, giving the agent complete parameter understanding.

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 and resource: 'Apply articulation to existing notes' and enumerates the articulation types. It also explicitly distinguishes the tool from siblings: 'Unlike velocity_curve (dynamics) or humanize (random), this applies deterministic duration ratios', making its scope and unique purpose unmistakable.

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 names two direct alternatives (velocity_curve, humanize) and explains why this tool is the right choice for deterministic articulation: 'Unlike velocity_curve (dynamics) or humanize (random), this applies deterministic duration ratios'. This gives clear when-to-use guidance relative to at least two siblings, and the examples further illustrate appropriate invocations.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It includes important behaviors: timing and duration remain unchanged, original pitch range center is preserved, and snapping to scale degree is optional. However, it does not explicitly state the destructive nature (e.g., that pitches are overwritten) or mention undo/restore implications beyond the preserve flags, leaving a slight transparency gap.

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 structured cleanly: purpose statement, algorithm explanation, contour definitions, and args list. Every sentence adds value—no redundant repetition of schema titles or types. It is front-loaded with the primary action and scales into necessary detail without bloat.

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 9 parameters, no annotations, and an existing output schema (so return values need not be described), the description is remarkably complete. It covers the algorithmic behavior, all contour semantics, parameter nuances, and even provides a differentiation from a sibling. This equips the agent to invoke the tool correctly in context.

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 for the schema's lack of parameter docs. It does this thoroughly: each parameter is explained with units, ranges, defaults, and allowed values (e.g., range_semitones '1-48, default 12=octave', full contour list, scale list). This is essential and well-executed.

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: 'Apply a melodic contour shape to existing notes.' It further details the behavior (redistributes pitches while keeping timing/duration) and explicitly contrasts with transpose_notes ('uniform shift'), making the tool's unique purpose unmistakable and well-differentiated from siblings.

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 explicitly names the alternative transpose_notes and explains the difference: 'Unlike transpose_notes (uniform shift), this reshapes the melody direction.' This provides a clear when-to-use/when-not-to-use signal, telling the agent to reach for this tool when reshaping contour rather than shifting uniformly.

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

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 details the exact chain assignment per track, the return value, and the meaning of parameters. However, it does not mention potential side effects such as whether existing chains are overwritten, or whether the operation can be undone. This is a minor gap given the tool's clear mutation intent.

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 front-loaded, starting with a one-line summary, then alternative guidance, parameter details, chain assignment, return value, and examples. Every sentence adds value; there is no fluff. The bullet points and code examples make it easy to scan.

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?

The description covers all four parameters, behavioral details, return value, and provides examples. It is quite complete for a complex tool. However, it does not explicitly mention prerequisites (e.g., that the unit must contain note tracks) or edge cases (e.g., what happens if num_tracks exceeds available tracks). These gaps are minor given the tool's clarity.

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%, but the description compensates thoroughly. It explains each parameter in detail: genre lists all supported values, unit_index identifies target, num_tracks explains track roles (0=drums, 1=bass, 2+=melodic), and master_lufs gives reference targets. The chain assignment section further elaborates how parameters map to behavior.

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 clearly states a specific verb+resource+scope: 'Apply a complete mix in one call — genre-aware processing chains on every track + mastering.' It explicitly distinguishes itself from sibling tools by naming the individual chain tools it replaces (add_drum_chain, add_bass_chain, add_instrument_chain, add_mastering_chain).

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 explicit guidance on when to use this tool: 'Replaces 5-6 separate calls (add_drum_chain + add_bass_chain + add_instrument_chain × N + add_mastering_chain).' It also gives concrete examples with different genres and LUFS targets, which clarifies the intended use cases.

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

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

With no annotations, the description carries the full transparency burden. It discloses detailed genre-specific behavior (timing/velocity/swing values), track-level effects (drums get most, bass stays tight), and that it returns the applied parameters. It does not explicitly state whether it mutates the actual MIDI notes or how it interacts with prior humanization, but the coverage is substantial.

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 front-loaded with a clear purpose statement, followed by structured sections: context, genre recipe bullets, parameter list, return value, and a concrete example. It is long, but every sentence contributes necessary behavioral or semantic detail for a complex tool with 7 parameters and 14 genres. Nothing feels redundant.

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 and the existence of an output schema, the description is remarkably complete. It covers the workflow context (post-arrangement), all parameter semantics, genre-specific recipes, track roles, and provides a usage example. The only minor omission is an explicit prerequisite statement, but the examples and opening context imply it clearly.

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 coverage is 0%, so the description must compensate — and it does. It explains the genre parameter with an explicit list of allowed values, defines unit_index as 'AU index with the arrangement tracks', interprets the track indices, and clarifies has_4th_track in the context of 3- vs 4-track genres. This adds essential meaning beyond the bare parameter names.

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: 'Apply genre-aware humanization to arrangement tracks — makes programmed MIDI feel alive.' It clearly distinguishes itself from generic humanization tools (e.g., humanize_notes, apply_swing) by emphasizing genre-awareness and the arrangement-track context.

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 contextual guidance: use it after creating an arrangement because notes are quantized/robotic. Examples explicitly show calls after create_jazz_arrangement and create_dnb_arrangement. However, it does not explicitly name alternative tools to use instead (e.g., humanize_notes) or exclusion cases, so it stops short of perfect guidance.

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

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

No annotations are provided, so the description carries the full disclosure burden. It details per-track effect recipes (compressor+EQ, saturation, reverb/delay, sidechain) and specifies genre-specific variations. It also discloses sidechain behavior and returns the effects added per track, giving full visibility into the operation's outcome.

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 uses tight lead sentences, bulleted recipe lists, a compact parameter explanation block, and two clarifying examples. Each section earns its place without redundancy, and the most important information (purpose and workflow) is front-loaded.

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?

With 4 parameters and zero schema descriptions, this description covers all necessary invocation context: usage scenario, workflow position, genre-specific behavior, parameter constraints, and return value. The output schema exists, and the description states it returns 'effects added per track and parameter values', so no critical information is missing.

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%, but the description thoroughly compensates for every parameter: genre lists the 11 allowed values, unit_index is defined as 'AU index with the arrangement tracks', num_tracks is specified as '3 or 4, must match arrangement', and sidechain is described as 'drums→bass' with genre-family guidance. This is exactly what the agent needs to invoke correctly.

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?

Description opens with 'Apply genre-specific mixing effects to tracks after creating an arrangement' – a specific verb+resource+context. It clearly distinguishes itself from sibling tools like create_*arrangement and manual effect-chaining calls by positioning itself as the connection between arrangement creation and rendering.

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?

Explicitly places tool in the workflow: 'Closes the loop: create arrangement → apply genre mix → ready to render.' It also states this replaces '10-20 manual add_effect + set_effect_parameter calls', directly identifying the alternative. Examples pair it with specific arrangement-creation functions (create_dnb_arrangement, create_jazz_arrangement), making when-to-use unmistakable.

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

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

With no annotations, the description carries full burden. It explains the operation, parameter format, and return value, but lacks details on side effects (e.g., whether existing settings are overwritten, behavior on invalid indices), reversibility, or prerequisites. It adds useful context but not complete behavioral disclosure.

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 slightly verbose but every sentence is informative. It is front-loaded with the primary purpose, then details the parameter format, examples, and return value. The structure is logical and scannable, though a bit dense.

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 single-parameter tool, the description is quite complete: it covers the main use case, parameter format, built-in options, and return value. However, it does not differentiate from similar batch tools like apply_full_mix or apply_genre_mix, and misses edge cases like invalid presets or partial application. Given no annotations, it's strong but has 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?

The input schema has a single 'preset' parameter with zero description coverage. The description fully compensates by providing the exact JSON structure, named presets, and multiple examples. This is exemplary parameter documentation that goes far beyond the 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 clearly states 'Apply a mix preset to all audio units in one call — volume, pan, mute, solo.' This specifies the action, target scope, and attributes, distinguishing it from individual set_track_* tools. It also mentions the batch nature, which separates it from siblings.

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 explicitly says 'Replaces 10-30 set_track_volume/set_track_panning/set_track_mute calls,' providing a clear alternative and when this tool is beneficial. It does not explicitly state when NOT to use it, but the context strongly implies the batch-vs-individual tradeoff.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It describes the note distribution algorithm in detail ('If fewer onsets than notes: extra notes are placed at the nearest onset'), the effects of velocity/duration modes, and notes that it returns 'a modification summary with repositioned note count.' It implies in-place modification by saying 'repositions existing notes.' It does not discuss undo or reversibility, but the level of detail is strong given the lack of annotations.

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 long but every section is purposeful: a summary sentence, numbered algorithm steps, a parameter glossary, and a usage example. It is structured and front-loaded with the one-line purpose, making it easy to scan.

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 tool with 8 parameters and no schema descriptions, the description covers all parameters, behavior, precedence, and an example workflow. It also mentions the return value ('modification summary'), and since an output schema exists, we don't need exact return fields. The only minor gaps are edge cases like empty note regions, which aren't critical for typical use.

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 has 0% coverage, but the description defines every parameter, including default values and precedence (e.g., 'onset_grid: ... Takes priority over rhythm_string'). It explains valid values for velocity_mode and duration_mode with examples, providing far more semantics than the schema alone.

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 first sentence states a specific action: 'Apply a rhythmic pattern to existing notes — reposition onsets to match a target grid.' It also explicitly distinguishes itself from extract_rhythm ('This is the inverse of extract_rhythm'), establishing a clear purpose unique among siblings.

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?

It explains when to use this tool by framing it as the inverse of extract_rhythm, saying it 'lets you stamp a groove onto any note content,' and provides a concrete example workflow ('Extract groove from drums, apply to bass'). It does not, however, list exclusions or alternatives beyond extract_rhythm, so it's clear but not exhaustive.

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

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

No annotations are provided, so the description carries the full burden. It clearly states that it creates automation events on the volume parameter and returns the event count and pattern info. However, it does not disclose potential side effects such as whether existing automation is overwritten or appended, whether the operation is reversible, or any preconditions like unit/track existence.

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?

Well-structured and front-loaded with a one-line summary. The mechanism, parameter list, return info, and an example are all included, and each sentence serves a purpose. The parameter explanations double as usage guidance, keeping the description efficient.

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?

Covers purpose, mechanism, parameters, return value, and an example. With the output schema present, describing return details in more depth is unnecessary. Missing only brief preconditions (e.g., valid unit_index/track_index, potential need for existing AU), but overall complete for an 8-parameter tool.

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 coverage is 0%, and the description fully compensates. Every parameter (unit_index, track_index, bars, start_beat, depth, attack, release, kick_interval) is explained with meaning, ranges, and practical examples—e.g., depth: '0.6 = volume drops to 40% on each kick'—adding far more value than 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?

Uses a specific verb+resource: 'Apply sidechain ducking via volume automation'. Clearly distinguishes from the sibling connect_sidechain tool by stating it 'Simulates sidechain compression' rather than performing actual routing, and from set_track_volume by describing automation creation.

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?

Provides clear context by describing the effect as 'the signature sound of house, techno, EDM, and modern pop', implying when this tool is appropriate. The description of how it works ('by creating volume automation') implicitly differentiates it from real sidechain tools, but it does not explicitly state alternatives or when not to use it.

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

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

No annotations are present, so the description carries full burden. It discloses key behavioral traits: no velocity/duration changes, deterministic, no randomness, reversible, and returns per-track note counts shifted. This gives the agent a solid safety and side-effect profile.

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 structured with a purpose statement, parameter details, return value, and a usage example. Every sentence adds value; there is no fluff or redundancy.

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?

With no annotations and a rich schema, the description covers what the tool does, when to use it, parameter semantics, return value, and an example. This leaves no significant gaps for an agent to select and invoke the tool correctly.

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 coverage is 0%, but the description explains all four parameters in detail: unit_index, track_index, swing_amount (including range and musical examples like 0.55-0.66 for hip-hop/lofi), and grid (with default and interpretation). This fully compensates for the missing schema descriptions.

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 action: 'Apply swing feel to existing notes without changing velocity or duration.' It also explicitly contrasts with humanize_notes, making the purpose and distinction from siblings clear.

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 explicitly states when to use this tool versus an alternative: 'Unlike humanize_notes (which couples swing with random velocity/timing changes), this tool applies pure swing.' This tells the agent when to choose this over a known sibling.

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

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

No annotations are present, so the description carries the full burden. It discloses the deterministic mapping mechanism (each note's position to a velocity value), details each curve's mathematical behavior, and states the return value. It stops short of noting irreversibility or clamps on out-of-range inputs, but the disclosure is substantial.

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?

Well-structured: purpose, mechanism, differentiation, parameter specs, return value, then three practical examples. No sentence is wasted; the length is justified by the tool's complexity and 0% schema coverage.

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 7-parameter tool with no annotations and no schema-side parameter descriptions, this description is fully complete. The curve_type values are individually explained, defaults are given, return semantics are stated, and concrete usage examples anchor the behavior.

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%, yet the description documents all 7 parameters with defaults, ranges (0-1 for velocities), and behavioral meaning. 'power' gains extra semantic depth ('2.0 = sharp attack, 0.5 = slow swell'), and region_index's -1 sentinel is explained. This fully compensates for the empty 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 a specific verb+resource ('Apply a velocity envelope across notes') and lists the curve variations (ramp, arc, trough, power curve). It explicitly distinguishes itself from the sibling humanize_notes, making the tool's identity 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?

It states when to use the tool ('useful for build-ups, fade-ins, crescendo rolls, and expressive phrasing') and explicitly contrasts it with humanize_notes for random variation. This gives an agent clear criteria for choosing this tool over an alternative.

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

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

With no annotations provided, the description carries the full burden and delivers substantial behavioral context: it explains the oscillating algorithm, parameter formulas (e.g., 'modulates ±depth*center'), and the return payload (notes_processed, min/max/avg stats). However, it does not explicitly state that the operation mutates note velocities in place or warn about destructiveness/reversibility, which would have made it fully transparent.

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 front-loaded with the core purpose, then uses a compact Args block with one line per parameter, followed by a Returns section. Every sentence adds information—the differentiation sentence, parameter examples, and return field list all serve purpose without redundancy. The structure is scannable and efficient for an 8-parameter tool.

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?

The description covers the tool's operation, all parameters, output format, and sibling differentiation, which is strong given the lack of annotations and schema descriptions. Minor gaps remain: no mention of prerequisites (e.g., the target track must be a note track with notes) or error/empty-region behavior, but the core knowledge needed to invoke the tool correctly is present.

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%, but the description fully compensates by documenting all 8 parameters with rich detail: rate includes beat-cycle examples (0.25=every 4 beats, 1.0=per beat), shape enumerates the waveform options and their meanings, phase explains starting positions, and center gives the exact modulation formula. This exceeds what a typical schema description would provide.

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: 'Apply periodic velocity modulation — velocity LFO along note positions,' which precisely states what the tool does. It further clarifies by contrasting with 'apply_velocity_curve (monotonic ramps)' and emphasizing 'REPEATING velocity patterns synced to beat positions,' distinguishing it from sibling velocity tools.

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 explicitly names the closest alternative (apply_velocity_curve) and states when to choose this tool over it: for 'pumping, breathing, or wave-like dynamic motion' and repeating patterns rather than monotonic ramps. It also provides concrete scenario descriptors ('pumping, breathing, wave-like') that signal appropriate use cases.

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

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

With no annotations, the description carries the full burden. It discloses the exact formula for final velocity, explains cycle vs stretch modes, and states the return payload (notes modified, pattern applied, velocity preview). It doesn't mention irreversibility, but the behavior is well-specified.

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 with a clear opening, parameter list, formula, and examples. It's somewhat long but every sentence carries meaningful information; the examples add practical clarity without being redundant.

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 6-parameter tool with no annotations, the description is remarkably thorough: it covers all parameters, modes, the underlying formula, return values, and practical examples. It also situates the tool against alternatives, making it easy for an agent to decide when to invoke it.

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 descriptions are 0% covered, so the description must and does explain every parameter: unit_index, track_index, pattern (with JSON example), region_index, mode (with definitions), and base_velocity (with default and formula). It even provides multiple examples showing parameter combinations.

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 uses a specific verb and resource: 'Apply a cyclic velocity pattern to existing notes in a region.' It clearly distinguishes from linear ramps/crescendos and positions itself as the accent/groove tool, differentiating it from siblings like apply_velocity_curve or apply_velocity_lfo.

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 explicitly contrasts with linear ramps ('Instead of a linear ramp (crescendo)...') and provides concrete use cases (backbeat emphasis, syncopation, dynamic layers). It implies when to use this tool but doesn't explicitly name alternative tools or exclusions beyond the linear ramp contrast.

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

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

With no annotations, the description carries full burden. It discloses factor effects, mode behavior on note positions (including potential overlaps/gaps), the possibility of skipped notes, and the return value. It omits explicit claims about reversibility or in-place modification, but covers core side effects adequately.

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 with a clear summary, factor bullets, a musical example, parameter definitions, and return information. It is longer than minimal but justified by complexity; the Beethoven/Bach example, while illustrative, is not essential for an AI agent, making it slightly less concise than a 5.

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?

It covers core functionality, all parameters, return behavior, and provides real-world context for use. It lacks explicit edge-case handling (e.g., invalid factor range or no notes present) but the mention of skipped notes covers some. Given the output schema captures exact return structure, this is adequately 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 coverage is 0%, so the description is the sole source of parameter meaning. It thoroughly explains every parameter: factor range and effect, unit_index as AU index, track_index as note track, region_index defaulting to -1 for all regions, and mode with two detailed behaviors. This far exceeds the schema's bare type information.

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 and resource ('Augment or diminish note durations') and immediately identifies it as the 'fourth classical transformation', clearly distinguishing it from transpose, reverse, and invert. This makes the tool's purpose unambiguous and differentiates it from sibling tools.

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?

It provides clear guidance on when to use augmentation vs diminution through factor ranges, and explains the two modes ('scale' and 'stretch') with practical implications for note positions. However, it does not explicitly name alternative tools for other transformations or state when not to use this tool, though it implies complementarity with transpose/reverse/invert.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It reveals the iterative loop (render → measure LUFS → adjust Maximizer threshold → re-render), convergence tolerance (±1 LUFS), and return values (final LUFS, threshold, iterations, WAV path). It does not state side effects on the project (e.g., whether the original mix is modified), but it gives substantial insight into its 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: a one-sentence purpose, a concise algorithm outline, a bullet-style parameter list, and a clear return statement. Every sentence adds meaningful information without repetition or unnecessary detail.

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?

The description covers the tool's purpose, algorithm, parameter semantics, and return values. Since an output schema exists, return details need not be exhaustive. The main missing piece is whether the tool operates on the entire project mix or a specific track, but the name and 'output volume' imply the master output. Overall, it is sufficiently complete for an agent to invoke it correctly.

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%, but the description explains all four parameters thoroughly: target_lufs includes platform examples, filename notes that no .wav extension is appended, sample_rate and max_iterations both state defaults. This fully compensates for the missing schema descriptions and adds practical guidance.

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 first sentence explicitly states the tool's function: 'Auto-adjust output volume to hit a target LUFS.' This uses a specific verb (auto-adjust), resource (output volume), and outcome (target LUFS), clearly distinguishing it from siblings like measure_lufs (measurement only) or export_mix (export only).

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 by mentioning common streaming loudness targets (Spotify -14, YouTube -14, Apple -16) and describing the iterative process to achieve a target. It does not explicitly name alternative tools or exclusions, but the use case is strongly implied through these examples.

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

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

No annotations exist, so the description carries the full burden. It discloses a key side effect: 'Automatically creates the automation track if it doesn't exist yet.' It also explains it generates multiple events and returns a preview. However, it does not mention whether existing automation events are overwritten, whether the operation is reversible, or any error conditions, which is significant for a write 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 well-organized with an overview, parameter list, return note, and example. Every section is useful, though it is somewhat long. The parameter list is necessary given the 0% schema coverage, and the example is valuable. Minor redundancy: the first sentence and the later transition mention overlap.

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?

The description covers purpose, full parameter semantics, return value, and a notable side effect (track creation). It is complete enough for an 8-parameter tool with no annotations. It lacks explicit error handling or edge-case info (e.g., what if start_beat > end_beat), but the provided details are strong.

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 input schema has zero descriptions (coverage 0%), so the description must compensate. It does so thoroughly: every parameter is documented with units (beats, normalized values 0.0-1.0), defaults (steps=16, curve='linear'), curve options with guidance ('exp' for filter sweeps), and an example that ties them together. This exceeds the baseline needed.

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 clear verb+resource+scope: 'Create a smooth automation sweep (ramp) between two values over a beat range.' It further explains the mechanism (generates interpolated events) and gives concrete examples (filter sweeps, volume fades), distinguishing this general-purpose tool from more specific siblings like create_filter_sweep or create_volume_fade.

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 states context—'creating smooth parameter transitions'—and lists typical use cases (filter sweeps, volume fades, pitch drops). It does not explicitly name alternatives or exclusions, but the use cases make it clear when this tool is appropriate. Lacks explicit 'use this instead of X' guidance.

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

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

No annotations are provided, so the description takes on the full burden. It discloses the algorithm: reads current average velocities, computes scale factors, and applies them in multiply mode, preserving original relative dynamics. It also notes that per-track velocity stats are returned before/after. This provides solid behavioral insight, though it does not explicitly state reversibility or edge-case handling (e.g., out-of-range targets), which keeps it from a 5.

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 comprehensive but well-organized with clear sections: overview, preset list, parameter definitions, return value, and examples. It is longer than average, but every section adds necessary detail for the tool's complexity. The front-loaded overview immediately conveys the core purpose, and the structured preset list is easy to scan. The lack of a brief parameter list for unit_index slightly affects structural completeness.

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?

The tool has 5 parameters and an output schema, and the description covers the key aspects: purpose, preset behavior, parameter formats, and return value (per-track stats). It includes practical examples for both preset and custom modes. The missing unit_index definition is the primary gap, and since the output schema exists, the description appropriately avoids re-explaining return structure. Overall, the description is complete enough for typical use, but the unit_index omission prevents 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?

Schema description coverage is 0%, so the description must compensate. It thoroughly explains track_indices, preset (listing all preset options with target values), target_velocities (format and requirement to match count), and region_index (special values -1 and -2). The only gap is unit_index, which appears only in the example (as the first argument) without explicit explanation in the parameter list. This is a notable omission but the example infers its usage.

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 and resource: 'Balance velocities across multiple tracks — MIDI mix leveling.' It clearly states the tool sets relative velocity levels across multiple note tracks. It also explicitly distinguishes itself from the sibling tool scale_velocity, which handles one track at a time, making the purpose unmistakable.

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 context is explicit: the tool is for balancing velocities across multiple tracks, with a direct comparison to scale_velocity ('Unlike scale_velocity (one track at a time)'). It also provides presets for specific musical genres/mix intentions, giving clear 'when to use' guidance. Examples further illustrate the intended call patterns.

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

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

With no annotations provided, the description carries the transparency burden and does so well: it enumerates the checks, the triage severity categories, the return structure, and the input format. It does not explicitly state that the operation is read-only, but 'diagnostic' strongly implies a non-mutating analysis.

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 longer than average but well-structured with numbered sub-checks, bullet points, and a short example. The first sentence front-loads the core purpose. Some redundancy exists between 'Produces a prioritized triage report' and the later return summary, but the structure keeps it scannable.

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 complex batch tool with an output schema, the description covers the input parameters, the per-stem analysis pipeline, the severity classification, and the result shape. It does not need to detail every return field because an output schema exists, and the provided example gives a concrete preview.

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 explains filenames as either a JSON array or comma-separated list of WAV filenames, and genre as an optional profile. This adds meaningful type and usage context 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 starts with a specific verb and resource: 'Run full diagnostic on multiple stems in one call', listing the three sub-analyses performed. It clearly distinguishes itself from siblings like detect_problems, analyze_phase, and compare_to_profile by framing it as their batch combination.

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 makes clear this is for multi-stem diagnostics, mentions that phase analysis applies only to stereo files, and notes genre comparison is optional. It does not explicitly state 'use this instead of calling individual analysis tools', but the context is adequately conveyed.

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