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

Annotations already mark the tool as read-only, idempotent, and non-destructive; the description adds materially useful behavior beyond that: the file is not opened in Live, automation exists in two separate layers, and those layers are never added together. The corpus stats reinforce a subtle reporting behavior that could otherwise cause misinterpretation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description front-loads the core purpose and return shape before a focused note. The note is somewhat long with corpus statistics, but it earns its place by explaining the automation-layer split, a non-obvious behavioral detail. It is structured and readable, though slightly verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists and the annotations cover safety/idempotency, the description covers the key remaining context: disk-based read scope, relationship to the live connection, automation layer separation, and cost implications of with_notes. An agent has enough context to select and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides 100% parameter coverage with detailed descriptions, so the baseline is 3. The description adds only light context beyond the schema, such as with_notes being the expensive part and locate returning als_write-ready arguments, but it does not meaningfully exceed the schema's already thorough parameter documentation.

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 operation ('Read a saved Ableton project (.als) or rack (.adg) from disk') and names the returned content (metadata, track list, devices, automation structure). It also distinguishes itself from live-session/LOM siblings by framing itself as Channel B, a peer connection that reads files the LOM cannot.

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

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

The description explicitly positions the tool versus the LOM: it is 'a peer of the live connection rather than a fallback' and answers two questions the LOM never will — reading someone else's project and locating envelope breakpoints. This gives clear selection guidance for when this file-based read is appropriate instead of live-session 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?

The description goes well beyond the destructiveHint annotation by disclosing the backup-and-restore behavior, the confirm=False dry-run mechanism, the risk of Live overwriting edits, and detailed operational side effects such as fill-in-place behavior for configure and expression-match refusal for attribute. This is substantial behavioral context that an agent would otherwise have no way to infer.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well structured, with the core statement and safety requirement front-loaded, followed by returns and operation-specific notes. Most content earns its place due to the tool's complexity, though the corpus statistics about sidechain usage are arguably secondary and could be trimmed without losing essential guidance.

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 14-parameter, four-operation mutation tool with no openWorldHint and a destructive annotation, the description covers the critical context: when to edit, what gets changed, how to verify, how to avoid data loss, and how each parameter interacts with each operation. Combined with the rich schema and an output schema, nothing essential is left unexplained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the schema coverage is 100%, the description adds significant meaning beyond the field definitions: it maps each operation to its relevant argument subset, explains confirm=True/False as a check-and-apply flow, and clarifies subtle semantics like index counting expression matches rather than project tracks. This materially helps an agent choose and populate parameters correctly.

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

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

The description opens with a specific verb and resource—'Edit a saved .als project file on disk'—and clarifies the scope by naming the sibling tools it is not, such as lom_set, set_parameter, and set_mix. It also distinguishes operations within the tool (sidechain, configure, attribute, restore), making its purpose immediately intelligible.

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

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

It explicitly states when not to use the tool: the target file must not be the one Live currently holds, and warns about Live overwriting edits. It names the alternative tools to use for the set open in Live and references als_read for building expressions, giving an agent clear routing guidance without ambiguity.

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, but the description adds far more: device dependency, monotonic peak behavior, placement effects, master fader dependency, and transport-state caveats including in_transition and tracks_sounding. It also discloses failure modes like device_not_found and transport null. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well structured: a one-line summary, a compact bullet list, then short paragraphs for device placement, reset procedure, and transport state. It is long but dense and mostly earns its length; a small deduction because the transport-state detail could be considered redundant if the output schema already documents those 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?

For a tool with this complexity, the description covers prerequisites, failure behavior, parameter interactions, placement constraints, reset workflow, and output interpretation. Combined with the annotations and output schema, it gives an agent everything needed to invoke the tool correctly and interpret the reading accurately.

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%, and each parameter already has rich semantic documentation. The prose adds workflow guidance like 'call with reset=true and no accumulate', but it does not materially expand parameter meaning beyond what the input schema already provides, which matches the high-coverage baseline of 3.

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

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

The description opens with a specific verb and object ('Measure the audio itself') and immediately enumerates the exact measurements: loudness, true peak, stereo phase, and band balance. This clearly differentiates it from sibling tools like get_session, describe, or get_track, which do not claim audio-signal measurement.

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 operational context: it requires the LiveMaestro Analyzer device, reports device_not_found otherwise, must be placed last in the chain, and needs a reset-then-measure cycle for peak figures. It does not explicitly name alternative sibling tools or say when not to use it, so it stops short of a 5.

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

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

Annotations are minimal (readOnlyHint=false, idempotentHint=false, destructiveHint=false), but the description goes well beyond them. It clarifies non-destructive copy behavior, explains that repeated calls add duplicates (non-idempotent), details the return structure and how to detect placement failures, and notes that long lists are chunked. It even warns about the risk of re-sending partially-successful lists. This is rich 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?

The description is structured logically: purpose, modes, copy semantics, return details, and practical notes. It is comprehensive without redundancy; every sentence adds information. Front-loading the core purpose and modes ensures agents quickly grasp the tool's function, while the later notes address edge cases. It is long but efficient for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (two modes, 5 parameters, output schema present), the description covers return values, usage patterns, and common pitfalls. It explains how to verify results, warns about retry behavior, and integrates with surrounding tools (create_clip, write_automation). The presence of an output schema reduces the need to describe return fields, and the description still adds operational context. 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%, so the baseline is 3. The description adds value by explaining the two modes and how parameters interact (e.g., to_track omitted for source track, MIDI needs MIDI destination, placements list omits single-placement parameters). It also clarifies the meaning of at_beat with fractional beats and the verification logic. This goes beyond the schema, justifying a 4.

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

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

The description opens with a precise action: 'Copy Session clips onto the Arrangement timeline at beat positions.' It then distinguishes two operational modes (single vs. batch) and explicitly states it is a copy, not a move, making the tool's role unambiguous. It also connects to related workflows (write_automation, create_clip) without confusing it with siblings.

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

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

It explicitly states when to use this tool: 'This is how a Session idea becomes an arrangement, and how clip automation... reaches the Arrangement timeline.' It also gives guidance on building the source clip with create_clip and write_clip_notes, and how to verify placement with set_arrangement_time and play. It warns against retries and explains the difference between single and list calls, providing clear when/why 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 destructiveHint=true, but the description adds essential nuance: confirm=True actually deletes, confirm=False is a dry-run report. It discloses the fallback behavior (parameter returns to outside value, not first breakpoint), sampling limitations, and the all_envelopes report limitation. This goes far beyond the annotation 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?

The description is lengthy but every section serves a purpose. It is front-loaded with the primary action and structured with Returns and Note sections for clarity. Slightly more verbose than necessary, but the density of critical caveats justifies the length.

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 destructive tool with 6 parameters and an output schema, the description covers purpose, usage, behavior, parameter interactions, alternatives, and error handling (refusing Arrangement paths). Nothing an agent needs to call 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%, but the description enriches parameter meaning: confirm's dry-run vs. actual behavior, the mutual exclusivity of parameter and all_envelopes (neither is refused), and how to resolve parameter names via lom_get. It adds context the schema alone lacks.

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

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

The description opens with a precise verb+resource: 'Delete automation envelopes on a Session clip.' It immediately distinguishes from Arrangement clips and names sibling tools (write_automation, read_automation) for alternatives. An agent can confidently select this tool over its siblings without ambiguity.

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 guidance is given: use write_automation with clear_first=True to change a curve, use read_automation to preserve shape, and use lom_get to inspect envelope parameters. It also clarifies the Session-only scope and the confirm requirement. No inference is needed.

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

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

With annotations all set to false, the description carries the behavioral burden and delivers: occupied slots refuse rather than overwrite, the clip is empty on arrival, and Live's default looping behavior is disclosed. This goes beyond the schema and prevents surprise side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is organized into short purpose, return, and note sections, with no filler. Each sentence carries operational information and is front-loaded with the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

It covers prerequisites (MIDI track), creation behavior, conflict handling, follow-up actions, and the default loop side effect, plus the return shape. Nothing an agent needs to call 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?

The schema already documents all four parameters at 100% coverage, so the baseline is 3. The description adds that track must be a MIDI track and connects length_beats to the read-back loop length, enriching parameter meaning beyond the schema.

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

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

States the exact operation: create an empty MIDI clip of a given length in a Session slot. The description also differentiates from the audio-slot counterpart by naming lom_call/create_audio_clip, so an agent can distinguish it from siblings.

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

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

Explicitly says when not to use it (audio slots) and names the alternative call. It also provides the workflow chain: fill with write_clip_notes, arrange to timeline, and delete_clip before replacing an occupied slot.

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

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

Beyond the annotations (which only indicate non-read-only, non-idempotent, etc.), the description discloses the important side effect of index shifting and the fact that previously held track indices become invalid. It also clarifies that no instrument is added and that return tracks are appended and cannot be named/positioned. This is rich, honest 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?

The description is concise yet substantive. The one-line summary is followed by a Return section and a Note section, both front-loaded with the most operationally important warnings. Every sentence adds necessary information; there is no filler or repetition of schema details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, the 100% schema coverage, and the presence of an output schema, the description is complete. It explains the return dictionary contents, the critical index-shifting behavior, and the necessary follow-up steps. An agent has everything needed to invoke and interpret the result 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 adds value beyond the schema by clarifying the semantic implications of index values ('Append with -1... only value that leaves existing track indices alone'), reinforcing that the resolved index from the response should be used, and noting the return-track limitation of name/index. This surpasses baseline without fully re-explaining each 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?

The description opens with a specific verb and resource: 'Insert a MIDI, audio, or return track and return its resolved index.' It names the three track kinds and the tool's key output, making it easy to distinguish from sibling tools like create_clip or delete_track. The core purpose is unambiguous and not a tautology.

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

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

The description explicitly explains when to append with -1 versus take a resolved index, and warns that inserting at N shifts existing indices. It also gives a clear follow-up workflow: 'Select it and call load_device for that, then create_clip for something to play,' naming specific alternatives and sequencing. This is strong guidance for an agent deciding how to use the tool.

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

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

Annotations already include destructiveHint=true and readOnlyHint=false, but the description goes well beyond them: it states that slot indices do not shift, that confirm=False only reports without changing anything, and that clips copied into the Arrangement are independent and survive. This reveals side effects and safety behavior that annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear headings (Requires, Returns, Note), front-loads the core action, and every sentence earns its place by conveying either a safety requirement, an edge case, or an alternative. Despite moderate length, there is no fluff, and the organization makes scanning easy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the full calling context: intended effect, safety mechanism (confirm=True), return values, side effects on slot indices, relationship to write_clip_notes, and behavior of Arrangement copies. An agent has everything needed to invoke the tool correctly and safely, especially with an output schema also present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all four parameters thoroughly. The description does not add significant parameter-level detail beyond what the schema provides; it mostly restates the confirm behavior and path/track/slot alternatives already present in the schema. Baseline 3 is appropriate.

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: 'Delete the clip in a Session slot, its notes and envelopes with it.' This distinguishes the tool from siblings like delete_track, create_clip, and write_clip_notes. It names what is removed (clip, notes, envelopes) and where (Session slot), leaving no ambiguity.

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

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

The description explicitly tells when to prefer an alternative: 'Emptying a clip is not the same as deleting it: write_clip_notes with an empty list and mode='replace' leaves the clip in place... Prefer that where the slot should stay filled.' It also warns that an Arrangement copy survives deletion, helping an agent choose correctly. The confirm=True requirement is clearly stated as a precondition for actual removal.

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, but the description adds far more: the confirm=True/False safety gate with a no-op preview mode, the index-shifting side effect that makes repeated deletes land on different devices, and the rationale for why the track name appears in reports (device names are not unique across tracks). It also clarifies the return shape ('Dictionary reporting deletion status or pending loss report').

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long (~220 words) but front-loaded with the core action and confirm semantics, then organized into Returns and a structured Note with distinct points. Every section addresses a real failure mode, but the Returns line is mildly redundant with the confirm paragraph and the track-naming rationale could be tightened. Slightly verbose, never 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 destructive, non-idempotent mutation tool with 4 parameters, this is complete: it covers the danger gate (confirm), post-call hazard (index shift) and its mitigation, equivalent alternatives, cross-tool addressing consistency (get_devices), and a parameter edge case (master ignores track). The output schema exists, so return details need no further elaboration.

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 adds genuine behavioral nuance beyond the schema: that 'track' is not read at all when kind is master, that kind addresses return/main chains the same way get_devices does, and how confirm=False frames the report as a look-before-committing preview. This exceeds the baseline.

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

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

The opening line names a specific verb ('Delete'), a precise resource ('one device from a track chain'), and the scope of the effect ('its settings with it'). It unambiguously distinguishes this from sibling deletion tools like delete_track and delete_clip, and from non-destructive neighbors like load_device.

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

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

The description explicitly rules out neighboring intentions: reordering a chain should use song.move_device via lom_call, and swapping an instrument should use load_device because 'Deleting first only loses the settings earlier.' It also instructs the agent to re-read the chain with get_devices between deletes—concrete operational guidance for correct sequencing.

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

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

The description adds substantial behavioral context beyond the annotations: the confirm=True requirement, what exactly gets destroyed, the confirm=False preview behavior, and the side effect of renumbering later track indices. It also warns that previously read indices become invalid and advises re-reading via get_session. This aligns with and enriches the destructiveHint annotation without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded: the core purpose and confirm requirement come first, followed by scope, preview behavior, side effects, and alternatives. Each section earns its place, and the use of Returns/Note keeps the content organized without bloat.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists, return values are adequately covered. The description covers invocation requirements, destructive scope, preview behavior, re-numbering side effects, operational guidance for multi-deletion, and alternative tools. There are no significant gaps for an agent to call this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already covers 100% of the parameters, so the baseline is 3. The description adds meaningful detail by explaining the confirm parameter's role as a safety gate: 'True carries the removal out. False changes nothing and returns a report of what the call would remove.' It also clarifies the consequence of the track index parameter by explaining the shift in indices after deletion.

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 verb and resource ('Delete a track with everything on it') and clarifies the full scope: devices, Session clips, and Arrangement clips are all removed. It distinguishes itself from sibling tools by naming delete_clip and delete_device as narrower alternatives.

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

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

The description explicitly explains when to use this tool versus alternatives: 'For something narrower, delete_clip empties one slot and delete_device takes one device out of the chain, neither of which renumbers anything.' It also provides concrete guidance on using confirm=False to preview before committing and deleting from highest index downwards when removing multiple tracks.

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 mark the tool as read-only, idempotent, and non-destructive, and the description adds significant behavioral nuance beyond that: the dynamic runtime surface, the parameter counting failure in Live Vector, the fallback probing behavior, and the fact that methods are never callable through a path. This gives the agent realistic expectations about edge cases.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is longer than typical but well structured into purpose, return summary, usage note, and parameter behavior. Each paragraph earns its place by explaining critical distinctions and fallback behavior. Slightly dense, but the detail is justified for a runtime-introspection tool with surprising edge cases.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, the output schema, and 100% schema parameter coverage, the description is complete. It covers what the tool returns, when to use it over its main sibling, what edge cases exist, and how to continue the workflow with lom_call and set_parameter. Nothing essential 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. The description adds meaningful value by explaining the behavioral difference of with_parameters, its role in diagnosing unconfigured plug-ins, and the unmeasured cost of deep depth descents. This is more than the schema alone provides, though the path parameter gains little beyond its already thorough schema description.

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

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

The description opens with a specific verb and resource: 'Introspect any Live object: class, properties, children, and methods.' It clearly identifies the tool's purpose and differentiates it from its sibling lom_describe by stating when to prefer each, so an agent can distinguish them without opening their 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?

The description explicitly directs usage: 'Prefer this over lom_describe for a device, and prefer lom_describe for anything else.' It also routes follow-up actions, telling the agent to invoke methods through lom_call and to set device parameters via set_parameter, which goes beyond vague context into concrete decision-making.

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=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds valuable context beyond those: the lookup costs about 1.5k tokens, 'does not touch Live,' and 'nothing here proves anything about the set that is open.' These are behavioral disclosures—cost and side-effect boundary—that the annotations do not provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the purpose and uses structured Returns/Note sections, but it runs long (~250 words). The device_parameter paragraph's enumeration ('filter cutoff, resonance, attack, threshold and everything else behind a front panel') is illustrative but padded, and the route details could be tightened without losing meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with complex multi-route semantics, the description covers the four routes, the writes field, the intent_tool nuance, the unmatched diagnostics, cost, and the no-Live-access caveat. An output schema exists, so structural return details are covered elsewhere; the description supplies the semantic layer an agent needs. Minor gaps remain around explicit alternative selection, but overall it is complete for its complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds some indirect meaning—e.g., the 'writes' route and 'read-only parameter object' discussion illuminate the access parameter's 'set' filtering behavior—but it does not add per-parameter semantics beyond what the schema already states for area, limit, query, and access.

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

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

The opening line states a specific verb and resource: find the mechanism serving an intent plus the catalog rows when rows serve it. It is clearly distinguishable from siblings like describe (describes an object), find_sound (sound matching), and set_parameter (direct write), because this is a lookup/routing tool, and the four-route note further sharpens the identity.

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 guidance is mostly implied: the description frames the tool as a ~1.5k-token alternative to reading the whole catalog, and the route explanations guide the next call ('the next call to make when rows are not the answer'). However, it never explicitly names sibling alternatives or states when-not-to-use conditions, so an agent must infer when this beats describe or lom_describe.

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=true and idempotentHint=true, and the description adds substantial behavioral detail beyond that: it notes nothing is listened to, ranking is based on names and categories, status is coverage not fit, performance costs (each word blocks main thread), and interpretation of 'considered' and word lists. This is far beyond the annotations and helps the agent understand edge cases and limitations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is excessively long, over 300 words, with detailed performance measurements and specific examples (e.g., 'rhodes' and 'moog'). While structured with paragraphs, it is not concise and would burden an agent parsing it. Key information is buried among many details, and the length is disproportionate to the tool's complexity.

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 the verbosity, the description is fully complete for an agent to use the tool correctly. It explains the return dictionary structure, the meaning of status and considered, how to load results via load_device, and even warns about silent replacement of instruments. Given the output schema exists, the description effectively covers all necessary behavioral and interpretive context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all parameters are already documented. The description adds valuable context: it explains that intent is split into words and searched separately, and that root selection defaults based on word type. It also clarifies that the ranking scores all intent words even if unsearched. This goes beyond the schema, justifying a score above the baseline 3.

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

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

The description clearly states the tool's purpose: finding instruments or presets by sound description, with a specific verb and resource. It distinguishes itself from generic search by explaining it splits the intent into words and searches each, which differentiates it from siblings like match_sound without naming them explicitly.

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

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

The description provides no guidance on when to use this tool versus alternatives such as match_sound or find_path. It explains how to interpret results and mentions load_device for loading, but does not state when not to use this tool or what distinguishes it from similar search tools. The usage context is implied by the purpose but not explicit about exclusions.

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

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

Annotations are minimal (all false), so the description carries the full burden and does so richly. It discloses the asynchronous fire-and-not-wait behavior, Live's quantisation race with a concrete measured example, the meaning of certain=false and candidate beats, and that is_playing=false immediately after is expected behavior rather than failure. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded and the Returns section is compact. The Note section is lengthy but each part earns its place by explaining real behavioral pitfalls. The measured example adds credibility and concrete context, though it is slightly more detailed than strictly necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity—quantisation timing, race conditions, ambiguous landing beats, and async behavior—the description is exceptionally complete. It covers what happens before, during, and after the call, how to interpret ambiguous results, and why immediate is_playing=false is not an error. With an output schema present, return-value details are not 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. The description clarifies the 'confirm' behavior indirectly through 'This fires and does not wait,' but it does not explicitly map behavior to the confirm parameter or add extra meaning beyond the schema's own description of the two parameters. It neither hurts nor significantly improves schema 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?

The description opens with a specific verb and resource: 'Fire a scene' and adds the distinguishing reporting behavior ('report which beat the launch actually lands on'). This clearly separates it from generic transport tools like play and stop, and the Returns section reinforces the unique output.

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

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

The description gives clear operational context: it explains the race condition, what measure the result is reliable to, and how to interpret is_playing immediately after firing. It does not explicitly name alternatives or say when not to use it, but the context is sufficient for an agent to decide when this tool's reporting adds value.

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?

Even with strong annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds substantial behavioral context: the return contract with has_clip for empty slots, the unit system (seconds vs beats) with measured examples, and the critical warning that toggling warping rescales markers and does not undo. These are non-obvious, empirically verified traits that no annotation could convey. There is no contradiction with 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 description is front-loaded with the purpose and then organizes key behavioral warnings under bold headings and clear paragraphs. It is long, containing measured values and dates (e.g., 'Measured 2026-09-19', exact numeric factors), which are useful but arguably more detailed than necessary for tool selection and correct invocation. Every sentence does contribute to the behavioral picture, so it earns a '4' rather than a '3', but it is not as lean as it could be.

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 that this tool has an output schema, annotations, and 100% parameter schema coverage, the description still goes beyond the minimum: it covers the has_clip return contract, unit semantics, the marker-rescaling data hazard, and verification status. An agent has everything needed to call the tool correctly and anticipate unusual behavior, even before examining the output schema. Nothing essential 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. The description does not add meaningful parameter-level detail beyond what the schema already provides; it references the 'generic path' but does not explain path/slot/track relationships beyond the schema's own descriptions. The description focuses on return behavior, not parameter semantics, so it neither compensates nor detracts from the schema. This meets the minimum viable standard.

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 pair: 'Read one Session clip's properties' and enumerates the exact fields (length, loop, warp, pitch, markers, flags). It also explicitly distinguishes itself from read_clip_notes and read_automation, which directly addresses sibling differentiation. An agent can confidently select this tool for reading clip properties without confusing it with the read-note or automation tools.

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

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

The description gives explicit guidance on when not to use it: 'Notes and automation are not properties: use read_clip_notes and read_automation.' It also makes clear via 'Session clip' that this is for Session clips, and the schema reinforces that Arrangement paths are refused. It does not survey all possible sibling alternatives (e.g., get_track, get_session), but the primary exclusions are covered, leaving little ambiguity for the common use case.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description states it 'changes nothing', discloses edge cases (empty chain returns device_count: 0, invalid index returns index_out_of_range), and explains the configure_needed flag and parameter_count_at_least fallback. This gives an agent a reliable model of side effects and failure behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose in one sentence and then organized into Returns and Note sections. It is somewhat verbose, especially the paragraph about the configure_needed probe, but every sentence carries useful information and the structure makes it scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and 100% input schema coverage, the description still adds necessary context: edge cases, error behavior, relationships to other tools, and a Live-specific limitation. An agent has everything needed to call this tool correctly and interpret its results.

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 schema already documents both parameters and their meaning. The description adds the behavioral note about invalid track indices but does not significantly enrich the semantics of the kind or track fields beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The first sentence names the exact verb ('List'), resource ('a track's device chain'), and content ('names, class names, on/off, parameter counts'). It also distinguishes itself from siblings by pointing to describe for parameters and get_track for mixer/sends/clip slots, so an agent can tell it apart 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?

The description explicitly says when to call describe instead ('this tool counts them and does not list them') and when to call get_track ('For the mixer, sends and clip slots on the same track'). It also tells the agent to read the parameter count first and warns about the configuration edge case, giving clear operational 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 declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description goes well beyond this by revealing the 450 ms round-trip cost, the group track 'armed' null quirk, and the index-probing fallback when zero tracks are reported. These are non-obvious behavioral traits that materially affect invocation decisions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured: a one-line purpose, a short invocation-placement paragraph, a return summary, and a note consolidating the most important behavioral caveats. Every sentence adds operational value, and the most critical 'call first' guidance 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 read-only session-survey tool with an output schema and rich schema-level parameter descriptions, the description covers everything an agent needs: when to call it, why it is expensive, what it returns at a high level, how to narrow afterwards, and two important quirks (group track arm state and zero-track fallback). Nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and each parameter already has a rich description explaining its effect, defaults, and edge cases (e.g., max_scenes is a cap not a count). The tool description adds contextual linkage ('clip and device detail where asked for') but does not need to restate parameter meanings, so the baseline of 3 is appropriate.

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 names a specific verb ('Survey'), a specific resource (the running set), and enumerates the content: script handshake, song fields, tracks, clips, and devices. It also explicitly positions itself as the first call and distinguishes itself from get_track, get_clip, and get_devices, making sibling differentiation clear.

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

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

The description gives explicit when-to-use guidance: 'The call to make first' and explains why, then directs the agent to 'Take it once at the start and narrow with get_track, get_clip and get_devices afterwards rather than calling this again between edits.' It also notes when the clips parameter can be disabled for speed, giving practical selection context.

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

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

The annotations already declare readOnly, idempotent, and non-destructive, so they cover the safety profile. The description adds substantial behavioral context beyond that: volume/panning are normalized not dB, arm is conditionally read to avoid Live exceptions, and counts are measured by probing batches and may be inexact. This is exactly the kind of non-obvious behavior an agent needs to trust the result.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with a one-sentence summary, followed by scoping guidance, then a structured return list, then a compact notes paragraph. Every section earns its place and is grouped logically. Despite length, the density of useful behavioral caveats makes the complexity justified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists and the annotations cover safety, the description fills all remaining gaps: return content, normalization caveats, conditional arm handling, batch-probed counts, and when to prefer sibling tools. An agent has everything needed to invoke get_track correctly and interpret the result without trial and error.

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 already documents both parameters fully with descriptions and enum values, so schema coverage is 100% and the baseline is 3. The description does not add much directly about the parameters themselves, but it does explain the meaning of 'track' in context and how certain values behave per track type. Since the schema carries the heavy lifting, a 3 is appropriate.

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

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

The first sentence names a specific verb ('Read'), the exact resource ('one track'), and enumerates the content: mixer state, flags, device chain, sends and clip slots. It explicitly contrasts with get_session (whole set) and get_devices (device chain only), so an agent can distinguish it from siblings 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?

The description gives explicit when-to-use guidance: 'One track in one round trip, where get_session covers the whole set' and 'Use this to read a mixer before writing it with set_mix, and get_devices when the device chain is the only thing wanted.' It also warns against using this tool on group tracks for the arm field, which is a practical usage constraint.

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 indicate destructiveHint=true and readOnlyHint=false, but the description goes far beyond that: it details side effects like arming/disarming tracks, renaming default tracks, silent replacement of instruments, crash risks with rapid loading, the meaning of success vs. actual sound output, null field semantics, and incomplete status handling. It discloses all known behavioral quirks, providing exceptional transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured: it opens with a clear purpose, then covers returns, caveats, and edge cases in a logical order. Every sentence adds value, though it could be slightly tighter. It is not overly verbose for the complexity it conveys, and the front-loaded purpose helps quick scanning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is exceptionally complete for a complex tool. It covers return values, error states, edge cases (null fields, incomplete status), workarounds (master track handling), and even measured behavioral notes against specific Live versions. With an output schema present, the description need not explain every return field, but it goes beyond that to ensure correct invocation and interpretation.

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%, so the baseline is 3. The description does not add significant new parameter semantics beyond what the schema already provides; the schema already explains uri, root, limit, query, track, confirm, and item_path in detail. The description focuses on workflow and behavioral context rather than parameter details, which is acceptable given full schema coverage.

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 verb and resource: 'Search Live's browser and load a device onto a track', and clarifies the two-step search-then-load process. It clearly distinguishes itself from siblings like get_devices by explaining it performs a load, not just inspection. The purpose is unambiguous and directly useful.

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 explicit guidance: it warns to 'check with get_devices first' before loading instruments (to see what will be discarded), advises loading one at a time to avoid crashes, and explains the search step vs. load step. It doesn't explicitly name alternative tools for different scenarios, but it provides clear context on when and how to use this tool safely.

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 all annotations set to false, the description carries the full burden of behavioral disclosure. It discloses that the batch runs synchronously on Live's main thread, is capped at 1000 operations, and is rejected upfront if larger. Critically, it explains that operations within a batch do not see recomputed state (e.g., a read after a transport jump returns the pre-jump value), and it describes the failure shape as returning clean but wrong numbers. It also notes atomic stops at the first error but undoes nothing, and that an end_marker write is refused. This is exceptionally transparent and goes far 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 description is front-loaded with the purpose and return type, then provides a detailed note. While it is quite long, the length is justified by the critical behavioral caveats (consistency, failure shape, atomic rollback). However, the performance measurements are extraneous for an AI agent's decision-making and could be trimmed without losing essential information. The structure is logical and the key points are early, so it earns a 4 rather than a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, the description is remarkably complete. It covers purpose, usage, behavioral caveats, and even includes failure shapes and advice on when not to use it. Since an output schema is present (as indicated by context), the description does not need to explain return values in detail. It provides everything an agent needs to correctly select and invoke this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage for all parameters, including ops (with its nested properties) and atomic. The description does not add extra meaning beyond the schema; it repeats the 1000-op cap (already in the schema) and the atomic behavior (also in the schema). Therefore, the baseline of 3 is appropriate—the schema does the heavy lifting, and the description adds no additional parameter-level context.

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

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

The description clearly states the tool executes multiple raw LOM operations (get, set, call) in a single round trip, using a specific verb and resource. It explicitly differentiates from dedicated siblings by naming get_session, get_track, get_devices, and set_mix and noting they batch their own reads and verify, which this tool does not. This leaves no ambiguity about what the tool does and how it differs.

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 explicit guidance on when to use this tool vs alternatives: 'Prefer a dedicated tool where one exists' and names the alternatives. It also provides specific usage warnings, such as not sampling a moving transport inside a batch and noting that atomic stops at the first error but does not roll back. This is clear, actionable, and covers exclusions.

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

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

The description discloses a critical limitation: 'a method call has no read-back, so nothing here proves the effect' and recommends following with matching reads. It also explains the return behavior, including refused calls naming the reason and 'use_instead' pointing to a dedicated tool. The annotations are all false and are not contradicted; the description adds substantial behavioral context beyond those booleans.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and then uses labeled sections for return behavior and usage notes. Every sentence adds information: the allow list boundary, the no-read-back caveat, the follow-up-read recommendation, and the explicit alternatives. It is longer than a one-liner but earns its length for such a generic escape-hatch tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a generic fallback tool with three parameters and an output schema, the description covers what an agent needs: what it calls, how it is restricted, what the return dictionary contains, how to verify effects, and when to choose a sibling tool. The presence of an output schema means the return-value structure need not be fully repeated here. No critical operational context appears 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?

The input schema already provides 100% coverage with detailed descriptions for path, method, and args, including the reference-dict format for Live objects. The description itself adds contextual examples like 'song.move_device' but does not attempt to redefine the parameters. A baseline score of 3 is appropriate because the schema carries the parameter-semantics load.

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 immediately states the verb and resource: 'Invoke an allowlisted method on a Live object.' It then clarifies that this is the 'escape hatch' for calls with no dedicated tool, using 'song.move_device' as a concrete example. This clearly distinguishes it from the many sibling tools that cover specific operations.

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

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

The description explicitly says to prefer a dedicated tool wherever one exists, names several such tools, and directs property access to lom_get/lom_set and multiple calls to lom_batch. It also instructs the agent to follow up with a matching read because method calls have no read-back. This is explicit, actionable routing 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 mark this as read-only and idempotent. The description adds important behavior beyond that: it reports child collections as counts, warns that device parameters may be misreported as zero due to Live Vector len() issues, clarifies that describe falls back to index probing, and states that listed methods are names, not calls. This is meaningful, non-obvious 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?

The description is organized with clear sections, front-loads the core purpose, and uses the note only for a genuinely important caveat. There is some redundancy between the opening sentence and the 'Returns' paragraph, both covering class, properties, children, and methods, but overall the structure is deliberate and every major block 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?

Given the output schema exists, the description does not need to explain return values in full, but it still covers the key behavioral details: what the dictionary contains, how methods are represented, when to prefer another tool, and an important failure mode. For this tool's complexity, 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%, so the baseline is 3. The description adds value beyond the schema by warning that raising depth multiplies the work and that the cost is unmeasured, which is not present in the parameter schema. It also reinforces the path semantics with examples already in the schema, but the depth warning is a genuine extra.

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

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

The description opens with a specific verb and resource: 'Reflect on any LOM object: class, properties, children, callable methods.' It clearly distinguishes itself from related tools by explaining that this is raw reflection rather than reading or writing property values, and explicitly names lom_get, lom_set, and lom_call for those actions.

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 explicit guidance on when to use this tool: to find property names the catalog does not cover, with follow-up reads via lom_get and writes via lom_set. It also gives a strong exclusion: for devices, prefer 'describe' with with_parameters=True, and explains why. This is clear routing among siblings.

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, so the safety profile is covered. The description adds valuable behavioral context about Live's internal integer representation, the dual lookup direction, and the conditional return shape based on the type_name parameter.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized with a clear opening, a Returns section, and a Note that justifies usage. Every sentence contributes meaning, and the front-loaded verb-resource sentence immediately conveys the tool's core function without waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with one optional parameter and an output schema. The description covers why the tool exists, when to use it, how to interpret the result, and which sibling handles the adjacent concern. Nothing essential is missing 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?

Schema description coverage is 100%, and the schema already explains the dotted name format, the empty-string behavior, and the default value. The description reinforces this and echoes the empty-case behavior in the Returns section, but adds little beyond the schema.

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

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

The description clearly states a specific verb and resource: 'Look up the integer behind a named Live enum member.' It also explains the bidirectional nature and distinguishes itself from lom_describe, making the tool's purpose unmistakable.

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

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

The description explicitly tells the agent when to call this tool ('Call this before writing an enum-valued property through lom_set or set_parameter') and contrasts it with lom_describe. This provides clear context and excludes the common alternative.

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

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

Beyond the readOnly/idempotent/destructive annotations, the description details error semantics (non-song/app/song.view roots refused before contacting Live, Live-rejected paths return ok:false with Live's code), sentinel handling via the 'means' field, and the shape of the return dictionary. This 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?

The description is compact and well-organized: purpose, return summary, then a note on edge cases and usage. Each paragraph earns its place with no fluff, and the core purpose 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 one-param read tool with strong annotations and a schema, the description covers the practical invocation concerns: path syntax constraints, error responses, catalog meaning, and fallback positioning relative to sibling getters. Nothing essential 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?

The schema covers the path parameter fully (dotted LOM path, allowed roots, integer subscripts, examples), so the high coverage baseline applies. The description adds context about path-root validation and single-property reading but does not introduce new parameter-level requirements.

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 lead sentence is a precise verb+resource statement: 'Read one property value by LOM path' and immediately differentiates the tool as 'the single-property read behind every getter here, for the field no getter exposes.' This clearly distinguishes lom_get from sibling getters.

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

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

The description explicitly directs agents to prefer a dedicated getter: 'Reach for a getter first where one exists,' and frames lom_get as the fallback for fields no getter exposes. It names get_session as an example, giving concrete routing 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?

The description discloses extensive behavioral nuances far beyond the annotations (readOnlyHint false, idempotentHint true, etc.). It details return semantics, clamping, quantization, asynchronous application (read_back: not_observed), silent success for unknown properties, and the distinction between clamped and quantized. It also warns that Live objects cannot travel as plain values and specifies how to pass them via __path__. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence carries essential behavioral or usage information. It is structured with a concise purpose statement, a 'Returns:' section, and a 'Note:' section that systematically covers edge cases. The most important distinguishing information (write vs. alternatives) is front-loaded. The length is justified by the complexity of the tool and the need to prevent common mistakes.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of LOM and the presence of an output schema, the description is remarkably complete. It explains return fields, handles out-of-range and quantized values, discusses asynchronous behavior, notes that unknown properties are ignored, and covers special cases for Live object references. Nothing an agent needs to call the tool 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?

Although the schema already describes both parameters with 100% coverage, the description adds crucial semantic details: it explains the trailing .value in paths (e.g., 'a mixer control is a DeviceParameter object and the number lives one level inside it') and specifies the exact structure for Live object values (reference dict with '__path__'). This goes well beyond the schema's generic descriptions, giving the agent the precise syntax needed for correct invocation.

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

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

The description opens with a clear, specific statement: 'Write a property value by LOM path and return verification read-back.' It then explicitly contrasts with sibling tools: 'The generic write, and the unvalidated one: set_parameter, set_mix and set_tempo check the catalog first. lom_call takes a method, lom_batch several writes in one round trip.' This precisely distinguishes lom_set from its siblings, making its purpose unambiguous.

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

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

The description gives explicit when-to-use guidance by naming alternatives and the conditions that select them. It states that set_parameter, set_mix, and set_tempo are the unvalidated variants, while lom_set is the generic write that checks the catalog. It also advises against assigning collections ('A collection like song.tracks cannot be assigned') and explains when to use __path__ references for Live objects. These are actionable usage rules, not vague hints.

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

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

The description goes far beyond the annotations by disclosing the score's meaning (lower is closer, not comparable across files), the weakness of ordering within one answer, the use of Ableton's preview render, and error cases like nothing_to_match and no_index. It also explains the load_with block and the name-not-path caveat – all behavioral traits not captured by readOnlyHint or idempotentHint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured: a one-sentence summary, then Returns, then a Note with measurement caveats and usage warnings. Every sentence carries substantive information; there's no fluff. The length is justified by the tool's complexity, though it could be tightened without losing meaning.

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 eight parameters and an output schema, this description covers everything an agent needs: return format, error cases, how to load the result, and extensive behavioral caveats backed by concrete measurements. It even explains how to safely confirm the selection ('Check before confirming'). No critical context 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?

The input schema already covers all eight parameters (100% coverage), so the baseline is 3. The description adds value by explicitly urging users to set the instrument parameter ('worth far more than any ranking') and by describing how window affects matching (loudest vs whole, with measurement context). This enriches the agent's understanding of parameter choices beyond the schema.

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

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

The description opens with 'Rank the library by how close each item sounds to a piece of audio you have.' This is a specific verb (rank) and resource (library) with a clear input, clearly distinguishing it from siblings like find_sound or analyze_audio. The purpose is unmistakable and specific.

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 note section gives clear guidance: set the instrument family when known, warns the result is 'a shortlist, not a ranking,' and explains matching behavior (timbral, level-removed, pitch-agnostic) and how to load the selected item. It doesn't explicitly name alternative tools, but the context is rich enough for an agent to know when to use this tool.

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

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

Annotations only provide high-level flags (not read-only, idempotent, not destructive). The description adds substantial behavioral context beyond those flags: the read-back proves transport running rather than audibility, the transport is left running, and Session clip playback can make a track ignore the Arrangement until Back to Arrangement is triggered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is longer than minimal, but it is front-loaded with the core purpose and then structured into useful blocks: return value, caveats, transport state, and Session/Arrangement behavior. Each block earns its place, though the last paragraph is detailed enough that a slightly tighter version would be possible.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's side effects and edge cases, the description is complete: it states the return dictionary, the non-audibility caveat, the leave-transport-as-found policy, the Session clip interaction, and the asynchronous back_to_arranger behavior. The full input schema and output schema cover the remaining structured details.

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%, with both from_beat and continue_playing already explained in detail, including the interaction where from_beat overrides continue_playing. The tool description does not need to add parameter semantics, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Start transport playback and read back the is_playing status.' It also names sibling tools stop and set_arrangement_time, so an agent can distinguish play from related transport operations without opening other definitions.

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

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

The description explicitly states when to use alternatives: 'Use stop to halt, and set_arrangement_time to move the playhead without starting.' It also clarifies that playback may be silent, which sets expectations for whether calling this tool is useful in a given context.

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

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

Annotations provide readOnlyHint=false and destructiveHint=false, but the description goes further by disclosing that quantizing modifies notes in place and is not undoable, and that it writes back using mode='replace' and verifies the result. It also explains the strength scaling and quantize_ends interaction, which is valuable behavioral context beyond the structured fields. No contradiction with annotations is present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized: the core purpose is front-loaded, then parameter interactions, then behavioral warnings, then alternatives. Every sentence earns its place; no fluff or repetition of schema details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutating tool with six parameters, the description covers the return format (dictionary with write result, note count, distance), handles edge cases (refusal of arrangement clip paths), and provides usage guidance. Even though an output schema exists, the description's return summary is helpful and not redundant.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description adds significant meaning: it explains strength as a displacement scale from 0.0 to 1.0 with a practical suggestion (0.5 for groove), and clarifies that quantize_ends=True snaps note ends while False preserves articulation. This goes beyond the schema's brief parameter definitions.

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 verb (quantize) and resource (MIDI clip note positions and lengths) against a beat grid. It clearly distinguishes itself from sibling tools by naming transpose_clip for pitch and write_clip_notes for custom off-grid notes, so an agent can tell them 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?

It explicitly says when to use this tool versus alternatives: 'To shift pitch instead of timing, use transpose_clip. To write custom or micro-timed notes off-grid, use write_clip_notes.' It also advises reading notes first with read_clip_notes if original timing might be needed later, covering both selection and prerequisite context.

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

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

The description goes beyond the readOnly/idempotent annotations by explaining that the result is a sampling at points positions rather than breakpoints, and by clarifying the semantic distinction between 'nothing is automated' and 'an envelope holding the parameter's current value.' It also discloses the return shape: sampled values, beat range, value range, and existence flags. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action and then uses clearly labeled 'Returns' and 'Note' sections for supplementary detail. Every sentence carries information: the sampling distinction, the return dictionary, the Session-vs-Arrangement caveat, and the alternative tools. It is longer than the simplest descriptions, but it is appropriately sized for a tool with 7 parameters and meaningful edge cases.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is complete for the tool's complexity: it explains what the tool returns, how it differs from related tools, the Session-clip requirement, and the subtle false-flag meaning. The input schema fully documents parameters, and an output schema exists, so the prose fills the remaining behavioral and contextual gaps. Nothing an agent needs to invoke 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 tool-level meaning that clarifies parameters: 'evaluating it at points positions' explains the role of the points parameter, and 'sampling of the envelope rather than the breakpoints' frames what all parameters collectively produce. It doesn't re-document each parameter, but it adds useful conceptual context beyond the schema.

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

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

The description opens with a specific verb and resource: 'Sample a clip envelope into a list of values and report what it found.' It immediately distinguishes itself from related tools by stating that it returns a sampling of the envelope, not the breakpoints, which differentiates it from als_read. This makes the tool's purpose unmistakable.

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

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

The description explicitly says when to use this tool versus alternatives: 'als_read is the way to see breakpoints in a saved project instead,' and 'Use write_automation to lay a curve down and clear_automation to remove one.' It also provides a key contextual constraint: automation lives in Session clips, so Arrangement clips have none to read. This is model-level guidance that leaves little 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses several critical behaviors: times are clip-local beats, muted notes are included with a mute:true flag, notes are sorted by time then pitch (and explains why Live's pitch-first order is problematic), and the effect of count_only on validation. It also explains the 57k character limitation and how count_only solves it. This is rich behavioral context that annotations alone cannot provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-organized: a one-line purpose, a Returns section, then a Note section for caveats. It is dense with useful information and each sentence earns its place. The structure is clear (purpose, returns, behavioral notes) and front-loads the main purpose. While it's not terse, the complexity of the tool (9 params, large-clip pitfalls, ordering quirks) justifies the length. Slight deduction for not being more scannable, but it's well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, the description covers all essential context: the large-clip size problem and the count_only workaround, pitch windowing for oversized reads, sorting behavior and why it matters, validation interactions, and the alternative tool for Live's ordering. An output schema exists, so return values don't need elaboration. An agent can call this tool correctly across all edge cases after reading this description. 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?

The input schema covers all 9 parameters with detailed descriptions (100% coverage), so the baseline is 3. The description adds value beyond the schema by explaining the rationale and usage context for key parameters: count_only for large clips, pitch_min/max for narrowing, and time_span semantics (length, not end beat). It doesn't re-explain each parameter but adds the 'why' and 'when' that the schema lacks. This pushes it to 4.

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

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

The description opens with a clear, specific verb-resource pair: 'Read MIDI notes of a Session clip, query a specific window, or count notes.' It immediately distinguishes three modes of operation. It also names the alternative tool (get_notes_extended via lom_call) that provides opaque handles, making it obvious this tool returns readable notes. This exceeds the minimum and clearly differentiates from siblings like write_clip_notes.

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 explicit guidance on when to use each mode: count_only for large clips that would exceed the result cap, pitch_min/max to narrow the read for large clips, and when to prefer get_notes_extended (when you need Live's native ordering or are okay with opaque handles). It also explains the interaction between count_only and check, and that a window makes check see the window not the clip. This is exemplary usage 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?

The description discloses behaviors well beyond the annotations: it states it writes song.current_song_time, that writes are bounded by song_length, the exact Live error on failure, and the stale-read behavior inside lom_batch. This gives the agent important execution expectations that annotations alone do not convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well structured: a front-loaded one-sentence summary, then an expandable note and return statement. The warnings about song_length and lom_batch are necessary behavioral context, not filler, and every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter write-and-read tool, the description covers the primary action, the boundary condition, the failure mode, the batching caveat, and the relationship to playback tools. An agent has enough information to invoke it correctly and anticipate outcomes.

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%, and the schema already defines at_beat including beat origin and fractional beat acceptance. The tool description adds little parameter-specific meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Move the Arrangement playhead to a beat and read the position back.' It clearly identifies the operation and distinguishes it from starting playback, explicitly noting that play or play with from_beat handles playback.

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 explicit guidance on when to use this tool versus alternatives: 'Use play to begin, or play with from_beat to do both in one call.' It also warns against using lom_batch for sampling a moving transport and prescribes 'One call per position', which is actionable usage advice.

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 sparse annotations, the description carries the behavioral burden and does so thoroughly. It discloses the non-idempotent toggle, the confirm=True requirement, the confirm=False preview behavior, the return dictionary contents, and the fact that locators do not move the playhead. No contradictions with annotations are present.

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 essential action and confirm requirement are front-loaded, followed by a compact explanation of the toggling behavior. The Returns and Note sections organize extra context cleanly, with no redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The definition is complete for the tool's complexity: it explains a subtle toggle behavior, states required confirmation, describes the return value, and differentiates sibling tools. Given the output schema exists, this leaves no important gap for an agent calling the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides rich descriptions for all three parameters, so the baseline is 3. The description adds beyond the schema by clarifying the toggle consequence of passing the same arguments twice and reinforcing the confirm=False workflow, which helps an agent reason about the non-idempotent parameter interactions.

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 concrete verb and resource: 'Place or remove an Arrangement cue locator.' It immediately distinguishes the tool from related siblings by explaining what it does not do—moving the playhead or marking a region—so an agent can recognize its specific scope.

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 explicit operational guidance: call with confirm=False first to preview whether the action will add or delete a locator. It also names alternatives set_arrangement_time and set_loop with the precise conditions for using them instead, which is strong usage-direction.

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?

Even though annotations already signal idempotent, non-destructive behavior, the description adds meaningful context: only supplied arguments are written, no-argument calls perform no writes, the return dictionary reports write count and before/after values, and length is a duration not an end position. These details go well beyond the structured annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections, front-loaded purpose, and no filler. The Returns and Note sections each add necessary behavioral or scoping information, and every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with three optional parameters and an output schema, the description is complete: it explains the write behavior, the read-only no-arg mode, the return shape, the meaning of length, and the boundary between Arrangement looping and Session clip looping. An agent has everything needed 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?

The input schema already covers all three parameters at 100% with clear descriptions. The tool description still adds value by explaining that length is a duration rather than an end position and by emphasizing that omitted parameters are left unchanged, reinforcing the optional-write 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?

The description opens with a specific, action-focused statement: 'Move the Arrangement loop brace, or switch looping on and off.' It clearly identifies the resource (Arrangement loop brace) and distinguishes this tool from Session clip looping by pointing to get_clip as the relevant tool for that case.

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

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

The description explicitly explains the optional-argument behavior, clarifies when not to use it ('no bearing on Session clip looping'), names the alternative (get_clip), and even documents the no-argument read mode as the cheap way to inspect the current brace. This gives an agent clear selection and invocation 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=true, and destructiveHint=false; the description adds meaningful context beyond these: master-track mute/solo 'are refused there rather than silently ignored,' 'track is not read at all when kind is master,' values are absolute rather than relative, volume/pan use a non-linear normalised scale ('0.85 is 0 dB (measured)'), and the return dictionary reports before/after values plus Live's dB display. The description is consistent with the annotations, so there is no contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose and core behavior, then returns, then normalization notes, then sibling routing. It is longer than average, but the tool genuinely has the complexity to justify it (7 parameters, normalization traps, master-track exceptions). The Note paragraph slightly overlaps the schema's volume description, though it earns its place by extending normalization context to pan and pointing at the display 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?

For a 7-parameter mutable mixer tool with an output schema and annotations present, nothing an agent needs is missing: prerequisites (get_track first), edge cases (master refusal, track ignored), exclusions (mute/solo unsupported), alternatives (set_parameter, set_tempo, write_automation), and return behavior are all covered. The output schema carries the detailed return structure.

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%, so the baseline is 3. The description adds genuine cross-parameter meaning beyond the schema: pan shares the same normalised 0.85=0 dB semantics as volume, the 'display' field in the answer is the authoritative dB reading rather than converting the normalised number, and master rejects mute/solo rather than silently ignoring them. This lifts it above the baseline.

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

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

The opening sentence states a specific verb and resource: 'Set volume, pan, sends, mute and solo on one track in a single round trip.' It is scoped precisely to the mixer of one track and is immediately distinguishable from siblings like set_parameter, set_tempo, and get_track without opening their 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?

The description explicitly tells the agent when to use this tool ('the cheap way to change several mixer controls at once'), states a prerequisite ('Read the current state with get_track first, since the values here are absolute and not relative'), and names alternatives with routing conditions: 'For a knob on a device in the chain use set_parameter, and for the tempo use set_tempo... write an envelope with write_automation.' 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?

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses critical behaviors: values are normalized rather than displayed units, the curve is nonlinear and device-specific, quantized parameters can legitimately clamp, and ambiguous names are refused. This is rich, honest behavioral context that prevents silent misconfiguration.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and return summary, then organized into a focused Note section. While lengthy, each sentence addresses a real operational pitfall (normalized units, nonlinear curves, quantization, str_for_value). It is longer than minimal but justified by the tool's subtle failure modes.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and the rich output schema, the description covers all essential operational context: value normalization, how to discover valid ranges, how to handle nonlinearity, quantization behavior, and ambiguous names. An agent has enough to call it correctly and interpret results without missing surprises.

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 adds meaningful semantics beyond the schema: it explains normalization, non-linear scaling, the meaning of the value parameter in device-specific terms, and the glob/refusal behavior of the parameter name. This goes beyond what the schema already states without 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?

The description opens with a specific verb and resource: 'Set one device parameter by index or name and verify the read-back.' This clearly distinguishes it from sibling tools like set_mix, set_tempo, and lom_set by focusing on device parameters and read-back verification. The purpose is unambiguous and immediately actionable.

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 explicit usage guidance: read min/max with describe before writing, use the device display when available, and use str_for_value to map units without trial. It stops short of naming alternatives or saying when not to use this tool, so it lacks explicit exclusions, but the context is strong and practical.

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?

Very rich behavioral disclosure: probes write nothing, nothing moves until a final single write, range is strictly bounded to avoid crashing Live, refusal occurs when a device reports no unit, and the stored value is not audibility. This far exceeds what annotations (destructiveHint=false, idempotentHint=true) convey and adds critical operational 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?

The description is long but front-loaded with a clear one-sentence purpose. Returns and Note sections are dense, not padded, and almost every sentence earns its place. Some internal references like 'catalog row return_device.str_for_value' and the measured third-party examples are slightly over-specific but still support the safety argument.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with an output schema, 6 params, and a subtle domain, this is complete. It covers failure modes (no-unit refusal, name ambiguity refusal), safety behavior (range bounds, no writes during probing), helper routing to set_parameter, and the semantics of the returned display. Nothing needed 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. The description adds real extra meaning by clarifying target is a display reading not a normalised value, giving concrete examples like -26 dB and 8000 for 8 kHz, and explaining refusal semantics when units mismatch. The v^4 * 1000 ms example makes the non-linear mapping tangible.

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

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

The opening sentence states a specific verb+resource+semantic: 'Set a device parameter by the reading it should show, not by its raw value.' This immediately distinguishes the tool from its sibling set_parameter. The Returns section and Note section continue to reinforce what the tool does and what it refuses to do, making the purpose unmistakable.

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

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

The description explicitly says when to use this tool (when aiming at display reading, when units are known) and when not to: 'Use set_parameter with a normalised value for those' VST2/no-unit devices. It also names the inverse relationship and explains why the inverse is necessary, giving clear routing between 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?

Discloses behavior well beyond the annotations: the tool writes and reads back the stored value, the set does not survive every scene launch, the exact mechanism (scene.tempo_enabled rewriting song.tempo), and that BPM is a real unit unlike normalized device parameters. The idempotentHint annotation is consistent—setting an absolute tempo is idempotent—and the description adds genuine lifecycle context. No contradiction.

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 main purpose is front-loaded in the first line, with Returns and Note sections structuring the caveats. The parameter-normalization tangent runs a bit long and includes extra set_mix detail, but every sentence carries information useful for correct invocation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with an output schema and annotations present, the description covers everything needed: global scope, return shape, the scene-launch override caveat, and cross-references to sibling tools. No material gap remains for an agent 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 bpm schema description already gives the unit and validation range, so baseline is 3. The description adds value by flagging that BPM is 'a real unit, which makes this tool the exception among the setters,' warning the agent not to send a normalized 0..1 value. This goes beyond what the schema states.

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: 'Set the global song tempo in BPM and read back the stored value.' The description immediately distinguishes scope ('One tempo governs the whole set, Session and Arrangement alike. There is no per-track tempo'), which prevents confusion with per-track setters like set_parameter or set_mix.

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

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

Provides real routing context: names the scene as the 'one other place a tempo can come from' and advises reading song.tempo back after a launch, and points to set_parameter for normalized device parameters plus describe for min/max. Lacks an explicit 'use this over X when...' framing, but the alternatives and conditions are clearly named.

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=true, openWorldHint=false, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context: the index is not committed, describes one machine, is built from Ableton preview renders, and lives under a specific path. This is valuable information that annotations do not provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear question, a usage directive, a returns summary, and a note. It is slightly longer than strictly necessary, but every section adds relevant information and the most important guidance ('Call this before match_sound') 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 zero-parameter read-only status tool with an output schema, the description is complete: it covers what the tool does, when to call it, what it returns, and important environmental caveats. An agent has everything needed to invoke it correctly and interpret its role in the workflow.

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 has zero parameters and the schema is empty, so the baseline is 4. The description does not need to explain parameter semantics since there are none, and it does not introduce any misleading parameter-related claims.

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

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

The description clearly states the tool is a status check for a sound index: it asks and answers whether an index exists and what it contains. It names the specific resource (the installation's library sound index) and differentiates itself from its sibling match_sound by establishing a dependency relationship.

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 explicit when-to-use guidance: 'Call this before match_sound' and explains why (without an index, match_sound has nothing to rank against). It also tells the agent when the index needs rebuilding via live-maestro-index, which is practical usage context beyond simple selection.

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

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

Beyond the annotations, it discloses that quantized clip stops are grid-aligned and may not be reflected in an immediate read, and it warns that stopping does not restore envelope-driven parameters. These are non-obvious side effects an agent needs before invoking or interpreting the result.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description front-loads the main action, then uses compact Returns/Note sections; the envelope and timing caveats earn their place. It could be slightly tighter, but it is well structured and not padded.

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 2-parameter tool with rich schema descriptions and annotations, the description covers the return value, timing semantics, side effects, and follow-up alternatives. Given an output schema exists, no critical behavioral information appears 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?

The schema already fully documents both clips and quantized, including lag behavior, so the description doesn't add much parameter-level detail. The note about an immediate read still showing playback is a useful consequence but not a substantive expansion beyond the schema.

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

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

The description opens with a specific verb and resource: 'Stop transport playback, and optionally every playing Session clip.' This immediately distinguishes it from siblings like play and set_arrangement_time, and the optional clip behavior frames its scope.

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 names relevant alternatives in context: 'Use play to resume playback, or set_arrangement_time(at_beat=0) to rewind the Arrangement timeline to the beginning.' This gives an agent clear follow-up actions, though it doesn't explicitly state when not to use stop.

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 mark destructiveHint=true, and the description adds substantial context beyond that: writing replaces every note, has no undo and no LOM rollback, and a write that fails after removal leaves nothing. It also discloses nuanced failure modes around percussion and sustained pads, plus measurements behind transcription_suspect, which annotations alone could never convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long, but almost every sentence carries operational weight: measured failure rates, no-undo guarantees, and the macOS-only check caveat. It is front-loaded with purpose, then Returns, then behavioral notes. Some empirical figures could be trimmed without loss, but the structure is logical and dense rather than padded.

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 8-parameter, write-capable, destructive transcription tool, the description covers prerequisites, preview behavior, failure modes, output contents, and safety consequences. The output schema and annotations cover machine-readable details, so nothing an agent needs to call this tool correctly and safely 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 schema already documents all parameters in detail. The description adds meaningful operational context on top: 'Writing needs a clip' explains slot/confirm usage, and the span_beats/clip-length note gives practical meaning to tempo and output interpretation. A few parameters like path and preview get no new detail, but the schema fully carries them.

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

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

The opening line states a specific verb and resource: 'Turn a recording of one instrument into notes, cleaned of what it is not.' This clearly distinguishes it from mix analysis and from clip note reading/writing siblings, especially combined with the path schema contrast between a separated stem and 'a whole mix transcribes as one tangle.'

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 explicit operational guidance: use separated stems, never write drums ('Never write drums from here'), and before writing create a clip and pass confirm=True. It also clarifies that track=-1 previews without writing. It does not explicitly name an alternative tool, but the when-to and when-not-to conditions are 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?

The description reveals important behavioral traits well beyond the annotations: relative semantics that accumulate across calls, audio clips being repitched via clip.pitch_coarse with read-modify-write behavior, and the information-loss consequences of 'clamp' and 'drop'. It even caveats that the reported -48 to 48 bound is from Live docs, not a local probe. No contradiction with the annotations is present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence earns its place. It is front-loaded with the core operation, structured under 'Returns' and 'Note', and moves from behavior to usage boundaries to implementation caveats without repetition. The density is justified by the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity.Counting all relevant context: what it does, when to use it, when not to, which siblings to prefer, return value shape, parameter semantics, and data-loss caveats are all covered. The output schema exists, so the Returns section is a useful complement rather than duplication. This is complete enough for an agent to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the input schema already covers 100% of parameters, the description adds substantive meaning: it explains why repeated calls with 2 semitones move by 4, how audio clips map to pitch_coarse, and why 'error' is recoverable while 'clamp' and 'drop' are not. This goes well beyond the schema's per-parameter text.

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

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

The description opens with a specific verb and resource: 'Transpose a MIDI clip by note pitch or an audio clip via pitch_coarse.' It clearly distinguishes the operation from the sibling tools by later naming write_clip_notes and quantize_clip as alternatives. An agent can tell exactly what this tool does and what it does not do.

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

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

The description provides an explicit 'When to use' section and a 'When NOT to use' section, naming write_clip_notes for melody/chord edits and quantize_clip for timing/groove changes. It also gives operational guidance about the default out_of_range behavior. This is exemplary usage guidance with concrete alternatives.

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

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

Beyond the annotations, the description discloses several non-obvious behaviors: verification reports the stored envelope rather than the requested one, clear_first=False layers points on repeated calls, a verified write does not guarantee audibility, and playing the clip permanently moves the parameter to the curve's last value without restoring it on stop. This is rich, honest behavioral context with no contradiction to 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 description is longer than average, but every section earns its place: the action is front-loaded, returns are separated, and the note block consolidates four distinct caveats that would otherwise be surprising. The structure is clean, though the length is substantial enough to prevent a perfect score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's high complexity—10 parameters, multiple interpolation modes, and significant side effects—the description is complete. It explains the return value shape, the Session-only targeting limitation, the audibility caveat, clear_first behavior, and the post-play state change, while the output schema handles detailed return structure.

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 already describes all 10 parameters at 100% coverage, so the baseline is 3. The description adds meaningful cross-parameter semantics by explaining how clear_first interacts with repeated calls and how the verify step affects the result, going slightly beyond the schema's individual parameter descriptions.

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

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

The description opens with a precise verb and resource: 'Write an automation envelope into a Session clip and verify the read-back.' This clearly distinguishes it from sibling tools like clear_automation, read_automation, and arrange, and explicitly states that Arrangement envelopes cannot be written directly here.

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 concrete routing guidance: use arrange to move the clip to the timeline, use read_automation before retrying after an unclear result, and use clear_automation when no new points should be written. It also explains the Session-versus-Arrangement limitation, leaving no ambiguity about when this tool is appropriate.

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

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

The description discloses the exact behavior of replace (makes clip match the list) and append (layers), the side effect of an empty list with replace (keeps length, loop, envelopes), and the precise floating-point deviation of times (e.g., 0.29 reads back as 0.29000010406260407). It also explains how unknown keys are handled. Annotations declare destructiveHint=true and readOnlyHint=false, and the description aligns with these, adding substantial behavioral detail 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 description is lengthy but every section earns its place: the opening sentence states purpose, return value is described, and the note sections cover time semantics, replace/append, input validation, and numerical deviation. The structure is clear and front-loaded with the core purpose. It could be slightly tightened, but the density of useful information justifies the length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 parameters including a nested notes array, an output schema, and subtle numerical behavior), the description is remarkably complete. It covers the local clip coordinate system, the append/replace semantics, the validation rules, and the exact precision caveats. An agent has everything needed to call this tool correctly without referencing external documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description adds critical semantic detail: times are beat-based and clip-local, replace/append behavior, the handling of tolerated keys like note_id, that pitch/start_time/duration are never defaulted, and the validation consequence of using pos/dur. This goes far beyond the schema's per-parameter descriptions and materially affects how an agent should construct the notes array.

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 'Write MIDI notes into a Session clip' – a specific verb, resource, and action. It clearly distinguishes from siblings like read_clip_notes (reading), delete_clip (removes clip entirely), and write_automation (writes automation, not notes). The purpose is unambiguous and immediately differentiates the tool.

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

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

The description provides explicit guidance on when to use append vs replace, contrasts with delete_clip (empty list with replace keeps clip attributes, delete_clip removes everything), and notes that lists from read_clip_notes can be written back. It also warns that a list with pos/dur keys is refused. This gives clear context and alternatives, leaving nothing to inference.

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