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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered. The description adds real behavioral value beyond that: execution happens locally on the MCP host, there is an external binary dependency, and two specific file classes fail with a message. It does not describe cost or latency for long files, which keeps it below 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?

One dense sentence, but it is front-loaded with the core action and the analysis list before the dependency and failure caveats. The output enumeration is long, though each item is meaningful rather than filler.

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?

There is no output schema, so the description carries the return-value burden, and it does so thoroughly by naming the measurements returned alongside the clip's own settings (warping, gain, pitch). Prerequisites and known failure modes are included, leaving nothing an agent needs to call it correctly out of scope.

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 100% schema description coverage and a single required parameter already documented with an example ('tracks/2/slots/0/clip'), the baseline is 3. The description's inline 'tracks/N/slots/M/clip' restates the same path shape without adding new semantics.

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?

Specific verb (Analyze) plus resource (source file of an audio clip) and an explicit enumeration of what is extracted: format metadata, LUFS, sample/true peak, RMS, six-band frequency profile. It also distinguishes itself from sibling read tools (get_properties, clip_action) by making clear it inspects the underlying source file rather than the clip's Live settings.

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?

Gives a clear precondition (ffmpeg and ffprobe must exist on the MCP host) and explicit exclusions (compressed Ableton .aif and REX files cannot be analyzed and report so). It does not name a sibling alternative for the unsupported formats, but the when/when-not conditions are unambiguous.

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?

Goes well beyond the destructive/idempotent annotations by disclosing undo semantics (history undo reverts all; device parameter writes create extra entries), execution order on the main thread, on_error stop/continue behavior, partial-application consequences, the 100-op cap, and the BATCH_FAILED outcome shape.

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?

Purpose and undo constraint are front-loaded, followed by ops format, references, example, error policy, and capability lists. Dense but nearly every clause carries required information; the batchable/not-batchable lists are long yet load-bearing.

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 output schema, the description still documents the failure response (BATCH_FAILED with every op's outcome), execution ordering, reference resolution, and limits. An agent has everything needed to construct a valid batch and predict 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: the '$N.field' reference syntax, type preservation for whole-string refs, list indexing, and on_error default/continue semantics. This meaningfully extends the schema's terse field 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?

States a specific verb+resource+benefit: run several tools in one round trip and one undo step. It clearly distinguishes batch orchestration from the individual sibling tools and explains the scoping (undo granularity) that makes it unique.

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 lists which tools are batchable and which are not, with reasons (e.g. not undoable edits, they combine calls or wait). An agent can decide membership and routing without inference.

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 already declare this a safe, idempotent read, and the description goes well beyond them: it explains index-building on first search (short slices, a few seconds, Live stays responsive), cache persistence until refresh:true, and that heavy sample libraries are only indexed when named. The only minor gap is that refresh:true invalidation semantics could be slightly crisper.

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?

Front-loaded with the purpose, then densely packs mode behavior into a single semicolon-structured paragraph with no filler. It is long, but each clause carries actionable detail; slight tightening of the index/search phrasing would help readability.

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 output schema, the description does the work of explaining returns: paged items each with a path, ranked results with exact and prefix matches first. It is nearly complete; only the index action's own return and search result shape beyond ranking are left implicit.

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 already 100%, so the baseline is 3, but the description adds real meaning: concrete path examples ('instruments/Drift/Bass'), per-action kind defaults, the differing limit defaults (100 list vs 25 search), the default root set, and that every item carries a path for deeper browsing.

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?

States specific verbs and resource: explore/search Live's browser, and enumerates the browsable content (instruments, presets, effects, drum kits, packs, user library). It distinguishes itself from siblings by routing load actions to load_item, so an agent can tell it apart without opening schemas.

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 covers the three modes (list default, search, index), the defaults that select each, and names load_item as the tool to use once a path is found. Nothing about when to pick each mode is left to inference.

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 already declare non-read-only, idempotent, non-destructive, and the description is consistent with that. It adds genuinely useful context beyond the annotations: 'The parameter stays wherever the ramp had taken it,' meaning cancellation freezes the current value rather than reverting it — an important behavioral detail 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?

Two tightly written sentences, front-loaded with the action and scope, with no wasted clauses. Both sentences carry information an agent needs.

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 one-parameter, no-output-schema tool whose annotations cover idempotency and destructiveness, the description is nearly complete: it covers scope and post-cancellation state. It could note whether the parameter must currently have an active ramp, but nothing critical 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 coverage is 100% for the single parameter, and the schema already states 'omit to cancel all'. The description reiterates that semantics but adds no syntax or format detail beyond it, so the baseline 3 applies.

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?

States a specific verb (cancel) and resource (ramp) and defines the scope precisely: one parameter's ramp, or all active ramps when omitted. The distinction from the sibling ramp_parameter is inferable (cancel vs. create) but never named explicitly, so it stops short of a 5.

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 via the omit-to-cancel-all rule, which tells the agent when to pass the parameter and when not to. It does not name an alternative tool (e.g. ramp_parameter) or state prerequisites, so guidance is implied rather than explicit.

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 already flag destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context: that the call reports whether an envelope existed and that the change is a single undo step, which matters for a destructive mutation.

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?

Two tight sentences, no waste, with the operating scope front-loaded before the return-value and undo notes.

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?

No output schema exists, and the description covers the return value (whether an envelope existed) as well as the undo behavior. Complete enough for a two-parameter destructive tool, though it could note any permission or state prerequisites.

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 100%, so both parameters are already documented in the schema, including the 'omit to clear all' semantics. The description restates the same omission behavior without adding format or address syntax beyond the schema, so baseline 3 applies.

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?

States a specific verb (clear) and resource (envelope on a Session clip) and distinguishes itself from siblings like get_automation and draw_automation. The dual-mode scope (single parameter vs all envelopes) is spelled out precisely.

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 is implied by the verb and the two operating modes, but the description never explicitly says when to choose this over get_automation or draw_automation, nor states any prerequisite. Adequate but leaves routing to the agent.

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 already flag destructiveHint=true and idempotentHint=false, and the description goes further: crop 'discard[s] everything outside the loop', crop/quantize each cost 'one undo step', and the `expect` guard 'refuses to act on the wrong clip'. It also discloses envelope-copy and envelope-to-arrangement-automation side effects, which the annotations cannot express.

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?

Length is defensible for 11 actions, but it is delivered as one dense run-on paragraph heavy with parentheticals and semicolons, with no per-action structure. The opening clause is front-loaded well, yet the middle is hard to scan, so each sentence only partly 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 an 11-parameter, 11-action tool with no output schema, it covers preconditions, side effects, undo cost, and even the return value ('the clip's length and loop after the action'). Minor gaps remain (e.g., detailed behavior of stop_scrub, error modes), but nothing an agent needs to call it 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 coverage is already 100%, so baseline is 3; the description nevertheless adds real semantics beyond the schema: the actual grid enum values (rec_q_quarter, rec_q_eight, ...), `amount` 0-1 with default 1, sample_time defaulting to 'where it changes nothing', and the meaning of `beat_time`/`distance` as retiming. Only the omission of explicit defaults for a few params keeps it off 5.

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?

Starts with a specific verb+resource ('Edit a clip in place') and then enumerates the exact 11 operations with what each does, letting an agent separate clip-level edits from the note-level siblings (edit_notes, transform_notes) and from automation siblings. MIDI-only vs audio-only scoping is stated per 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?

Gives per-action preconditions and routing ('clip must be playing' for move_playing_pos; MIDI only for duplicate_loop/quantize_pitch; audio-only for warp markers) and names a genuine alternative workflow by telling the agent to use draw_automation on the Session clip first for arrangement automation. It does not systematically cover when *not* to use a given action, but the when-to-use coverage is well above average.

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 cover only the safety triad; the description adds real behavioral context: output is new tracks with addresses/devices/clips, audio_to_midi runs in the background and the call blocks up to 15 s, results depend on Live edition, and it constitutes one undo step. These are exactly the traits annotations cannot convey 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?

Dense but front-loaded: the overarching purpose leads, then per-action definitions, then address/return/timeout details. Every clause carries information, though the packed parenthetical listing makes it slightly heavy to parse in one pass.

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 output schema, the description compensates by describing the return value (new tracks with addresses, devices, clips) and the background/timeout behavior for audio_to_midi. An agent has everything needed to call it correctly and interpret the result.

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 100%, so baseline is 3, but the description adds cross-parameter meaning the schema lacks: `address` refers to a different entity per action (clip, drum pad, or Simpler), and `type` is scoped to audio_to_midi only. That conditional mapping is genuinely useful beyond the flat enum 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?

States a specific verb+resource (Live's audio conversions) and enumerates each action with its concrete outcome, so an agent can distinguish convert from siblings like analyze_audio_clip or clip_action. The scoping to audio clips/pads/Simplers is explicit.

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?

Each action's purpose is spelled out (check vs audio_to_midi vs simpler_track vs drum_rack_from_clip vs pad_to_track vs slice_to_drum_rack), giving clear context for selection. However, it never states when NOT to use this tool or names an alternative for overlapping cases, so it stops short of explicit routing.

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 only declare write, non-idempotent, non-destructive; the description adds substantial behavioral context beyond them: existing objects shift so addresses must be re-read, color is snapped to a palette and reported back, audio clips are auto-warped and report length, and the whole operation is one undo step. This is exactly the extra context annotations cannot supply.

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?

Front-loaded with purpose and densely informative, with no filler sentences; each clause earns its place by clarifying a kind-specific rule. It is a single unbroken block rather than bulleted per-kind, which slightly hurts scannability for a nine-variant enum, but the content is not bloated.

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 nine-kind creation tool with no output schema, the description covers required parameter combinations, defaults, address formats, side effects, and even what the result reports back (length, applied color). Nothing an agent needs to invoke it correctly 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 coverage is 100% and schema descriptions are terse ('What to create'), so baseline is 3. The description adds real semantics: which parameters are relevant per kind, the -1/omit append convention for index, the 'tracks/2/slots/0' address format for empty slots, and time-in-beats meaning. This exceeds what the schema conveys.

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?

States a specific verb (Create) and enumerates the exact resources it can produce (track, return track, scene, MIDI/audio clip, arrangement clip, take lane). Distinguishes itself from siblings like duplicate and load_item by scope and by returning the new object's address. An agent can tell what it does without opening the schema.

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?

Gives per-kind usage rules (which parameters apply to which kind, defaults like length=4 or index=-1 to append) and a negative exclusion ('Cue points cannot be created'). However, it never routes the agent to alternatives such as duplicate or load_item, so it stops short of explicit when-to-use-this-vs-sibling 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?

Annotations only flag destructiveHint/idempotentHint; the description adds that one undo step reverses the delete, that the mandatory name guard yields GUARD_FAILED when the name no longer matches, and the untouchable-object rules (cue points, master track, last scene). This is behavioral context the agent could not get from annotations alone.

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?

Front-loaded with the verb and target enumeration, then moves through destructive semantics, guard, and edge cases. Dense but nearly every clause carries decision-relevant information; the cue-point parenthetical is slightly convoluted but not padding.

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 target syntax, guard semantics, destructive/undo behavior, and the main refusal cases. With no output schema, it never states what a successful call returns (beyond the GUARD_FAILED error), which is the one remaining gap for a mutation 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 already 100%, yet the description still adds real meaning: the accepted address forms per object type, the exact `expect` payload shape ({"name": ...}), why the guard exists (index shifting), and the failure mode when it mismatches. That is well beyond the schema's terse 'What to delete'.

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?

Names a specific verb (Delete) plus every addressable resource type, with concrete path syntax for each ('tracks/N', 'returns/N', 'scenes/N', clip and arrangement paths). An agent can tell this apart from the sibling create/duplicate tools immediately.

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?

Gives explicit when-not conditions: cue points cannot be deleted, the master track cannot be deleted, a Set always retains one scene, and indices shift after create/delete so the object must be read first. It stops short of naming an alternative sibling (e.g. history for undo) but the preconditions are unusually clear.

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 already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description goes beyond by disclosing what is NOT captured (playhead, play state, meters ignored) and the stability contract of fingerprint/hash values. Doesn't state output size or performance characteristics, but the semantic-stability contract is valuable behavioral context.

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?

Front-loaded with the core purpose; every sentence carries information (structure, identity, stable comparison, lighter mode). Slightly dense but no 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?

For a read-only introspection tool with no output schema, the description covers what's returned (settings, tracks with address/kind/mixer/devices/clips, scenes) and identity semantics. Return value shape is inferred rather than explicit, but adequate for an agent to call correctly and interpret fingerprints.

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 100% (include_clips documented with type and default). The description adds the consequence of the flag ('clip counts and hashes stay'), which is helpful but baseline 3 applies when schema already covers the parameter.

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?

Opens with a specific verb+resource: 'A compact map of the whole Set'. Clearly distinguishes itself from sibling getters (get_properties, get_health, get_capabilities) by describing a full structural snapshot including tracks, scenes, mixer state, devices and clips.

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?

Explicit when-to-use guidance: 'compare fingerprints to detect edits, or hashes to see which track changed' and 'Set include_clips=false for a lighter summary'. Names concrete alternatives for achieving specific goals.

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 supply only the generic destructive/non-idempotent profile, and the description materially extends it: 'One undo step', the explicit DESTRUCTIVE list (delete, clear_pad, remove_macro, delete_variation), that Live refuses bad placements and explains why, that move returns where the device landed, and that delete_variation refuses when nothing is selected. That is exactly the kind of failure-mode and side-effect detail annotations cannot carry.

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?

It is dense and front-loaded — the core operation is stated first, then each action is unpacked in a compact clause. The single mega-sentence makes scanning harder than a bulleted structure would, but given 16 actions almost every clause carries decisive information.

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 16-action, 12-parameter mutation tool with no output schema, the description covers address forms, per-action parameters, guards, failure behavior, undo semantics, and the return value ('the new address where one is created'). Nothing an agent needs to invoke it correctly 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 coverage is 100% so baseline is 3, but the description adds genuinely new cross-parameter semantics the schema cannot express: which parameters are valid per action, that `expect` is a mandatory guard for delete/clear_pad, the meaning of 'song' as an address for re_enable_automation, and the enumerated method names for `call` per device type.

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 'Change device structure' states a verb and resource, and the per-action enumeration makes the scope concrete against a large action enum. However it never differentiates itself from siblings that appear to overlap (create, duplicate, delete), so an agent cannot tell whether device-level deletion belongs here or to delete without inspecting both.

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?

For nearly every action it supplies the triggering context and prerequisites: which address type applies (track/chain vs device vs drum pad), that `expect` is mandatory for delete/clear_pad, that position defaults to end, and that recall_variation/delete_variation behave differently when nothing is selected. It stops short of naming alternatives, so there is no explicit 'use X instead when...' routing against sibling 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?

Annotations declare destructiveHint=true and idempotentHint=false, and the description goes well beyond them: what replace destroys (rebuilds the parameter's envelope), how merge preserves out-of-range breakpoints, edge-filling via hold, the one-undo-step-per-call cost, and the stored-value readback. This is exactly the behavioral context a mutation tool needs.

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?

Front-loaded with the core action, then organized parameter-by-parameter; nearly every sentence carries load-bearing detail. It is dense and long, though a reader must parse several embedded clauses to extract defaults, which slightly hurts scannability.

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?

No output schema exists, and the description compensates by noting the result includes a readback of Live's stored values. Combined with the Arrangement-clip limitation and undo cost, an agent has everything needed to call this destructive 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?

Even with 100% schema coverage, the description adds real meaning: concrete address grammars for clip and parameter, points expressed in beats from clip start with values in the parameter's own units ('get_device shows min/max'), the point-level curve shaping the segment after it, and resolution semantics that differ per style. This exceeds the schema's terse field notes.

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?

States a specific verb and resource ('Draw a clip automation envelope for a device or mixer parameter, inside Live') and adds scope qualifiers (tempo-locked, sample-accurate). It is immediately distinguishable from siblings like get_automation, clear_automation, and ramp_parameter.

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?

Gives clear conditions for internal choices (style breakpoints vs steps, mode replace vs merge) and a hard exclusion ('Arrangement clips have no envelopes in Live's API'). However, it never names sibling alternatives such as ramp_parameter or clear_automation, so the agent must infer routing between 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?

Annotations establish this as a non-read-only, non-idempotent, non-destructive write. The description meaningfully adds the placement rule (copy lands immediately after the source; a duplicated slot goes into the next scene), the return value (new address), and the unsupported cases. It stops short of noting permissions or what happens on invalid addresses.

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?

Three tight sentences: what can be duplicated first, then placement/return behavior, then the exclusion. No filler, and the most decision-relevant content 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?

For a single-parameter mutation with no output schema, the description covers accepted inputs, placement behavior, the return value, and the negative cases, which is everything an agent needs to call 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 coverage is 100% and the schema already provides address examples, so the baseline is 3. The description adds some interpretable meaning (the N-index convention implied, and that scene addresses may use name: syntax) but largely restates the formats the schema documents.

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?

States a specific verb (duplicate) and enumerates the exact resource types accepted (regular track, scene, clip slot) with their address forms. This clearly distinguishes it from siblings like create and convert, which an agent could otherwise confuse with duplication.

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 strong selection context by listing accepted address patterns and explicitly excluding return tracks and the master, which prevents wasted calls. It does not, however, contrast this tool against the sibling 'create' or explain when duplicating is preferred over creating fresh.

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?

Adds substantial behavior beyond the annotations: one undo step, DESTRUCTIVE for remove and replace, replace restores old notes if Live refuses the new notes, unknown ids refused with NOT_FOUND and nothing changed. The `expect` guard against the wrong clip and the note about modify keeping note ids and per-note events are real behavioral disclosures. No contradiction with destructiveHint=true.

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?

Dense but front-loaded: first sentence states the core purpose, then per-action clauses. Every clause carries operational meaning. It is long, but for six distinct actions with conditional parameters that length is earned; minor friction from comma-spliced clauses.

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 18 params, no output schema, and annotations covering safety, the description does the essential work: tells the agent how each action consumes parameters, the failure modes (NOT_FOUND, restore-on-refusal), and the undo/expect guards. It does not describe the return payload, but with no output schema that is a minor gap; it is otherwise complete enough 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?

Schema coverage is 100%, so baseline is 3. The description goes further by mapping parameters to actions (e.g. `ids` + `set` for modify, `notes` cleared range, `transposition` semitones, `destination_time`), clarifying which fields apply to which action – value beyond the flat 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?

States a specific verb (change existing notes) and resource (notes in a MIDI clip), and enumerates the six action variants with their semantics. Distinguishes clearly from get_notes, write_notes, and transform_notes by being the edit-existing-notes 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?

Explicitly says to get ids from get_notes, and notes that unknown ids are refused with NOT_FOUND with nothing changed. Per-action prerequisites (e.g. remove needs exactly one of ids/range/all, replace needs notes) are given. No explicit sibling routing like 'use transform_notes for generative edits', but usage context is strong.

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?

Despite annotations only marking readOnly=false and destructive=false, the description discloses deep behavioral traits: emulation on a 10 ms timer, ~40 ms early trigger, once-per-pass execution, quantization-dependent timing, and that configurations are memory-only, lost on restart/reload, not undoable and not batchable. This is exactly the kind of context annotations cannot carry.

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?

Dense and front-loaded, with the tool's nature stated first and mode-specific detail following. The run-on parenthetical sentences pack a lot in but remain readable; a little could be trimmed without loss, but nothing is wasted filler.

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, stateful, timing-sensitive tool with no output schema, the description covers activation conditions, timing caveats, persistence limits, and undoability. An agent has everything needed to invoke it correctly without opening the source.

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 100%, so the baseline is 3, but the description adds real semantics: `actions` may be names or {action,weight} objects chosen by weight each pass, the relative action set (next, previous, etc. relative to the clip's own track), and that after_bars/after_beats default to one pass through the clip. These go beyond the terse 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?

Opens with a specific verb+resource ('Clip follow actions') and immediately distinguishes the capability from what Live's API provides natively. The three modes (set/clear/status) are enumerated, so an agent knows exactly what the tool covers and how it differs from siblings like clip_action or launch.

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?

Gives concrete operating conditions: it only acts while transport runs and the clip plays, once per pass, and recommends q_none or matching quantization for tight timing. It does not explicitly name alternative tools or say when NOT to use follow actions in favor of another sibling, but the modal guidance is strong.

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 destructive=true/non-idempotent, and the description earns credit on top by specifying exactly what gets destroyed per mode (replace_span vs replace_all vs additive add), that the whole operation is one undo step, that dry_run previews, and that the result warns if music overruns the clip's loop end.

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?

Front-loaded with the core action and undo behavior, then parameters in backticked order. Dense but almost every clause carries actionable information; the generator-name roster and parenthetical examples add some bulk.

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?

No output schema exists, and the description compensates with the dry_run preview hint and the loop-overrun warning. Prerequisites, help discovery, modes, and offset semantics are all covered; only a fuller account of the return payload (e.g. created note count or error shapes) 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the terse schema strings: start_time is measured in beats and offsets everything, mode semantics are spelled out, and address is tied to the required clip prerequisite. `expect` is left to 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?

States a specific verb (compose notes), the target resource (a MIDI clip), and the distinguishing mechanism (from a generator, in one undo step). The enumerated generator list makes it clearly distinct from plain note-writing siblings like write_notes or edit_notes without needing to name them.

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?

Gives concrete prerequisites and routing: create the clip first via `create kind midi_clip`, and use generator 'help' to discover parameters. Explains the mode choices and when each applies. It stops short of explicitly stating when to prefer this over write_notes/edit_notes, so no exclusion 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?

Annotations already establish readOnly/idempotent/non-destructive, so the burden is lighter, yet the description still adds real behavioral detail: default max_points of 500 and the `truncated` flag disclosing possible partial results, plus breakpoint/step semantics via jump_from. Only pagination-style navigation beyond the cap is left unstated.

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?

Front-loaded with the core action and refines it in one dense but well-ordered paragraph: return shape, semantics, cap behavior, then the use case. Slightly packed, but virtually every clause conveys information.

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 output schema, the description carries the return-value burden and does so thoroughly: breakpoint structure, units, jump_from semantics, per-envelope cap, and truncation signal. Nothing an agent needs to call and interpret the result 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 coverage is 100%, so baseline is 3, but the description goes further by explaining that `parameter` restricts output to one envelope, `max_points` caps each envelope, and jump_from marks a step's preceding value. It adds meaning beyond the schema text rather than repeating it.

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?

Specific verb (Read) plus resource (a Session clip's automation), with the return shape ({time, value, jump_from?}) spelled out. The closing clause 'before drawing over it' implicitly routes the agent away from draw_automation/clear_automation, so the purpose is distinguishable 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?

Gives clear usage context: inspect existing automation before overwriting it, and states the parameter-scoping option. It does not explicitly name draw_automation as the alternative or state when-not to use this tool, so it falls short of a full when/alternatives statement.

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 already cover the safety profile (readOnly, idempotent, non-destructive), so credit goes to the extra behavioral context: the description warns that a beta build reports variant 'Beta' and edition 'unknown' because the edition is unreadable, and that callers should trust `features` instead. That is a genuinely useful quirk disclosure beyond the annotations, though no rate limits or call-order constraints are mentioned.

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?

Two sentences, front-loaded with the primary payload and followed by a targeted caveat about beta builds. The enumeration is dense but each item earns its place; the second sentence exists specifically to prevent a misread of the edition field.

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 parameters, no output schema, and full annotation coverage, the description carries the burden of explaining return content, which it does by listing the reported fields and the bridge-command listing. It is complete enough to invoke correctly, with only a minor gap around how the feature probe values should be interpreted.

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 tool takes zero parameters, so the baseline is 4. The description correctly implies a no-argument introspection call and does not invent parameter semantics that do not exist.

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 states a specific resource and enumerates exactly what it reports: script version/build id, Live version and variant, unavailable features, feature probes, and bridge commands. It is distinct from siblings like get_health or get_properties, though it never explicitly contrasts itself with them.

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 is implied rather than stated: the caveat 'rely on `features`, never on the edition' tells the agent how to interpret and act on the output, and 'Also lists every bridge command' hints at discovery use. There is no explicit when-to-use or when-to-prefer-an-alternative guidance relative to get_health or get_properties.

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 already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds substantial context about the result shape (the `specific` block for plugin devices, where a Simpler's sample lives). It does not discuss pagination or performance, but discloses what the read returns beyond the 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 read purpose is front-loaded, but the paragraph then drifts into detailed set_properties mechanics (value field, quantized labels, `items`) that belong to the sibling tool, not to a read definition. Several sentences about other tools don't earn their place here, making the description bloated and hard to parse.

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 output schema and a simple one-param input, the description carries the return-shape burden and does so thoroughly (parameter fields, chains, pads, macros, `specific` block). It is more than complete for the tool's complexity, even if over-broad.

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 100% with a single `address` param, so baseline is 3; the description goes beyond the schema's one-line example by giving literal forms (tracks/2/devices/0, returns/0/devices/1, master/devices/0, nested chains) and the name selector syntax ('name:EQ Eight').

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 verb+resource is precise: 'Read a device with all its parameters...' and it enumerates the scope (parameters, chains, return chains, drum pads, macro state) so an agent can distinguish it from get_properties/list_properties. The address examples make the target 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 routes related tasks to siblings explicitly: 'Change a parameter with set_properties', 'see list_properties' for properties, and 'Device names per track are in describe_set'. It doesn't state when NOT to use get_device, but the alternative routing is clear.

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, but it does disclose what the call reports (connection status, script version, capabilities), which is the key behavioral trait here. It does not state what happens when the bridge is unreachable, whether the call blocks times out, or confirm the operation is side-effect free.

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?

A single front-loaded sentence with no filler; the action and the returned information are stated immediately and nothing is repeated from structured 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?

With no annotations and no output schema, the description sensibly takes on the return-value role by naming status, version, and capabilities. The only gap is failure/timeout semantics when the TCP bridge is down, which an agent would want to know for a diagnostic call.

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 tool takes zero parameters, so by the stated baseline this scores 4. There is nothing for the description to disambiguate beyond the empty input 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?

States specific verbs (ping, report) and the exact resource (Ableton Live Remote Script TCP bridge) plus the three things it reports: connection status, script version, capabilities. This is clearly distinguishable from siblings like get_session_info, which concerns session content rather than bridge connectivity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or when-not-to-use statement, and no alternative tool is named. However, framing it as a ping that reports connection status strongly implies its role as a preflight/connectivity check before issuing the many set_* and get_* 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?

Annotations cover the safety profile (readOnly/idempotent/non-destructive), and the description still adds substantial behavior: the default 2000 cap, the `truncated` overflow signal, deterministic sort order (start_time then pitch), and the id's stability contract tied to edit_notes. It also documents the extra return values (clip length and loop), which the annotations do not.

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?

Effectively a single dense paragraph covering fields, sorting, truncation, and all filter modes; front-loaded with the purpose and address. It is long and reads as a run-on, but nearly every clause carries information an agent needs.

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 output schema, the description must describe the return payload, and it does: every note field with types/ranges, sort order, the clip length and loop, and the truncation signal. Combined with annotations carrying the safety profile, nothing needed to call this correctly 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 coverage is 100% so the baseline is 3, but the description adds real meaning beyond it: note field ranges (velocity 1-127, probability 0-1, velocity_deviation -127..127, release_velocity 0-127), the semantics of 'notes that start in the range', and the limit default. It does not restate every filter parameter, but what it adds is substantive.

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?

States a specific verb and resource ('Read the MIDI notes of a clip') plus the exact address format and a scoping constraint ('MIDI clips only'). The verb 'Read' cleanly separates it from write_notes, edit_notes, transform_notes and generate_notes in the sibling list.

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?

Explains when to use each filter mode (range, ids, selected:true) and cross-references edit_notes for the returned note ids, giving clear operating context. It stops short of stating when not to use the tool or drawing an explicit contrast with siblings like get_properties.

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 already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real behavior beyond that: non-applicable properties land under `unavailable`, enum values are returned as names, name selectors are accepted, and ambiguous name matches raise an error listing indices.

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?

Front-loads the verb and resource list, and the long address grammar is dense but necessary for a path-addressed API. Some address examples are verbose, but each clause carries distinct information rather than filler.

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 output schema, the description does carry the burden of return behavior and does so reasonably: it explains the `unavailable` bucket, enum-name conversion, and the error path for ambiguous selectors. It stops short of describing the overall return envelope, but for a property reader whose address grammar is already exhaustively documented, coverage is nearly 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 100%, so the baseline is 3. The description goes further by explaining that `names` defaults to all readable properties, that indices are 0-based, and that a name selector like 'tracks/name:Drift' can substitute for any number — semantics the terse schema strings do not convey.

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?

States a specific verb ('Read properties') plus an explicit enumeration of the resource types it can address (Song, Track, Scene, ClipSlot, Clip, device, rack chain, drum pad, etc.), which cleanly distinguishes it from set_properties (write) and list_properties (enumerate). An agent can tell what it returns without opening the schema.

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?

Gives actionable guidance: 'Give `names` for specific properties, or omit it to read every readable property,' and routes to the sibling with 'Use list_properties to see what exists.' No explicit when-not conditions or mention of the set_properties write counterpart, so not 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?

Goes well beyond the annotations: it quantifies the granularity of undo (one step per writing call), documents the exceptions (track rename and device parameter writes consume extra steps), discloses the global scope that reaches manual user edits, and states what is returned. Annotations only supply the destructive/non-idempotent profile; the description supplies the semantics.

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 action is front-loaded in the first two words and every clause carries operational value, but the long parenthetical about track renames and parameter writes makes the middle sentence dense and slightly run-on.

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?

No output schema exists, and the description compensates by stating what is returned (names of what was undone plus whether more undo/redo is available). Combined with the granularity rules and global-scope warning, an agent has everything needed to call this 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 100% and both parameters are already described in the schema, including the 1-50, default 1 range. The description merely restates 'steps repeats it', so it adds no meaning beyond the structured fields. Baseline 3 applies.

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?

States a specific verb pair and scope: 'Undo or redo in Live.' It also frames the tool against the rest of the writing tools by explaining that each writing call is one undo step, which distinguishes it from every sibling mutation 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 warns that undo is global and reverts the user's manual edits, so 'use it deliberately' – a clear when-to-be-cautious instruction. It does not name a named alternative tool, but the caution covers the main usage decision.

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 non-destructive and read-only false; the description adds important context that launching does not change the Set's content, and explains quantized stop behavior and self-ending recordings. It does not cover error or auth conditions, but it adds meaningful behavior beyond 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?

Dense but front-loaded with the core action, then follows with address types and options. It could be better structured with lists, but every sentence earns its place for a complex domain.

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 no output schema and rich annotations, the description covers all address types, actions, applicable options, and key caveats needed to call the tool correctly. No significant gaps remain for a Session-view launcher.

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 100%, but the description adds substantial meaning: address format variants, action default, legato scope, select for scenes, quantized for stops, quantization slots, and record_length for empty slots. This materially enriches how each parameter should be understood and used.

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?

States a specific action (fire or stop) on Session view targets and enumerates the address forms, distinguishing from transport for arrangement clips. An agent can identify intent and scope without opening the schema.

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 notes arrangement clips cannot be launched and directs to transport, and explains how each address type behaves. It lacks explicit when-not guidance versus other session-action siblings like clip_action, but the context is otherwise clear.

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 already declare read-only, idempotent, non-destructive, so the safety profile is covered; the description adds substantive behavior beyond that by disclosing the returned shape (type, writable flag, enum values, ranges) and the conditional expansion for device/sample addresses including methods.

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?

Front-loaded with purpose and result content, and only two sentences. The inline re-listing of all fourteen kinds duplicates the schema enum and is the one wasteful element.

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?

No output schema exists, so the description carries the return-value burden and does so adequately (types, writability, enum values, ranges, extra device/sample entries). It omits address string syntax and whether output is paginated, minor gaps for a read-only lister.

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 100% and the enum is repeated from the schema, but the description adds real meaning the schema lacks: that address supplies an implicit kind, and that device/sample addresses unlock device-specific properties and labeled choices.

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?

Specific verb (list) plus resource (properties) and explicit scope: the properties that get_properties/set_properties recognize. It also enumerates what the listing contains (type, writability, enum values, ranges), which distinguishes it from the sibling value-reader get_properties.

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?

Explains the two selection modes clearly ('give an address (its kind is used) or a kind') and notes that a device/sample address returns richer output. It does not explicitly say when to prefer this over get_properties, leaving that relationship inferential.

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 only declare readOnly=false, idempotent=false, destructive=false, which is thin. The description adds real behavioral context: loading selects the target in Live's window, preview is audible and needs no target, stop_preview reverses it, and the operation consumes 'One undo step'. This goes well beyond the annotations, though permission requirements and failure modes are unstated.

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?

Front-loaded with the core action and addressing, then target semantics, then the preview exception. Dense but every clause carries information; slightly heavy to parse in one block, which keeps it just under the top mark.

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 mutation tool with no output schema, it covers addressing, target behavior, the preview alternative, exclusions, undo impact, and even the return value ('addresses of the devices it added'). An agent has what it needs to call 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 coverage is 100%, so baseline is 3, but the description meaningfully enriches params the schema describes only tersely: it explains what each target address form does (track/clip slot/device) and that action=preview bypasses loading and needs no target. That adds value beyond the schema's one-line 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?

States a specific verb (load) and resource (browser item) and immediately distinguishes the two addressing modes (path vs uri) plus what each target type does. An agent can tell it apart from browse without opening either schema.

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 says when to use preview vs load ('plays an item on the preview channel without loading it'), when uri is fast vs slow, and states an exclusion: folders and categories cannot be loaded, browse into them. Nothing is left to inference.

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?

Goes well beyond the annotations (readOnly=false, idempotent=false, destructive=false) by disclosing that ramps are not undoable, cannot run inside a batch, that a new ramp on the same parameter replaces the old one, and that updates run at ~100/s inside Live. These are non-obvious operational constraints an agent must know before calling.

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?

Four dense sentences, front-loaded with the core action and duration, then constraints. Every clause carries information an agent would otherwise have to guess; none is redundant with the schema.

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 non-idempotent, non-undoable mutation with no output schema, the description covers the replacement semantics, batch exclusion, undo behavior, and units. Nothing an agent needs to invoke it correctly appears to be 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 coverage is already 100%, so the baseline is 3, but the description adds real meaning: 'from' defaults to the current value, values are in the parameter's own units, and the curve options are enumerated. The one gap is that the seconds range (0.01–3600) appears only in the schema, but that is minor.

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?

States a precise verb (sweep) on a precise resource (a device or mixer parameter address) with the target, duration, and driving rate. It also distinguishes itself from draw_automation by naming it directly, so an agent can separate the two without opening schemas.

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 scopes usage: 'For live gestures; use draw_automation for motion that belongs to a looping clip.' This names the alternative and the condition that selects it, which is exactly the routing an agent needs.

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 only cover readOnly/idempotent/destructive. The description adds substantial non-structured behavior: the feedback-loop guard, the refusal condition, the allow_feedback escape hatch, the one-undo-step reversibility, and that Live only offers valid choices. This is real behavioral context beyond the 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?

Dense but front-loaded: it opens with the core read/change statement, then parameters, then the feedback caveat. Every clause carries information, though the long parenthetical enumerations make it slightly less scannable 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?

With no output schema, the description discloses the return shape (type, channel, available_types/available_channels with their category values), covers the required and optional parameters, and documents the safety edge case. Nothing an agent needs to invoke it correctly 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 coverage is 100%, so the baseline is 3, but the description goes beyond the schema by giving concrete address examples ('tracks/N', 'returns/N', 'master', 'tracks/2/devices/1'), clarifying which parameters apply to get vs set, and noting the type/channel coupling constraint.

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?

States a specific verb pair (read/change) on a precise resource (a track's or side-chain device's input/output routing), and scopes it to 'display names the mixer shows'. An agent can distinguish this from siblings like set_properties or get_properties without opening any schema.

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 documents the address forms, the direction values, that action defaults to get, and that set requires type/channel set together in one call since channels depend on type. It routes to an alternative path for the feedback case ('monitoring is set to OFF first with set_properties current_monitoring_state'), which is exactly the when/when-not guidance the dimension asks for.

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?

Goes well beyond the annotations: atomic all-or-nothing writes with rollback, one undo step per call, strict type checking (booleans/integers/enums), interdependent properties settable in any order, name selectors with ambiguous-match errors listing indices, and returns of previous vs new values. This is exactly the extra behavioral context the annotations cannot carry.

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?

Front-loads the core action and then the contract (atomicity, returns, undo), but the long address enumeration is dense and somewhat list-like. It is appropriately sized for the tool's complexity, with only minor redundancy between the atomicity and undo-step sentences.

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 4-parameter, nested-object, no-output-schema mutation tool, the description covers target addressing, batching, guarding, validation rules, atomicity, and return values. An agent has everything needed 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 coverage is 100%, so baseline would be 3, but the schema's own parameter descriptions are terse ("Object address", "Property values"). The description compensates heavily by defining the address grammar, the `expect` guard shape, and the `items` batch form, adding real meaning over the structured fields.

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?

States a specific verb ("Set properties") and enumerates exactly which resources are writable (Song, Track, Scene, ClipSlot, Clip, Groove, cue point, device, rack chain, drum pad, device PARAMETER). This clearly separates it from read-side siblings like get_properties and list_properties without the agent opening any schema.

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?

Gives concrete usage context: use `address`+`properties` for one object or `items` for several in one call, use `expect` as a guard, and see list_properties for enum names. It does not explicitly state when NOT to use this tool (e.g. preferring batch or device_action for bulk device edits), so it stops short of full alternative routing.

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 already declare destructive=true, idempotent=false, readOnly=false, but the description adds material behavior beyond them: single-undo-step atomicity, in-place vs rebuild vs addition semantics for note ids, refusal when notes land outside MIDI range or before beat 0, dry_run preview, and unit conventions (beats, C3=60). This is exactly the extra context a mutation tool needs.

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?

Front-loaded purpose and atomicity, then addressing, transforms, selection, and semantics in a tight, dense paragraph. Minor redundancy: the full list of 20 transforms repeats the schema enum verbatim, which costs space without adding information.

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 10-param, nested-object, destructive mutation tool with no output schema, the description covers selection, addressing, units, atomicity, and failure conditions. It could say more about what dry_run returns or error reporting, but an agent has enough to call 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 coverage is 100%, so the baseline is 3; the description goes further by explaining that range params are an alternative to `ids`, that the default selection is every note, that `ids` only applies to in-place transforms, and that times are beats with C3 = 60. It adds real meaning over the schema's terse per-param lines.

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?

States a specific verb (change/transform) and resource (notes in a MIDI clip), and pins down the atomic behavior ('reads the notes, transforms them, writes the result in ONE undo step'). An agent can distinguish this from write_notes/get_notes/edit_notes by the described read-transform-write cycle and the named transform set.

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?

Gives clear context: use range params (from_time/time_span/from_pitch/pitch_span) or `ids` from get_notes for in-place transforms, with default = every note, and points to transform 'help' for per-transform params. It names one sibling (get_notes) as a source of ids but never states when to prefer edit_notes or generate_notes instead, so it stops short of explicit when-not 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?

Annotations declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the mutation/safe profile is already covered. The description adds genuine behavioral context beyond that: toggle_cue's playing-vs-stopped semantics and the arrangement-insert-marker detail ('which only the user controls'), plus capture_midi keeping recent MIDI. It also discloses the return value ('resulting transport state').

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?

It is front-loaded and dense, but the action enumeration substantially restates the enum values already present in the schema, which costs space. The routing sentences and per-action hints do earn their place, so it is functional rather than wasteful.

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 mutation tool with no output schema, the description covers the full action surface, the return value ('resulting transport state'), the one non-obvious parameter's semantics, and sibling alternatives. Remaining gaps (permissions, side effects of stop_all_clips) are minor against the annotation coverage.

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 100%, so the baseline is 3, and the description earns extra by clarifying that jump_by 'needs `amount`: beats, negative jumps back' – the negative-direction semantics are not in the schema's terse 'Beats to jump (jump_by only)' text. This is meaningful added meaning over the structured field.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource ('Transport and playhead actions') and enumerates the exact operations supported. It distinguishes itself from a few siblings by routing tempo/loop to set_properties and undo/redo to history, but the enumeration largely mirrors the enum rather than adding distinct framing.

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?

Explicit alternative routing is given: 'To change tempo or loop settings use set_properties on \'song\'. For undo/redo use the history tool.' This is clear when-to-use-elsewhere guidance. It stops short of when-not to use transport itself, but the alternatives are named concretely.

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?

Goes well beyond the annotations (readOnly=false, idempotent=false, destructive=false) by disclosing validation atomicity ('a bad note rejects the whole call'), the 5000-note cap, same-pitch overlap behavior that can shorten or replace earlier notes (lowering note_count), the returned note ids, and single-undo semantics. This is exactly the domain-specific conduct an agent needs and cannot infer from the flags.

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?

Front-loaded with the core action and scope, and every clause carries real information (ranges, atomicity, overlap, undo). It is dense as a single paragraph; splitting the per-note field list from the behavioral notes would read more cleanly, but nothing is wasted.

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 having no output schema, it describes return values (new note ids, note_count) and edge cases. For a nested-object mutation tool with 100% schema coverage and full annotations, this leaves no material gap for 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 fields carry only thin descriptions ('Notes to add'), so the description compensates richly: it documents pitch range (0-127), beats-unit start_time/duration with duration>0, and defaults for velocity (100), probability (1), velocity_deviation (0), and release_velocity (64). This adds substantial meaning beyond the structured fields.

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?

States a specific verb+resource ('Add MIDI notes to a clip') and immediately clarifies scope ('additive: existing notes stay'). It explicitly distinguishes itself from the sibling 'edit_notes', so an agent can route correctly without opening a schema.

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?

Gives an explicit alternative and the condition that selects it: 'To replace or change existing notes use edit_notes.' The additive semantics are stated up front ('existing notes stay'), removing the main ambiguity about when this tool applies.

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