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

Annotations already declare write/non-destructive/non-idempotent, so the bar is lower, yet the description adds real behavioral context: MIDI track/rack-chain preconditions, that Max for Live devices load through the browser, and that an empty drum pad triggers a new chain. It doesn't disclose failure behavior or the resulting device state/selection, keeping it at 4.

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

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

Front-loaded with the action, then packs parameter semantics into terse fragments and closes with a concrete example. It is dense but nearly every clause carries non-obvious information; a slightly tighter grouping of the chain examples could improve it.

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

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

No output schema exists, and the description covers insertion scope, preconditions, chain grammar, device sourcing, and an example. Missing only return/error behavior and post-insert side effects (selection, undo interaction), which the sibling set (undo/redo) hints at but the description never addresses.

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

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

Schema coverage is 0%, so the description carries the full burden and does so well: name casing rules with examples, position=-1 meaning end, and a detailed chain path grammar with three illustrative formats. Only 'track' is left implicit (inferable from "on a track"), which is a minor gap against a 0%-covered 4-param 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 a specific verb+resource ("Insert a native Live device") and scopes it to a track or rack chain, immediately distinguishing it from browser-based loading by naming 'live_from_browser's role. The sibling list contains many device tools (set_device, device_action, duplicate_device), and the word 'native' plus the insert-only framing separates this one cleanly.

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 routing guidance is given for a key case: "Presets and packs: load_from_browser." Preconditions are also stated ("Instruments and MIDI effects need a MIDI track or MIDI rack chain"). It doesn't systematically state when NOT to use it versus siblings like duplicate_device/move_device, so it stops short of a full 5.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description adds substantial behavioral context on top: it details exactly what gets returned (LUFS, dBTP, stereo correlation, spectral bands, dropouts, notes) and how the 'sections' and 'images' options alter 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 long but densely informative and front-loads its purpose before listing return details. Every clause contributes necessary information about output content, with no filler, though the run-on structure makes it slightly dense.

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

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

With no output schema, the description admirably covers the return payload, and annotations handle safety. Gaps remain around supported audio formats and expected 'path' format, but for a read-only analysis tool the definition is largely complete.

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

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

Schema description coverage is 0%, so the description must compensate. It clearly explains 'sections' (locators or [{name, start, end}] in seconds) and 'images' (adds spectrogram and waveform PNGs), covering two of three parameters well; only the obvious 'path' lacks format guidance.

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

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

The description states a specific verb ('Measure') and resource ('an audio file') and immediately clarifies the goal ('judge a mix without hearing it'). It enumerates the exact metrics returned, making it clearly distinct from siblings like export_audio or get_meters.

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 phrase 'so you can judge a mix without hearing it' implies the analysis use case, but there is no explicit comparison to alternatives such as get_meters or export_audio, nor any when-not guidance. Usage is suggested rather than stated.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, and the description goes well beyond them: it details exactly what gets overwritten ('A track's range is overwritten where it has a clip'), what clear=True empties, that clips become independent copies, that the transport is stopped first, and that it returns undo_steps.

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

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

Dense but front-loaded: the core mechanic comes first, then side effects, then the example. Every sentence adds information, though the parenthetical asides make it longer than strictly minimal for a tool this complex.

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, 5-param tool with no output schema, the description covers ordering semantics, overwrite scope, looping vs one-shot behavior, locator creation, transport handling, the pre-arrange editing prerequisite, and the return value (undo_steps). Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 0%, so the description carries full burden and does so well: it documents the sections element shape (scene index/name, bars or length with beats/'8 bars', optional name), clear, tracks, and locators semantics, plus a concrete example. The `start` format (e.g. '1.1.1') is only implied by the default, a minor gap.

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

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

States a specific verb+resource ('Build the arrangement from scenes') and immediately defines the mechanism: sections play in order from `start`, each placing every track's clip. This distinguishes it clearly from get_arrangement and clear_arrangement siblings.

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

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

Gives strong workflow context: write notes/automation in Session clips BEFORE arranging, or re-run with clear=True after editing, and 'Verify with get_arrangement' routes to the read-back sibling. It stops short of explicit when-not-to-use guidance (e.g. vs. manual clip placement), so not 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?

Goes well beyond the annotations: discloses that the song plays audibly, that transport/loop/metronome/arm states are restored, that same-named files are replaced, and that temporary tracks are created and removed on polling. The destructiveHint annotation is reinforced with concrete detail about what is overwritten and cleaned up.

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

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

Front-loads the core purpose, then per-parameter details, then the mandatory polling workflow. Dense but every clause is load-bearing; slightly run-on but appropriately sized for a 7-parameter tool with no schema descriptions.

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?

Complete for a mutation/export tool with no output schema: it explains the async job model, the required polling step, side effects, and output locations/defaults. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 0%, so the description carries the full burden and does: it defines formats for start/end ('bar.beat.sixteenth' or locator name), the end default behavior, tail units (beats, '1 bar', seconds), stems syntax ('all', names, indices, 'return:A'), include_returns, output_dir default and file-naming pattern.

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

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

States a specific verb and resource ('Render the arrangement to WAV in real time') plus scope ('the master plus optional stems'), which is concrete enough to distinguish from siblings like export_audio. An agent knows exactly what operation this performs.

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

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

Gives clear workflow context: the returned job must be polled via get_bounce_status(wait=50) and 'polling is required', plus a concrete example invocation. It does not explicitly contrast with the sibling export_audio, so the when-to-use-vs-alternative condition is left implicit.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed world), yet the description adds real value beyond them: item field contents (name, path, uri, kind, is_loadable, is_device), pagination behavior, and case-insensitive matching. No error behavior for bad paths is described, so it stops short of a 5.

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

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

A tight, front-loaded paragraph with no filler; the path convention is stated first and the return fields/paging follow. Slightly dense with parenthetical asides, but every clause carries information.

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

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

With no output schema and 0% parameter coverage, the description compensates by enumerating returned item fields and paging mechanics. It lacks failure modes (invalid/nonexistent path) and any note about ordering, but is otherwise sufficient 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 0%, so the description carries the burden and mostly succeeds: it explains path syntax/semantics (root "", nested example, case-insensitive names, optional extensions) and the paging role of limit and offset. It doesn't document limits on limit values or offset defaults beyond what the schema shows.

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?

Clear verb+resource ("List a browser folder") with concrete path examples that make the scope unambiguous. It implicitly separates itself from siblings like search_browser and load_from_browser, but never names or contrasts 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 root-path convention ("" lists categories) and example path give implied usage, and paging with limit/offset is explained. However there is no explicit guidance on when to choose browse versus search_browser or how it pairs with load_from_browser, leaving the workflow to inference.

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

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

Annotations only convey the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false); the description adds substantial behavioral detail beyond that — that recording halts, transport and arm states are restored, and that temporary '[bounce]' tracks are deleted. This also explains why destructiveHint=false is accurate (only temporary bounce tracks are removed) and why the operation is idempotent (the no-bounce branch still cleans up).

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

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

Two tightly written sentences that are front-loaded with the primary action and then the fallback behavior. Every clause carries information; nothing is redundant padding.

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

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

For a zero-parameter, no-output-schema tool with annotations already covering the safety profile, the description supplies everything needed: both execution branches and the state restoration side effects. Nothing an agent needs to invoke it correctly is missing.

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

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

The tool takes no parameters, so the baseline is 4; there is no parameter semantics to document. The description correctly implies a parameterless, single-action operation.

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

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

States a specific verb ('Cancel') and resource ('a running bounce') and immediately enumerates the concrete effects (recording stops, transport/arm states restored, temp tracks removed). It is unmistakably the counterpart to the sibling 'bounce' tool, so an agent can distinguish them without opening a schema.

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

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

It covers both states explicitly: cancel while a bounce runs, and clean up leftover '[bounce]' tracks when none is running, which is clear usage context. It stops short of naming an alternative or a precondition (e.g., checking get_bounce_status first), so it is not full when/when-not guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false; the description reinforces this with an explicit 'confirm before deleting the user's work' caveat and details the surgical trim behavior (clips cut at edges) that annotations cannot convey. It does not address reversibility/undo availability despite idempotentHint=false, so not a 5.

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

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

Front-loads the destructive warning and the core action, then moves to mode semantics and an example. Dense but every sentence carries information; the mode enumeration is slightly verbose but justified by the ambiguity it resolves.

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, parameter-heavy tool with no output schema, the description covers action, modes, defaults, parameter formats, and a usage example. It omits return-value/response behavior and undo interaction, but those are minor given no output schema exists.

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

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

With 0% schema description coverage, the description carries the full load: it explains start/end formats (beats, 'bar.beat.sixteenth', or a locator name), all mode values and the default, and the tracks vs all_tracks relationship. It also provides a concrete example call, which the bare anyOf schema cannot.

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

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

States a specific verb (Delete) and resource (arrangement clips) with scope (by track and time range), which cleanly separates it from the single-clip sibling delete_clip. The mode breakdown further pins down exactly what gets removed in each 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?

Explicitly documents when each mode applies (trim vs overlapping vs inside) and what omitting start/end does, plus the tracks-vs-all_tracks choice. It does not name an alternative tool to prefer for a narrower delete, so it falls short of a full when-not/alternatives statement.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the higher-destruction case: omitting `parameter` wipes every envelope, and it clarifies the Session vs arrangement clip scope. It stops short of mentioning undo or irreversible-state caveats.

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

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

Two tight sentences followed by a concrete example; the primary removal semantics are front-loaded and nothing is padded. The example earns its place by disambiguating argument types.

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 5-parameter mutation with no output schema, the description covers scope and the clear-all behavior adequately but leaves the addressing model (how track, device, slot, and arrangement_clip combine to locate the target clip) largely unexplained. An agent would still have to guess at target resolution.

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

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

Schema description coverage is 0% across 5 parameters, so the description carries the full burden and mostly fails it. The example conveys that `track` takes a name like 'Pad', that `parameter` is a string like 'volume', and that `slot` addresses the clip, but `device` and `arrangement_clip` are never explained, nor is the track/device/parameter addressing hierarchy.

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

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

States a specific verb and resource: 'Remove a clip's envelope for one parameter, or every envelope,' which is the clear inverse of the sibling write_automation. It is unambiguous what the tool does, though it does not explicitly name or contrast itself against the automation 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?

Provides one conditional usage rule (omitting `parameter` clears every envelope) and a scope note that it works on Session and arrangement clips. It does not say when to reach for this versus write_automation/get_automation, so the guidance is implied rather than explicit.

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

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

Annotations already declare destructiveHint=true and non-idempotent, so the safety profile is partly covered. The description adds real behavioral context beyond them: which actions create a new track and return it (audio_to_midi, drum_rack_from_audio, simpler_track_from_audio) and that crop keeps the loop/marker range. It still omits whether existing content is destroyed, and there are no rate-limit or auth notes.

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

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

Front-loaded with the one-line purpose, then a dense but well-packed semicolon-separated action list. Nearly every clause carries information. Slightly cramped formatting, but nothing is wasted.

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

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

For a destructive multi-action dispatcher with 0% schema coverage and no output schema, the description covers actions and their nested args but not the required top-level parameters (track, action semantics) nor any return-value expectations beyond 'these create a new track and return it.' Adequate but incomplete.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It does document the args objects for several actions (duplicate_region, quantize, add_warp_marker, remove_warp_marker) fairly well. But it says nothing about the top-level params track, slot, and arrangement_clip, leaving a meaningful gap for a 5-param tool.

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 framing sentence 'Run a clip function' is generic, but the action enumeration (crop, duplicate_loop, quantize, add_warp_marker, audio_to_midi, etc.) makes the tool's actual scope concrete: a dispatcher for clip-level edits. An agent can tell what it does. However, it never differentiates itself from siblings like transform_notes, edit_notes, or write_notes, which partly overlap with the quantize/MIDI 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?

No explicit when-to-use, when-not-to-use, or alternative guidance is given. The description never routes the agent toward clip_action versus transform_notes/edit_notes for note operations, nor states prerequisites (e.g., that slot or arrangement_clip must be set). Usage must be inferred entirely from the action names.

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 a non-destructive, non-idempotent, closed-world write. The description goes well beyond that by disclosing monitoring/input settings ('In', 'No Input'), placement at the end of the set, the routing side effect, the uniqueness constraint, the audio-output prerequisite for sources, and that reverting requires two undo steps. This is rich behavioral context that annotations alone 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 front-loads the core definition of a bus, then layers constraints, routing guidance, and an example call. It is dense and every sentence carries useful information, though the long opening sentence with nested parentheticals could be split for easier parsing.

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

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

With no output schema, the description covers creation mechanics, routing, post-creation mixing, prerequisites, and undo behavior thoroughly for a write tool. It omits what the tool returns (e.g., the new track identifier) and the accepted color encoding, but those are secondary 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 0%, so the description must compensate. It explains that 'name' must be unique and that 'sources' are tracks whose output is routed into the bus (requiring audio output), and the example demonstrates 'color' with a hex string. It does not clarify that color accepts either an integer or a string, nor whether sources accept track names, indices, or both, but it covers most parameter 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 states a specific verb and resource ('Create a bus') and immediately clarifies that it creates a special audio track acting as Live's substitute for group tracks, with source outputs routed into it. This distinguishes it from sibling tools like create_track by describing the distinctive routing behavior. An agent can tell what the tool does without opening the schema.

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

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

It gives concrete usage context: mix the bus like any track with set_mixer or add_device, name must be unique, sources need audio output (MIDI tracks need an instrument), and reverting takes two undo steps. It does not explicitly state when to prefer this over create_track or duplicate_track, but the operational guidance is clear and actionable.

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 destructiveHint=true and non-idempotent, so the safety profile is covered. The description adds real behavioral context beyond that: overlapping MIDI ranges on the arrangement are refused, audio reports what it trimmed, and the call returns the new clip 'as get_clip'. It does not explain overwrite behavior for an occupied slot, which is the main remaining gap.

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

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

Front-loaded with the core purpose, then a compact per-parameter block, closing with a concrete example. Dense but every line carries format or constraint information; the only minor cost is that the parameter notes read as a terse list rather than prose.

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

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

For a nine-parameter mutation tool with no output schema, the description supplies the return value ('as get_clip'), the units/formats for the ambiguous params, and the failure semantics for overlapping arrangement ranges. What remains thin is the interaction with an already-occupied slot and the audio-path prerequisites.

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

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

With 0% schema description coverage across 9 parameters, the description compensates thoroughly: slot is a 0-based scene index, at accepts beats, 'bar.beat.sixteenth' or a locator name, length is MIDI-only in beats or 'N bars' with a stated 4-beat default, color is an index 0..69 or '#RRGGBB', and pattern is drum steps. Only the trivial track and name params go unexplained.

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

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

Opens with a specific verb+resource ('Create a clip') and immediately enumerates the distinct creation modes: MIDI into a Session slot, MIDI at an arrangement time, or audio from file_path. An agent can distinguish this from siblings like duplicate_clip, write_notes, or create_scene without opening any schema.

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

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

States when each mode applies (slot vs at vs file_path, MIDI vs audio tracks) and names the equivalent lower-level calls for in-line filling ('as write_notes', 'as write_drum_pattern'). It lacks an explicit when-not / prerequisite rule, e.g. what to do if the target slot is already occupied, so it falls short of a 5.

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

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

With annotations already declaring the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description adds genuine behavioral detail beyond them: the transport must be stopped, Live snaps to the 1/16 grid, placement is bounded by song length, and locators are indexed in time order. It stops short of stating error behavior or the return value.

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

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

Front-loads the action and target, then layers prerequisite, snapping behavior, and an example without padding. Slightly dense, but every sentence carries information an agent needs.

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

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

For a mutating tool with no output schema, the description covers the key operational facts: prerequisite state, grid snapping, song-length bound, and indexing. It omits what the call returns (e.g., a locator id) and failure modes, which are minor gaps here.

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

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

Schema coverage is 0%, so the description must carry the load, and it does: it explains `time` accepts beats or a 'bar.beat.sixteenth' string and that `name` is optional. The example (create_locator("17.1.1", "Chorus")) concretely demonstrates both parameters, though it doesn't spell out the plain-beats numeric format precisely.

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

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

States a specific verb ('Add') and resource ('arrangement locator (cue point)'), and the parenthetical clarifies the term. An agent can distinguish it from siblings like set_locator and delete_locator without opening a schema.

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

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

It states a concrete prerequisite ('The transport must be stopped') which shapes when the tool can be called, but never contrasts itself with the sibling set_locator/delete_locator or says when to prefer each. Usage context is implied rather than explicit.

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

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

Beyond the destructiveHint/readOnlyHint annotations, the description discloses the concrete destructive behavior ('replacing same-named files'), the exact loudness/limiting algorithm, per-format encoding, artwork embedding targets, stems handling, and the deterministic output path and release.json contents. This is rich behavioral context that materially informs invocation.

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 tool's purpose is front-loaded in the first clause, followed by dense, largely load-bearing technical detail. It is somewhat long, but given 13 parameters and no schema descriptions, most sentences earn their 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 13-parameter mutation tool with no output schema, the description supplies the missing output contract (directory layout and release.json contents) and processing semantics. The main shortfall is that several metadata parameters are left undocumented, but overall it is sufficient 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?

With 0% schema description coverage the description must carry the load, and it does so well for the non-obvious parameters: target_lufs (with -14 streaming note), true_peak (dBTP), formats (default all, enumerated values), artwork (JPEG/PNG), and stems ('auto' vs paths). It omits explicit meaning for several metadata params (year, album, genre, track_number) and the source/output_dir params, so a few gaps remain.

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: 'Master and package a finished song.' It enumerates the concrete pipeline (normalise, encode, tag, embed artwork, write release.json) and clearly distinguishes this finishing step from the bounce it consumes, so an agent can tell it apart from siblings like bounce/export_audio.

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

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

Usage is only implied: the mention of 'a bounced master' and 'the bounce's other files' signals this runs after a bounce, but the description never states the prerequisite explicitly or names a when-not/alternative. The agent can infer the workflow position but receives no explicit 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 declare non-read-only, non-destructive, non-idempotent. The description adds genuine behavioral context beyond that: index -1 appends at the end and tempo/time_signature cause Live to switch to them when the scene fires. It does not mention whether inserting at index shifts existing scenes, which is a small gap.

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

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

Tight and front-loaded: the core action leads, parameter semantics follow, and a single example call closes it. No sentence is padding.

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

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

For a mutation tool with no output schema, the description covers all parameters and the tempo/time-signature side effect. It omits prerequisites such as an open Set and the effect of index insertion on neighbouring scenes, but nothing critical to invoking 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 description coverage is 0% and there are 5 params, so the description must carry the load – and it does. It explains index semantics (-1 = end), colour encoding (Live index 0..69 or '#RRGGBB'), tempo units (BPM), and time_signature format ('3/4'), plus a concrete example call.

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

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

States a specific verb and resource ('Create a Session scene') and clarifies the domain object via the parenthetical 'a song section'. An agent can distinguish it from set_scene, delete_scene, fire_scene and duplicate_scene at a glance.

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

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

The description implies creation for song arrangement but never states when to use this versus siblings like set_scene (modify existing), new_set, or duplicate_scene. No prerequisites (e.g. a Set must be open) are given, so usage is only implied.

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

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

Annotations declare non-read-only, non-destructive, non-idempotent, closed-world, but the description adds real behavioral context beyond them: native devices are inserted directly while Max for Live/pack devices load through the browser, and new MIDI tracks can come up armed. It also states the return payload (ref, routing, arm state), which matters since no output schema exists.

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

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

Dense but front-loaded, with a worked example at the end. Every clause carries parameter or behavioral information; the single long paragraph is slightly heavy but 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 5-param mutation tool with no output schema and 0% schema coverage, the description compensates fully: it documents all parameters, the device-loading path, the MIDI-track prerequisite, and the return fields.

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

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

Schema coverage is 0%, so the description carries the full burden and does: it defines kind values, index semantics (-1 = end, returns last), color format (0..69 or "#RRGGBB"), device name matching (case-insensitive, native vs browser-loaded), and name. This is more than the bare schema provides.

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 ('Create a track') and immediately enumerates the kind values, distinguishing it from create_bus/create_scene. An agent can tell exactly what this tool produces without opening the schema.

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

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

Provides concrete usage conditions: instruments and MIDI effects require a MIDI track, returns always go last, index=-1 means end, and devices can be inserted by name. It does not explicitly point to siblings (e.g. create_bus, duplicate_track) as alternatives, so it falls just 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 already declare destructiveHint=true, so the safety profile is covered. The description adds valuable behavioral context: it specifies that the tool deletes Session or arrangement clips and instructs the agent to confirm with the user before deleting their own material. It does not mention undo or whether deletion is reversible, but this is a strong addition over 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?

Two short, front-loaded sentences with no wasted words. The purpose is stated first, followed by the destructive confirmation requirement.

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 annotations cover destructiveness and no output schema exists, so return values need not be explained. However, for a tool with three parameters at 0% schema coverage and two deletion modes (Session vs arrangement), the description is too thin to fully guide correct invocation, especially regarding which parameters select which mode.

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

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

Schema description coverage is 0% for all three parameters (slot, track, arrangement_clip). The description mentions 'Session or arrangement clip,' which hints at two modes, but it does not explain what slot, track, or arrangement_clip mean or how they map to the modes. It fails to compensate for the undocumented 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 states a specific verb (Delete) and resource (Session or arrangement clip), clearly distinguishing it from sibling deletion tools for scenes, tracks, notes, devices, and locators. An agent can identify exactly what this tool removes without opening the schema.

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

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

The description implies usage by saying it deletes a Session or arrangement clip, and it adds a caution about confirming with the user before deleting their own material. However, it does not name alternatives or state when-not to use this tool versus delete_scene, delete_track, or clear_arrangement.

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 destructiveHint=true, but the description adds meaningful context beyond them: the deletion is cascading ('a rack with everything in it'), it is reversible via undo, and it returns what remains. That reverses the usual opacity of a destructive op and is genuinely useful for a mutation.

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

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

Two tight sentences: the core action and scope come first, followed by the destructive caveat. No wasted words, though the destructive note could be folded more economically.

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 no output schema, the description covers what gets removed, its reversibility, and return behavior ('returns what remains'). The only missing piece is parameter format detail, which is the remaining incompleteness.

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

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

Schema description coverage is 0%, so both required parameters (track, device) carry no documented meaning. The description hints that track is the container and device the target, but never explains the integer|string id formats or that device may be an array, leaving a real gap it should have filled.

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

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

States a specific verb and resource ('Delete a device') and clarifies scope by defining a device as 'a rack with everything in it' and locating it 'from its track or chain'. This distinguishes it from delete_track, delete_clip, and delete_scene without the agent needing to inspect other 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?

Gives clear when-to-use guidance by flagging it as destructive and instructing the agent to confirm with the user before deleting their own work, plus notes that undo reverts it. It stops short of explicitly naming sibling alternatives (e.g., device_action or undo) as routing options, so it is clear but not fully differentiating.

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 destructiveHint=true and readOnlyHint=false, so the mutating nature is covered. The description adds genuinely new behavioral context: the transport-stopped prerequisite and the playhead being restored afterwards, which are side effects not derivable from 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?

Two sentences, front-loaded with the action, no filler; the addressing detail and precondition each earn their 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?

With no output schema, the description is appropriately scoped: addressing semantics, precondition, and side effects are covered. It could note failure behavior (e.g., if the transport is running or the locator is not found), but for a one-param tool it is essentially complete.

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

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

Schema coverage is 0%, so the description carries the burden and does so well: it explains the lone param accepts either an index (interpreted in time order) or a name. This disambiguates the anyOf integer/string type that the schema leaves unexplained.

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

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

States a specific verb+resource ('Delete a locator') and clarifies the addressing modes, distinguishing it cleanly from siblings like create_locator and set_locator. An agent knows exactly what this does without opening the schema.

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

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

Provides a precondition ('The transport must be stopped'), which is implied usage guidance, but never names alternatives (e.g., set_locator vs delete, or undo) or states when deletion is preferable. Context is implied rather than explicit.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and non-idempotency, so the safety profile is covered. The description meaningfully adds the half-open interval semantics ('notes starting in [start, end)'), the AND-combination of filters, and the required-filter constraint, which an agent needs to avoid over-deletion. It stops short of describing return/error behavior or idempotency quirks.

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

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

Two sentences, front-loaded with the core action and its filter selectors, then the constraint. Dense and largely waste-free, though the mapping of the various selectors is packed into one long clause that borders on a run-on.

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

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

For a 10-parameter destructive mutation tool with no schema descriptions and no output schema, the clip-targeting parameters (track, slot, arrangement_clip) and the error/return behavior are left unexplained. What is present is accurate, but the definition does not fully equip an agent to call it on the correct clip.

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

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

With 0% schema description coverage the description must carry the full burden, and it does document the deletion-defining params (note_ids, pitches, pitch_min/max, start/end) plus the half-open start/end semantics. But it never mentions three clip-targeting parameters — the required 'track', 'slot', and 'arrangement_clip' — leaving the agent to guess which clip is operated on.

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

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

States a specific verb and resource ('Delete notes from a MIDI clip') and enumerates the selection mechanisms (note_ids, pitches, pitch range, time range, all=True), which clearly distinguishes it from the sibling delete_clip. It does not explicitly name the sibling it relates to (get_notes/write_notes/delete_clip), so it earns a 4 rather than a 5.

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

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

Provides the key operating constraint ('Filters combine; at least one is required'), which is genuine usage guidance for invocation. However, it offers no guidance on when to prefer this over sibling tools like edit_notes or delete_clip, nor any prerequisites beyond the filter requirement.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds non-obvious behavior: cascading deletion of all clips in the scene's row and the minimum-one-scene constraint, which the annotations 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?

Three short sentences, front-loaded with the action and cascade behavior, followed by the destructive warning and the invariant. No wasted words.

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

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

No output schema is needed for a delete tool, and annotations cover the safety hints. The description supplies cascade scope, the confirmation requirement, and the one-scene invariant; only error/edge-case behavior on an invalid scene reference is unaddressed.

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

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

Schema description coverage is 0%, so the description must compensate. Stating the scene may be given as 'index or name' explains the schema's anyOf (integer|string) meaningfully, though it doesn't say how names are resolved or what happens on ambiguity.

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

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

States a specific verb (Delete) and resource (a scene), and clarifies scope as 'together with every clip in its row,' which distinguishes it from siblings like delete_clip and delete_track. An agent can tell immediately what is removed.

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 instructs confirmation before deleting user material and states the business constraint that a set must retain at least one scene. It doesn't name an alternative or an explicit when-not condition, but the context is clear enough to route correctly.

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

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

Goes well beyond the destructiveHint annotation by disclosing the full blast radius (clips and devices are removed), the cascading side effect of deleting a return (sends to it are removed and later returns reletter), the master exclusion, and reversibility via undo. This is exactly the extra context annotations cannot carry.

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

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

Front-loads the core action, then layers constraint, side effect, and caution in short sentences with zero filler. Every sentence adds distinct information.

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

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

For a one-parameter destructive tool with no output schema, the description covers destruction scope, cascade effects, limits, and reversibility well. The remaining gap is how to specify the target track, which belongs in the description given the empty schema coverage.

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

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

The single `track` parameter has 0% schema description coverage and the description does not compensate: it never says whether the value should be a track index, name, or position, nor how a 'return' is addressed. The integer|string anyOf is left entirely unexplained.

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

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

Names a specific verb and resource (delete_track), states the scope (regular or return track with all its clips and devices), and adds a hard constraint the agent must respect (master cannot be deleted). An agent can distinguish this from delete_clip, delete_scene, and delete_device without opening any schema.

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

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

Gives clear operational context: it is destructive, the user should be asked to confirm before deleting their own work, and undo reverts it. It does not name an explicit alternative path when the agent should not delete, but the caution guidance is concrete and actionable.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds that certain actions (e.g., delete_chains, remove_slice) may be destructive, but doesn't detail permissions, reversibility, or side effects beyond the action names.

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

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

The description is a single long sentence followed by a dense list of actions. It is front-loaded with the core purpose but lacks formatting to separate device categories, making it somewhat hard to parse.

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

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

Given 4 parameters with 0% schema coverage, no output schema, and destructive annotations, the description is incomplete. It doesn't explain the format of args for each action, nor the return values or error handling, leaving significant gaps 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 0%, so the schema provides minimal meaning. The description explains that args holds named arguments for the action, but doesn't clarify the types or expectations for track, device, or action beyond their names. This is insufficient for a 4-parameter tool with zero 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 clearly states it runs type-specific device functions with args as named arguments. The enumerated action catalog shows the scope of operations, though it doesn't explicitly differentiate from siblings like set_device or clip_action.

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

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

It lists actions but provides no guidance on when to use device_action vs. alternatives like set_device, set_device_parameters, or clip_action. No prerequisites or context are given.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, and the description confirms that behaviour with the specific consequences: move=True relocates rather than copies, clip envelopes travel with the copy, and occupied slots or overlapping arrangement ranges are refused. The refusal semantics and envelope propagation are real added context beyond the annotations.

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

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

Front-loaded with the core action and route modes, then destinations/defaults, then constraints, then a concrete example. Every sentence adds information; no filler or restatement of the title.

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, 7-parameter mutation tool with no output schema and zero schema-level parameter docs, the description covers almost everything an agent needs to call it correctly. Only arrangement_clip and any return/confirmation behaviour are left unaddressed.

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

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

Schema description coverage is 0%, so the description carries the load and does well: it explains to_slot defaults, to_time accepting beats or "bar.beat.sixteenth" notation with its arrangement default, to_track defaulting to the same track, and move's copy-vs-move switch. The one gap is arrangement_clip, which is never mentioned.

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

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

States a specific verb+resource ('Copy ... a clip') and enumerates the exact source→destination route combinations it supports (Session→Session slot, Session→arrangement, arrangement→arrangement). This scope statement makes it clearly distinguishable from create_clip and delete_clip in the sibling list.

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

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

Gives concrete usage context: the move=True variant, the defaults for destination (next empty slot below, same track; right after itself for arrangement sources), and the refusal conditions for occupied slots and overlapping ranges. It stops short of naming an alternative tool (e.g. create_clip for a fresh empty clip).

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 write (readOnlyHint=false), non-destructive, non-idempotent behavior. The description adds useful behavioral detail: duplication is right after itself, racks include contents, and track instruments are not duplicated. 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?

Two tight sentences, front-loaded with the core action. No filler; every sentence adds purpose or routing information.

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

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

The description covers purpose, placement, and the key duplicate_track limitation, and annotations cover safety. However, with 0% schema parameter coverage and no output schema, the agent still lacks guidance on how to specify the track and device arguments.

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

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

Schema description coverage is 0% for two required parameters. The description names 'device' and 'track or chain' but does not explain accepted forms (integer/string/array) or how to identify track/device, so it fails to compensate for undocumented parameters.

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

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

States a specific verb ('Duplicate') and resource ('device', racks with contents), plus placement in track/chain. It explicitly distinguishes itself from duplicate_track for track instruments.

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

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

Gives an explicit alternative: use duplicate_track when trying to duplicate a track's instrument, or use another Instrument Rack chain. This is when-to-use/when-not guidance tied to a sibling.

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

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

Annotations already cover the safety profile (readOnly=false, destructive=false, idempotent=false). The description adds genuinely useful behavior beyond that: it returns the new scene, it selects the new scene, and — importantly — later scene indices shift by one, which is a non-obvious side effect an agent must account for.

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

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

Two tight sentences, front-loaded with the action and scope, followed by the return/side-effect note. No filler.

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

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

For a one-parameter tool with no output schema, the description supplies the parameter form, the return value, and the index-shift side effect. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 0%, so the description must carry the parameter burden. It does so for the single `scene` param by stating it accepts an index or a name, which the schema's bare anyOf integer/string does not convey in words.

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

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

Specific verb+resource with full scope: duplicates a scene including its clips, places it directly below, and selects it. This clearly distinguishes it from siblings like create_scene (which would not copy clips) and duplicate_clip/duplicate_track.

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

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

Implied usage is clear from the copy-and-place semantics, but the description never states when to prefer this over create_scene or fire_scene, and names no alternatives. Adequate context with no explicit 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 declare the write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds valuable behavior beyond that: where the copy lands (right after the original), that it becomes selected, and the return/master track exclusion. It stops short of saying what happens on name collision or whether the original is untouched.

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

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

Two short sentences, front-loaded with the action and scope, then the constraint. No filler; every clause carries information an agent can act on.

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

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

For a 2-parameter mutation with no output schema, the description covers scope, side effects (selected, adjacent placement), and the key restriction. It is only incomplete on the `track` identifier format, which matters given 0% schema coverage.

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

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

Schema description coverage is 0%, so the description must carry the parameters. It covers naming ("Optionally name the copy") but leaves `track` ambiguous — the anyOf integer|string allows index or name and the description never says which form is accepted.

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

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

Specific verb+resource ("Duplicate a regular track") with explicit scope: devices, clips, and mixer settings are included in the copy. Naming "regular track" plus the note that return/master tracks cannot be duplicated distinguishes it clearly from siblings like duplicate_clip, duplicate_scene, and duplicate_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?

States a hard precondition (Live cannot duplicate return or master tracks), which prevents a whole class of failed calls, and describes the resulting placement/selection. It does not, however, explicitly route the agent between this and duplicate_scene/duplicate_clip for adjacent tasks.

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

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

Annotations already establish readOnly=false, destructive=false, idempotent=true, so the safety profile is covered. The description adds a non-obvious behavioral fact beyond them: edits target notes by id and 'keep their ids,' which is exactly the identity-preservation detail that makes idempotency meaningful here.

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

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

Front-loaded with the core action, then the edit shape, then a compact example, then the alternative tool. Every sentence carries information; no filler.

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

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

For a mutation tool with no output schema and informative annotations, the description covers what is editable, how to format edits, the required id source, and the sibling alternative. The only real omission is the meaning of slot/arrangement_clip, which an agent needs to target the right clip.

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

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

Schema description coverage is 0%, so the description must carry the load. It does this excellently for edits (required note_id plus the full list of editable fields and a concrete example), but says nothing about the slot or arrangement_clip parameters, leaving half the interface undocumented.

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

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

States a specific verb+resource (change existing notes) with an explicit scoping key (note_id from get_notes) and pins down that ids are preserved. The agent can distinguish this from write_notes (creates) and transform_notes (relative/mass changes) without opening any schema.

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

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

Gives the source of the required identifier (from get_notes) and names an explicit alternative with its condition: 'For relative changes on many notes use transform_notes.' Clear routing guidance, though it doesn't state what happens if a note_id doesn't exist or when slot/arrangement_clip should be used.

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

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

Goes well beyond the annotations by disclosing side effects and constraints: it temporarily sets the arrangement loop to the range and restores it afterwards, the format/render settings follow the Export dialog's last state, it never overwrites a file, and it requires macOS UI automation permission. These are exactly the behavioral facts an agent needs before invoking a UI-driven export.

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

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

Purpose and scope are front-loaded in the first sentence, with constraints following. It is somewhat dense across several lines, but nearly every clause carries operative information rather than filler.

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

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

No output schema exists, yet the description never states what a successful call returns (e.g., the written file path or a confirmation), which matters given the 'never overwrites' behavior implies failure modes. Everything else needed to call the tool correctly — range semantics, permission requirement, alternative tool — is present.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does: it explains that `start`/`end` accept beats or "bar.beat.sixteenth" notation and that `path` is a ".wav" destination. It stops short of saying whether the path must be absolute or whether parent directories are created, so it is not fully compensating.

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

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

States a specific verb and resource ('Render the arrangement ... with Live's own offline File > Export Audio/Video, to `path`') and immediately differentiates itself from the sibling bounce tool. An agent can identify both the action and its mechanism without opening the schema.

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

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

Explicitly routes the agent: 'Prefer bounce, which needs no UI permission,' and states the prerequisite 'Needs macOS UI automation (see get_status).' Both the when-to-use and the when-to-prefer-an-alternative conditions are given.

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 the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the bar is lower. The description adds genuinely new behavior: firing is deferred to the next launch-quantization boundary and Live starts the transport, which the agent could not infer from 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?

Two tight sentences, front-loaded with the core action and followed by the verification/stop paths. Every clause carries information; there is no filler.

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

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

For a two-parameter side-effecting tool with no output schema, the description covers timing behavior and the natural follow-up tools. The only real gap is parameter meaning (track/slot addressing), which it leaves entirely to the undocumented schema.

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

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

Schema description coverage is 0% for both required parameters. The description mentions 'Session slot' and 'track' only in passing and never explains slot indexing, the int-or-string track reference (name vs. index), or valid ranges. With zero schema documentation, the description fails to compensate.

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

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

States a specific verb and resource: 'Launch the clip in a Session slot'. The Session-slot scoping distinguishes it from the arrangement/transport siblings and from fire_scene, and the quantization note clarifies the launch semantics rather than restating the name.

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 routes follow-up actions to concrete alternatives: check results with get_clip or get_meters, stop with stop_clip or transport. It gives clear context for the surrounding workflow, though it does not state when not to use fire_clip (e.g. vs. fire_scene or clip_action).

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

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

Annotations only declare the safety envelope (readOnly=false, idempotent=false, destructive=false). The description adds genuine behavioral context beyond them: it starts the transport, applies the scene's tempo/time signature, respects launch quantization, and describes force_legato's immediate legato behavior — all non-obvious side effects not derivable from structured fields.

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

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

Front-loads the core action and consequence, then tacks on the force_legato nuance and the stop/audition routing. Every sentence carries information, though packing the audition/stop guidance into one clause is slightly dense.

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

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

With no output schema and only safety annotations, the description supplies the missing behavioral context (transport start, tempo application, legato, stop path). It does not describe any return value or error conditions, but for a fire-and-act tool whose result is observed via get_meters, coverage is adequate.

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

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

Schema coverage is 0%, so the description must carry parameter meaning, and it does: 'scene (index or name)' clarifies the anyOf integer/string choice, and 'force_legato launches clips immediately in legato' explains the boolean's effect. Both parameters are covered, though the quantized (non-legato) default behavior could be spelled out slightly more explicitly.

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

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

States a specific verb and resource ('Launch a scene (index or name)') and immediately explains the effect on the row's clips, distinguishing it from fire_clip (single clip) and create_scene/set_scene (scene management). An agent can tell what this does and how it differs from siblings without opening the schema.

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

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

Gives clear operational context: audition with get_meters, and stop via transport("stop_all_clips") or transport("stop"). It names concrete alternatives for the stop/audition workflows but does not explicitly contrast fire_scene against fire_clip, so the when-not-to-use boundary is implicit rather than stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds useful behavioral context beyond that: the filter semantics (overlap-based range), the accepted time formats, and the cap ('At most `limit` clips are listed') which signals possible truncation of results.

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

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

Front-loads the return shape, then the filter semantics, then a concrete example, with no filler sentences. The long parenthetical enumerating clip fields is dense but every item earns its place for an inspection 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?

Since there is no output schema, the description correctly documents the return structure, and it covers all four input parameters plus an example. It omits the default limit value (200, visible only in the schema) and any pagination note, leaving minor gaps for a read 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?

With 0% schema description coverage, the description must carry all parameter meaning and largely does: start/end are explained with accepted formats (beats or "bar.beat.sixteenth"), and limit is described behaviorally. The 'tracks limits the tracks' clause is thin — it doesn't clarify whether entries are indices or names — so it isn't fully compensating.

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

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

States a specific verb and resource ('The arrangement timeline') and enumerates what it returns (tracks, clips with fields, locators, loop region, song length). This clearly distinguishes it from siblings like get_song_overview or get_clip without needing to open 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?

Gives concrete usage context: start/end keep only clips overlapping the range, tracks limits the tracks, and a worked example (start="9.1.1", end="17.1.1"). It does not name alternatives or state 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 already declare readOnly, idempotent, non-destructive, closed-world behavior, so safety is covered. The description adds real context beyond that: values are returned in display units (dB, Hz, pan), the sample points span the clip loop, and it works for both Session and arrangement envelopes.

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

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

Three compact sentences plus a concrete example, front-loaded with the primary behavior and with the display-unit and scope details appended. Every sentence adds information and nothing is redundant.

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

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

There is no output schema, and while the description sketches the returned content (parameter list, breakpoints, samples), the shape of the return and the roles of several inputs remain thin for a 6-parameter, 0%-coverage tool. Adequate but with clear gaps.

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

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

Schema coverage is 0%, so the description must carry the load. It explains `parameter` well (listing vs breakpoints) and references `samples`, and the example demonstrates track-as-string and slot usage. But `device` and `arrangement_clip` are undocumented in both schema and description, leaving known gaps.

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: list the parameters a clip automates, and with `parameter` also its breakpoints and samples. It clearly marks this as a read/inspection tool and covers both Session clips and arrangement-clip envelopes. It does not explicitly distinguish itself from write_automation/clear_automation, so it stops short of a 5.

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

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

Usage is implied by the two modes it describes (omit `parameter` to list parameters, supply it to get breakpoints/samples), and the example shows them. However, it never names alternative siblings or states when NOT to use this tool versus get_clip or write_automation, leaving routing 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?

The annotations alone (readOnlyHint=false, idempotentHint=true, destructiveHint=false) leave the non-read-only claim unexplained; the description supplies the reason by disclosing that completion triggers file delivery, that takes are trimmed sample-exactly to the range, and that temporary '[bounce]' tracks are removed. That is meaningful side-effect disclosure beyond the structured fields, though auth/rate-limit or error-recovery behavior is not covered.

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

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

Front-loaded with the core purpose, then structured by state (running / done / failed / cancelled). It is telegraphic and dense, but each fragment carries distinct information — no filler sentences.

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

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

There is no output schema, so the description must describe returns, and it does so exhaustively: phase, progress, eta_seconds while running; folder, manifest and per-file {stem, path, duration_seconds, peak_dbfs, silent} when done; plus the failed and cancelled cases. Nothing needed to interpret a response 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 0%, so the description carries the parameter alone, and it does: 'wait: seconds (0-50) to long-poll until the bounce finishes' gives units, valid range and observable effect. Only the default value (0) is left to 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 first sentence names a specific resource and state ('Progress of the current bounce') and the terminal behavior (deliver files, return paths), which cleanly separates it from siblings like get_status, bounce and cancel_bounce. An agent knows exactly what question this tool answers without opening the schema.

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

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

It tells the agent to pass wait to long-poll until the bounce finishes, notes that 'cancelled' appears after cancel_bounce, and hands off explicitly with 'Next: analyze_audio(path)'. It stops short of stating when NOT to call it (e.g., when no bounce is in flight) or contrasting it directly with get_status.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: return content varies by clip type (audio adds gain_db, pitch, warping; arrangement clips give start/end), and notes retrieval is capped by `limit`. It does not mention authorization or failure modes, but for a read tool this is solid.

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

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

Front-loaded with the scope, then the conditional return content, then the notes option. The property enumeration is long but each clause adds information rather than restating the name; minimal 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?

There is no output schema, so the description rightly explains return values, which it does thoroughly and per clip type. But for a 5-parameter tool with 0% schema coverage, the omission of how slot vs arrangement_clip vs track select the clip is a meaningful completeness gap affecting 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 0% across 5 parameters, so the description must carry the load, and it only clarifies notes and limit ('up to `limit` notes'). The two address-selecting parameters, slot and arrangement_clip, plus track, are never explained, so an agent cannot tell from the description how to identify the target clip or whether slot and arrangement_clip are mutually exclusive.

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

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

States a specific verb and resource (retrieve every property of one clip) and enumerates what that includes, which makes it clearly distinct from get_notes and get_track. It does not explicitly say what it is not, so it stops short of full sibling differentiation.

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 only routing guidance is a narrow note about notes: 'notes=True adds up to `limit` notes (or use get_notes with filters)', which usefully points at an alternative. However, there is no guidance on when to use this versus get_track, set_clip, or clip_action, and none on the addressing modes.

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, destructiveHint=false, and openWorldHint=false. The description adds meaningful behavioral context by describing the return payload and how detail and parameters alter what is returned, though it does not discuss errors, permissions, or limits.

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, followed by return-content details and then parameter notes. The long enumeration is dense but appropriate for a complex device-inspection tool, with little wasted text.

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

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

With no output schema, the description usefully enumerates the return data, which is a strong plus. However, 0% schema coverage and no explanation of the required track parameter leave the definition under-specified for a complex device retrieval tool.

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

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

Schema description coverage is 0%, so the description must compensate. It explains device path formats and the detail/parameters toggles, but it omits the required track parameter entirely, leaving a significant gap.

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?

"One device in detail" names a specific verb and resource, and the enumerated return components make the scope concrete. It does not explicitly name the sibling get_devices to contrast list-versus-detail, but the singular scope implies the distinction.

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 never states when to choose this tool over get_devices, set_device, or device_action. The only guidance is output-toggle behavior (parameters=False, detail=True), which is not tool-selection 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 readOnly/idempotent/non-destructive, so safety is covered. The description adds real behavioral context beyond structured fields: recursive chain traversal, visible macros, variation counts, and that only non-empty Drum Rack pads are listed.

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

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

Front-loaded with the core purpose followed by progressively finer detail. One long sentence, but each clause (paths, macros, pads) carries distinct information with no filler.

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

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

With no output schema, the description correctly carries the return-value burden and does so thoroughly for a read tool. The only real omission is explaining the `track` input, which is a minor gap given the otherwise complete return 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?

Schema coverage is 0% and the lone parameter `track` (int or string) is never explained in the description – the agent cannot tell whether it expects an index, name, or path. The path format '1/0/0' describes output, not the `track` input, so it does not compensate for the gap.

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 resource ('device tree of a track') and enumerates exactly what is returned, so the agent knows this differs from a single-device read like get_device. It does not explicitly name the closest sibling for differentiation, but the scope is 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?

'Pass a path as `device` to other tools' implies a workflow (this tool feeds others) but stops short of stating when to use it versus get_device or other device siblings. Usage is implied rather than spelled out.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: the shape of the returned data and the non-obvious global groove amount range (0..1.31), which an agent could not infer from the empty schema.

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

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

Two sentences, zero filler. The return payload is front-loaded and the follow-up action is placed second, which is the correct order for an agent deciding whether to read.

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

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

With no output schema and no input parameters, the description carries the full burden of describing the response, and it does so: field list, units (percent), and the exceptional global amount range. Nothing needed to call this correctly is missing.

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

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

Zero parameters, so the baseline is 4. The only parameter-like information given is for a different tool (set_clip's groove argument), which is still helpful for chaining but does not apply here.

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 the resource ('the groove pool') and enumerates exactly what it yields — index, name, base grid, amounts, global amount — so an agent can distinguish it from set_groove and set_clip. The verb is implicit (a noun phrase rather than 'returns/lists'), which keeps it short of a 5, but the resource and scope are unambiguous.

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

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

It routes the agent forward by naming set_clip(groove=...) as the way to assign a groove, which is useful context for what to do after reading. However, it never states when to call this getter versus set_groove, nor any precondition, so usage is only implied.

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

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

Annotations already establish read-only/idempotent/non-destructive, but the description goes well beyond: it documents the full return shape (peak_db, left_db, right_db, raw 0..1), the dBFS conversion formula, the over_0db threshold, audio-vs-MIDI differences, and the critical behavioral trait that meters only advance during playback.

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

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

Dense but front-loaded: the core purpose leads, then output semantics, then the key constraint. Every sentence carries technical value, though the parenthetical formula is slightly crammed into the flow.

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

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

With no output schema and only 0%-covered parameters, the description fully carries the return-value burden, explaining units, units conversion, flags, and per-track-type behavior. 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 lone `tracks` parameter is undocumented in the schema (0% coverage), and the description compensates by clarifying it narrows output to 'only `tracks`' (excluding returns/master). It does not specify accepted id/name formats, but it adds real 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 a specific verb (read) and resource (Live's meters) with explicit scope: 'Momentary peak levels of every track, return and master'. An agent can distinguish this from siblings like get_mixer or analyze_audio without opening a schema.

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

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

Implied usage as a monitoring/read tool, and it provides the key caveat that 'Meters only move while the transport plays'. However, it never states when to prefer this over alternatives (e.g. get_mixer) or any exclusions, so guidance is only inferable.

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, and destructiveHint=false, so the safety profile is covered. The description adds useful return-shape context (specific fields returned, '-inf' meaning silence) but doesn't describe pagination, scope limits, or error 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?

Front-loads the core scope (mixer state of all tracks in one call) and then enumerates returned fields. Dense but focused. Slightly overloaded by the field list and minor formatting oddities, but every sentence carries information.

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

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

No output schema exists, so the description must describe the return value, which it does thoroughly (fields, units, -inf semantics, master-specific additions). Missing only details on the tracks filter semantics and any edge cases for an agent calling it with a subset.

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

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

Schema description coverage is 0% for the single tracks parameter, so the description must compensate. It mentions 'only tracks' implying a subset filter, but doesn't clarify accepted identifier formats (integer vs string) or scope. Adds marginal value over the bare schema.

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

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

States a specific verb+resource: reading mixer state for regular, return, and master tracks. Clearly distinguishable from set_mixer (its write counterpart) and get_meters. Not explicitly differentiated from siblings in text, but the mixer-state reading purpose is 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?

Implies a use case (retrieve all mixer state in one call) and notes the optional tracks filter. No explicit when-to-use vs alternatives guidance, e.g. no routing to get_meters for metering or to get_track for per-track detail. Adequate but with clear gaps.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuine behavior: results are sorted by time, filters are combined (ANDed), and start/end is a half-open interval [start, end) over note start times. It omits the limit/pagination behavior despite a limit parameter defaulting to 200.

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

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

Front-loaded with the return shape, then filters, then the downstream-tool routing and an example. Dense and mostly waste-free, though the field enumeration is long and the 'Optional filters (combined)' line reads slightly run-on.

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

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

With no output schema, the field list is essential and present; time formats and filter semantics are covered. Gaps remain for limit-based pagination and the slot/arrangement_clip addressing needed to actually target a clip.

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

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

Schema coverage is 0%, so the description must carry the load and largely does: it explains pitches, pitch_min/pitch_max (numbers or names), start/end, and note_ids, and gives the "bar.beat.sixteenth" vs clip-beats format with a worked example. It leaves limit, slot, and arrangement_clip unexplained.

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

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

States a specific verb+resource ('Notes of a MIDI clip') and enumerates exactly what a note record contains (note_id, pitch, start, duration, velocity, etc.) plus the sort order. An agent can distinguish this read tool from write_notes/edit_notes/delete_notes without opening a schema.

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

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

Explicitly routes the returned ids to edit_notes, delete_notes or transform_notes, and gives a concrete call example. It does not state when to prefer this over get_clip or how it relates to arrangement clips, so it stops short of full when/when-not coverage.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context beyond them: state-dependent output where the channel list reflects the currently selected type, a required re-read after set_track, and a scope limit for return/group/master tracks.

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

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

Front-loaded with the purpose in the first sentence, followed by two short supporting sentences. No filler, though the awkward line breaks add no value.

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

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

With no output schema, the description usefully previews what is returned (types and channels) and flags the scope exception for return/group/master tracks. The remaining gap is the undocumented track parameter format.

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

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

Schema description coverage is 0% and the single 'track' parameter accepts either an integer or string, yet the description never clarifies whether it is an index, name, or path. With low coverage the description needed to compensate and does not.

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

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

States a specific verb and resource: reading the current input/output routing of a track along with the available types and channels. This is clearly distinct from the broader get_track resource, though no sibling is named to reinforce the differentiation.

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 a concrete workflow rule: the channels belong to the current type, and after switching type with set_track the agent must re-invoke this tool. It also gives a caveat that return, group and master tracks expose output routing only. No explicit when-not or alternative-search guidance, but the usage context is clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive, non-open-world behavior, so the safety profile is covered. The description still adds useful behavioral context: the exact return surface, the fact that times are returned as beats plus 'bar.beat.sixteenth', and how detail=True expands the payload. It does not mention auth, caching, or cost, but the annotation bar is low here.

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

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

Front-loaded with the one-line purpose ('One-call map of the project') followed by dense but factual enumerations. The long parentheticals are information-rich rather than padding, though the sheer volume of listed fields is on the verbose side. No sentence is wasted.

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

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

With no output schema, the description correctly takes on the burden of describing return contents, so an agent knows what it will receive. Annotations cover safety and the alternates are named. Only the absence of any note on payload size/cost for detail=True keeps it from being fully complete.

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

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

Schema description coverage is 0% for the single 'detail' parameter, so the description must carry the meaning — and it does: detail=True explicitly enables every set_song setting, mixer levels (dB), pan/sends, device classes and on/off, clip colours, and arrangement clip lists, versus the lean default. This fully compensates for the empty schema.

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

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

States a specific verb+resource (a one-call overview/map of the project) and enumerates exactly what it covers: tempo, meter, key/scale, tracks, returns/master, scenes, locators, selection. It also distinguishes itself from siblings by naming get_track and get_notes as the deeper alternatives. An agent can place it precisely without opening any schema.

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

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

The closing 'Use get_track or get_notes for more' explicitly routes the agent to alternatives when per-track or note-level detail is needed. There is no explicit when-not statement or prerequisite, but the intended usage (broad snapshot first, drill down later) is clear.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, it discloses a non-obvious behavioral trait: the tool still answers when Live is unreachable, returning connected: false plus a fix hint. It also explains the dialog-pending state and how capabilities gate other tools, which is exactly the kind of context annotations cannot carry.

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

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

The opening 'Start here.' is well front-loaded, and the remaining sentence is information-dense with no filler. It is a single very long enumeration clause that could be broken up for scanability, but every item 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 status tool with full annotation coverage and no output schema, the description covers the payload fields, the degraded-mode behavior, and the follow-up action, so an agent has everything it needs to call it and interpret the result.

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

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

The tool takes zero parameters, so by the rubric the baseline is 4. There is nothing for the description to clarify, and the schema is trivially complete.

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 identifies this as the diagnostic entry point ('Start here') and enumerates exactly what the status report contains: connection, versions, open set, transport state, dialog, jobs, and capabilities. An agent can distinguish it from every sibling (which are all mutation/query tools) without opening the schema.

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

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

It gives a strong positive trigger ('Start here') and explicitly routes to respond_to_dialog when the dialog field is set, plus names which capabilities gate analyze_audio/create_release/save_set etc. It does not state when this tool is not appropriate (e.g., polling vs. event-driven use), so it stops just short of the top band.

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, so safety behavior is covered. The description adds useful behavioral detail about what is returned and how detail=True expands the result to every slot, arrangement clip, full mixer, meters, and 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 dense and front-loaded, with the core read behavior first and detail-mode behavior second. The final track-format line is slightly orphaned but still useful, and there is no filler.

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

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

With no output schema and zero schema parameter descriptions, the definition adequately explains the returned track contents, the detail flag, and accepted track identifiers. It omits error behavior and exact response shape, but for a read-only inspection tool it is largely complete.

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

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

Schema description coverage is 0%, so the description must carry all parameter meaning. It does: track accepts an index, name, "return:A", or "master", and detail=True is explicitly defined as expanding the response to include everything else.

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: 'Read one track'. It then enumerates the exact content returned (mixer, routing, devices, session slots, arrangement, take lanes), which makes it clearly distinct from sibling tools like get_mixer, get_devices, or get_song_overview.

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

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

The description implies when to use the tool by defining it as a single-track read and explains how the detail flag changes scope. However, it does not explicitly compare against alternatives such as get_mixer, get_devices, or get_song_overview, so routing between siblings remains inferred.

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 covering the safety profile (destructive=true, idempotent=false), the description adds substantial behavior: an instrument/preset/drum kit replaces the track's instrument, a sample on a MIDI track becomes a Simpler, clips load as a new track, and the default slot is the first empty slot. It discloses exactly what gets mutated, which is what an agent needs for a destructive tool.

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

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

Front-loads the core action and packs target-specific semantics into a tight block with no filler. Slightly hurt by mid-sentence line breaks that make the 'Targets' paragraph denser to parse than 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?

For a 7-parameter tool with no output schema, it covers the selector inputs, the target rules, edge cases (clips create tracks), defaults, and even the return shape. Nothing material 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 description coverage is 0%, so the description must carry the full burden, and it largely does: position (device insert index), drum_pad (note 'C1'/36 or pad name), slot (Session scene index, default first empty), and the uri/path/query disjunction are all clarified beyond the bare types. Only 'track' is left to inference, keeping it just below full compensation.

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

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

States a specific verb (Load) and resource (browser item onto a track) and names the sibling tools (search_browser, browse) that produce the identifier. An agent can distinguish it from add_device/add_* siblings without opening any schema.

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

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

Explicitly requires exactly one of uri/path/query and points to search_browser/browse as the source for identifiers, giving clear workflow context. It stops short of contrasting directly with add_device (the nearest sibling for placing devices), so it is clear but not fully alternative-routing.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description adds useful return behavior ("Returns the result, with a path for any object returned"), but says nothing about the destructive potential or that method names must be valid Live Object Model methods.

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

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

Front-loaded with the core action, followed by one tight example and a return-value note. No filler sentences; every line 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?

No output schema exists, and the description does provide a minimal return contract (result plus path for returned objects). For a generic object-method dispatcher with a 0%-coverage schema, more would help – e.g. how `path` strings are formed or what happens on an invalid method – but the essentials to make a call are 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?

With 0% schema coverage, the description must carry the load, and it does: it explains that `path` refers to an object, that `args` are positional, and the example demonstrates all three parameters including an empty-arg and negative-number case. `method` is only shown by example rather than defined, hence not a 5.

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

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

States a specific verb (call) and resource (a function of the object at `path`), and the example disambiguates the argument order concretely. However it does not distinguish itself from the close siblings lom_get and lom_describe, which an agent would need to pick between.

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

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

Usage is implied by the worked example (lom_call("live_set", "create_scene", [-1])), so an agent can infer the calling convention. But there is no explicit when-to-use guidance relative to lom_get/lom_describe, nor any note that this is the mutation-capable path of the trio.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral content by specifying that the result includes writability flags and Live's documentation, but it omits path validity handling, output shape, or any caveats about querying invalid paths.

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

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

A single, front-loaded sentence that conveys the core action, the target, and the notable extras. There is no filler or repetition.

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

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

For an introspection tool with no output schema, the description is moderately complete because it sketches what is returned. However, the missing path syntax and failure behavior create meaningful gaps for an agent that needs to call it correctly without a schema description.

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

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

There is one optional string parameter with 0% schema description coverage, so the description must compensate. It only mentions `path` without explaining syntax (e.g., 'live_set tracks 0'), valid values, or what the default 'live_set' represents, leaving the parameter underspecified.

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

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

States a specific verb (List) and resource (properties and functions available at `path`) with the added detail that writability and Live's docs are included. This clearly distinguishes it from generic value getters, though it does not explicitly name sibling tools like lom_get or lom_call for contrast.

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

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

No guidance about when to use this tool versus lom_get, lom_call, or others. It does not mention prerequisites, exclusions, or the consequences of choosing this introspection call over retrieving a value directly.

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 the safe, idempotent, read-only profile, and the description adds real value on top: the path dialect (Max for Live style) with three concrete examples and the output shape for lists (counts and names). It does not say what happens on an invalid or nonexistent path, which is the main remaining gap for a path-driven reader.

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

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

Front-loaded with the action and resource, then syntax, then routing advice, then output shape. No filler sentences, though the guidance and path material are packed into one block rather than visually separated.

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

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

With no output schema, the description does the right thing by describing the return form for objects and lists. It stops short of error/failure behavior and depth semantics for nested paths, which matters for a generic object-model reader.

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

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

Schema coverage is 0%, so the description must carry the load, and it does: the `path` parameter's syntax and semantics are given with worked examples, and `properties` is explained as an optional projection ('all property values or only `properties`'). It could be tighter on whether subproperty indexing is supported, but the core usage is conveyed.

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

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

Specific verb (Read) plus resource (an object of Live's object model) and scope (by path, with full properties or a subset). It is clearly distinguishable from lom_set, lom_call, and lom_describe, and it explicitly positions itself against the curated 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?

"Use the curated tools first; this reaches anything they do not cover" is an explicit when-not rule and tells the agent this is the catch-all fallback. The alternatives are described only as a category rather than named, so an agent still has to infer which sibling to prefer for a given 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?

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, covering the safety profile. The description adds that the target property must be writable and that value can be a reference object using {"path": "..."}, which is useful context but does not describe side effects, persistence, or undo 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?

Two concise sentences with the core action front-loaded and no filler. The second sentence conveys an important special case efficiently.

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 LOM setter in a large sibling toolset, the description lacks guidance on choosing it over specific setters and does not mention how to discover valid paths or properties (e.g., via lom_describe). Annotations cover safety, but parameter coverage and routing context remain incomplete.

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

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

Schema description coverage is 0%, so the description must compensate for all three parameters. It names path, property, and value, and explains one special value format, but does not clarify path syntax, property naming conventions, or expected value types, leaving substantial gaps.

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 (Set) and resource (a writable property of the object at path), distinguishing it from lom_get and lom_call. It does not explicitly differentiate from specific setters like set_track or set_scene, but the core action is 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?

No guidance is given on when to use lom_set versus alternatives such as set_song, set_track, or lom_call. The only extra sentence concerns value syntax, not tool selection or prerequisites.

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

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

Annotations only declare the generic mutation profile (readOnly=false, idempotent=false, destructive=false, closed world). The description adds real behavioral detail beyond that: Live auto-corrects to the nearest valid position, MIDI effects are kept ahead of the instrument, and instruments/MIDI effects cannot be placed on audio tracks. It does not say what the move returns or what happens if the target is invalid.

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

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

Front-loads the one-line purpose, then breaks the optional parameters into labeled clauses, which is easy to scan. The final constraint sentence crams three separate rules together, adding mild density but no real 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?

For a 5-parameter mutation tool with no output schema and no schema-level parameter docs, the description supplies the placement semantics, defaults, and validity constraints an agent needs to call it correctly. The remaining gap is the identity/format of the required track and device arguments.

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

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

With schema description coverage at 0%, the description carries the burden and does so for three of five parameters: it defines to_track, to_position (omitted or -1 = end) and to_chain (with concrete chain-path examples). The two required parameters, track and device, are left unexplained, including the fact that they accept either an index or a name, so the coverage is good but incomplete.

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

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

States a specific verb and resource ("Move a device") plus the three positional scopes it can act on: within its chain, to another track, or into a rack chain. That distinguishes it from siblings like duplicate_device and add_device, though it never names an alternative 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?

Gives operational context (defaults, index behavior, where Live will place the device) but never states when to prefer this over duplicate_device, device_action, or delete_device, nor any precondition such as requiring the source device to exist. Usage is implied rather than routed.

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

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

Annotations already declare this is a read-only, idempotent, non-destructive, closed-world computation. The description adds two traits annotations cannot express: it never touches the Live set ('without touching Live') and it fixes the MIDI octave convention (C3 = 60), which materially affects numerical results. It says nothing about error handling for invalid chord/scale names, keeping it below a 5.

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

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

Purpose and the octave convention are front-loaded, then one compact clause per operation. Every phrase earns its place, including the illustrative literals that double as format documentation. No filler or repetition.

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

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

For a 12-parameter, multi-operation tool with no output schema and no schema descriptions, the description covers the operation matrix and sketched return shapes ('-> pitches', '-> MIDI number, names, frequency') well. Defaults (octave=3, octaves=1, voicing='close') and failure behavior for bad input names are left to the schema and inferred, so it is not fully self-contained.

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

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

Schema description coverage is 0% across 12 parameters, so the description must carry the load, and it largely does: it gives accepted forms for key ('A', 'F# dorian'), chord ('Am7', 'C/E', 'V7'), voicing values (close, open, drop2, drop3, spread), and the roles of inversion, octave, beats_per_chord and voice_leading. Gaps remain: the plural 'octaves' parameter and integer keys are never explained.

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 concrete resource (music theory utilities) and immediately enumerates the five operations with what each computes, including concrete input/output examples. The phrase 'without touching Live' cleanly separates it from the DAW-mutating siblings (write_notes, set_clip, etc.). An agent can tell what this tool does and what it does not.

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

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

Usage is conveyed per operation: use 'scale' with key+scale, 'chord' with a symbol or numeral, 'progression' to get chords and notes 'ready for write_notes', 'notes' to convert names/numbers, 'list' to discover valid scale/chord/voicing names. The mention of write_notes establishes the downstream relationship. There is no explicit when-not-to-use or named alternative, 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?

Goes well beyond the destructiveHint annotation: it discloses that unsaved changes are refused by default, that discard_unsaved=True answers the save prompt with 'Don't Save' (data loss), the UI-automation dependency, and a confirm-with-user instruction. This is exactly the extra behavioral context a destructive tool needs.

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

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

Front-loads the '[UI automation]' marker and the core behavior, then adds constraints. Mostly tight, though the parenthetical menu path and save-prompt detail add some density, still all earning their 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 destructive, environment-dependent mutation, the description covers the dependency check, the data-loss semantics, and the user-confirmation requirement. No output schema is needed for an action of this kind.

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

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

Schema coverage is 0% and the single parameter has no schema description, so the description must compensate. It explains that discard_unsaved=True causes the save prompt to be answered 'Don't Save' (i.e., unsaved work is lost) and that the default refuses unsaved changes, which is more than the bare boolean schema provides.

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

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

States a specific verb and resource ('Start a new empty Live Set'), names the menu path (File > New Live Set), and describes the effect ('replacing the current one'). This clearly distinguishes it from siblings open_set and save_set.

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

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

Explains the prerequisite (macOS UI automation must be available and get_status shows whether/how to enable it) and the destructive-confirmation requirement. It does not explicitly contrast with open_set/save_set, but the context is clear enough for correct 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?

Goes well beyond the destructiveHint annotation by explaining exactly when destruction occurs (only with discard_unsaved=True), the save-prompt failure mode when discard_unsaved=False, and that the call blocks until the set has loaded. This is the kind of behavioral depth annotations alone 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?

Front-loads purpose, then layers behavioral detail; every sentence adds actionable information. The middle sentence is somewhat dense but not wasteful, and the closing follow-up step is well placed.

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 mutation tool with no output schema, it covers the critical gaps: permission needs, failure mode, destructive branch, blocking semantics, and the recommended next call. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 0%, so the description must carry the parameter meaning, and it does for discard_unsaved by spelling out both the default (False) and True behaviors and the destructive consequence. The path parameter is left implicit, but its meaning is self-evident from the .als 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?

States a specific verb and resource ('Open a Live Set (.als)') and the scope consequence ('replacing the current set'), which cleanly distinguishes it from siblings like new_set and save_set. An agent can identify the operation without opening the schema.

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

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

Gives clear usage context: 'No UI permission needed' and the follow-up action 'then call get_song_overview'. It also prescribes confirming with the user before destructive discard. It stops short of explicitly naming alternatives (e.g., new_set for a fresh set), so it is strong but not exhaustive.

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

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

Annotations cover the safety profile (non-read-only, non-idempotent, non-destructive), and the description adds real behavioral value beyond them: the return shape (count redone plus can_undo/can_redo) and the stateful rule that 'any new change clears the redo history'. It omits error/permission behavior, keeping it from a 5.

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

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

Two tight sentences, zero waste, with the core action front-loaded before the return-value and history-reset details. Every clause 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-optional-param mutation tool with no output schema, the description supplies the return contract, the range, and the stateful caveat, so it is nearly self-sufficient. Minor gaps remain around error cases and default behavior.

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

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

Schema coverage is 0% (the `steps` param has only a title and default 1), so the description must compensate, and it does: it defines steps as the count of previously-undone actions and gives the valid range 1..100. It does not explain out-of-range or interaction with the default, keeping it below a 5.

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

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

States a specific verb (redo) and resource (steps actions), scopes it to actions 'previously undone with undo', and thereby distinguishes itself from its sibling `undo`. An agent can tell exactly what this does without opening the schema.

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

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

The description anchors usage to the `undo` sibling ('actions previously undone with undo') and gives an implicit when-to-use cue via redo-history semantics. It stops short of explicitly stating when NOT to use it or naming `undo` as the alternative in a routing sense, so it is clear context without 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 already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds useful context beyond that: it explains the full flag's effect, the failure reporting behavior, and that previous code keeps running on import failure.

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

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

Two short paragraphs, front-loaded with the core action and followed by the parameter detail and failure semantics. Every sentence adds distinct information with no 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?

For a single-parameter developer tool with no output schema, the description covers purpose, parameter meaning, and failure behavior. It does not describe any success return value, but that is minor given the tool's nature.

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

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

Schema description coverage is 0% and the only parameter is 'full', but the description explains what full=True does (reloads the shell module), compensating for the missing schema description. It does not explain default behavior when full is omitted, but the implication is clear.

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

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

States a specific verb (hot-reload) and resource (the Remote Script's code inside Live) and frames it as a developer tool. No sibling tool in the list does anything similar, so it is clearly distinguishable.

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 phrase 'Developer tool' implies a development-time context, but there is no explicit when-to-use, when-not-to-use, or named alternative. Usage is only implied.

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

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

Annotations flag destructiveHint=true generically; the description goes further and names exactly which option is destructive ('dont_save' discards unsaved work) and prescribes confirming with the user. This is meaningful added context beyond the structured safety profile.

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

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

Two short paragraphs, front-loaded with the action, then the parameter explanation and the one warning that matters. No filler sentences.

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

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

For a single-parameter tool with annotations and no output schema, the description covers action, parameter values, and destructiveness. It stops short of noting behavior when no dialog is open or how an invalid index/name is handled, but those are minor omissions.

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

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

Schema coverage is 0%, so the description carries the full burden, and it delivers: index semantics (0 = first button) plus the exact string names valid on known layouts ('ok', 'save', 'dont_save', 'cancel'). This translates the anyOf integer|string schema into actionable values.

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

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

States a specific verb and resource ('Press a button on the dialog Live is showing') and scopes it to the currently-open dialog, tying directly to the get_status sibling that reports it. An agent can distinguish this from all other session tools without opening the schema.

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

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

Implies the correct sequence by referencing get_status as the source of the dialog's message and button count, and gives explicit caution ('confirm with the user first') before the destructive 'dont_save' path. It does not state what to do when no dialog is present, but the when-to-use condition is clear.

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

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

Goes well beyond the annotations: it discloses that save-as never overwrites an existing file (important nuance against destructiveHint=true), that Live may create a new "<name> Project" folder, that the result is verified via file path or modification time, and that macOS UI automation is required. These are exactly the side effects an agent needs before calling a mutating tool.

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

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

Front-loads the core action and keeps the mode distinction and caveats tight. The verification sentence is slightly meta for a tool description but is short and does convey how success is confirmed.

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

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

With no output schema and a single optional parameter, the description covers everything needed: preconditions, path semantics with an example, non-overwrite behavior, folder side effect, and the platform requirement. 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 0%, so the description must carry the `path` parameter — and it does: it explains the save-as semantics, gives a concrete example ("~/Music/My Song.als"), and states the failure condition when omitted. Only the accepted format details (absolute vs. tilde paths, extensions) are left implicit.

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

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

States a specific verb and resource (save the current Live Set) and immediately distinguishes two modes: plain save vs. save-as when `path` is supplied. An agent can tell this apart from siblings like new_set and open_set without opening any schema.

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