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

Zero annotations are provided, so the description carries the full burden — and it delivers. It discloses the disk-vs-live distinction, and adds a genuinely useful data-model insight: automation lives in two places, with empirical stats (52/174 projects have clip envelopes vs 159/174 have track automation) warning an agent not to conclude a project lacks automation when only clip envelopes are absent. This is high-value behavioral context well beyond the 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?

Clean, front-loaded structure: one-line summary, Args, Returns, then a clearly marked Note for contextual guidance. The Note section is the longest part but every clause carries routing or data-model value; no filler sentences. This is appropriately sized for a 4-parameter tool with a nuanced niche.

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

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

Covers purpose, all parameters, the return container, and the niche use cases, and an output schema exists so return detail is not needed. The only real gap is failure behavior for a disk read — missing/corrupt file, unsupported .als version — which an agent will not be prepared for.

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

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

Schema description coverage is 0%, so the description must compensate, and it does completely: the Args block documents all four parameters. Path gains accepted extensions (.als/.adg), track gains 'name or index' semantics, and both booleans get their behavioral effects ('parses clip notes and calculates note metrics,' 'formatted human-readable summary report'). Every parameter receives meaning beyond its title.

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

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

States a specific verb and resource: 'Read saved Ableton project (.als) or rack (.adg) structure directly from disk,' naming exact file types and the disk source. The 'Channel B' framing positions it against the live-connection LOM tools (get_session, get_track, get_clip) and its counterpart als_write, so an agent can tell it apart without opening schemas. Naming the two questions it answers — 'what is in someone else's project' and 'where an envelope's breakpoints actually sit' — makes scope unmistakable.

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

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

Provides explicit routing: 'This is Channel B, a peer of the live connection rather than a fallback' says when-not to use it, and the two questions it alone can answer give concrete selection criteria for when to use it over the LOM. It names the alternative by class ('the LOM') rather than specific sibling tool names, which is the only gap.

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

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

With no annotations provided, the description carries the full burden and does so well. It discloses the confirmation requirement, the open-file restriction, measured behavior for sidechain and configure operations, that configure fills plugin parameter strips which LOM calls cannot, that 128 slots are allocated with no insertion, and that attribute refuses ambiguous ElementTree matches unless index is provided.

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

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

The description is front-loaded with the core purpose, requirement, and operations before the Args block. The Note section adds valuable behavioral detail but is somewhat cluttered with corpus statistics and a measured-date aside that are less directly actionable for tool invocation.

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

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

For a complex 14-parameter tool with no annotations and no schema descriptions, the description covers most needed guidance: parameters, safety confirmations, file-open conditions, and behavioral notes. Gaps remain for the 'restore' operation, the exact meaning of 'backup', and how allow_live_running relates to the confirmed/unconfirmed open-file rule. The presence of an output schema offsets some need to describe return values.

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

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

Schema description coverage is 0%, and the description compensates by documenting all 14 parameters with purpose beyond field names. Most are clear, such as tap ('pre' or 'post'), expression as an ElementTree path, and value as a configure assignment string. However, 'backup' is only described as 'Backup filepath?' which is incomplete, and 'allow_live_running' is vague ('Whether Live may be running') given the earlier open-file condition.

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: 'Edit a saved .als project file on disk.' It also lists the four supported operations ('sidechain', 'configure', 'attribute', 'restore'), so an agent can immediately see what the tool does and how it differs from live-set tools like lom_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?

The description gives clear conditions: requires confirm=True, the target file must not be open in Live unless confirmed, and it explicitly directs on-screen set edits to lom_set instead. It does not fully explain when to choose among the four operations, nor does it compare against als_read for reading files, which leaves some selection guidance 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?

No annotations are present, so the description must carry behavioral disclosure. It does state the core behavior (duplicate, not move), the destination, and an expected return value ('placement status and arrangement clip counts'). However, it does not disclose what happens if a clip already exists at the target beat, whether the source remains untouched, or any permission/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?

A single informative first sentence, followed by a compact Args block and a one-line Returns note. No wasted words; the most important action is front-loaded.

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

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

For a single mutation with four params, no annotations, and an output schema, the description provides all calling details and return shape. The only notable gap is target-conflict/overwrite behavior, which keeps it just short of 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%, but the description compensates fully: it defines track as source index in song.tracks, slot as scene/slot index, at_beat as target start position in beats, and to_track as destination with source-track default. This gives real meaning beyond the schema's bare integer/anyOf types.

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

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

The opening sentence names a specific verb (Duplicate), a specific resource (Session clip), and a precise destination (Arrangement timeline at a beat position). This clearly separates it from siblings like set_arrangement_time or create_clip even though no sibling is explicitly named.

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 first line: use this to copy a Session clip into the Arrangement. There is no explicit when/when-not guidance or comparison with alternatives such as create_clip or write_clip_notes, so it meets but does not exceed the implied-usage bar.

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

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

With no annotations provided, the description carries the full behavioral burden and handles it well. It explicitly states that deletion requires confirm=True, that confirm=False inspects instead of deleting, and that the return value reports either clearance status or pending envelope details.

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

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

The description is compact and well structured: a front-loaded behavioral summary, a two-line confirm-mode distinction, a concise Args list, and a one-line Returns note. Every sentence adds useful information and there is no redundant 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?

Given that the tool has five parameters, no annotations, and dual destructive/inspection behavior, the description covers all essential invocation semantics. An output schema already exists for the return shape, so the brief Returns line is sufficient, and nothing needed to call the tool correctly appears missing.

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

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

Schema description coverage is 0%, so the Args block is essential and fully compensates. Every parameter is explained in meaningful terms: track and slot index positions, parameter as a DeviceParameter LOM path, all_envelopes selecting full clearance, and confirm as the mandatory execution gate.

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: 'Delete automation envelopes on a Session clip.' It then clarifies the confirm-dependent dual behavior, which distinguishes it from sibling tools like read_automation, write_automation, and clip-level deletion tools.

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

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

The description explains two modes clearly: confirm=True executes deletion, confirm=False inspects and reports without deleting. However, it never names sibling alternatives or states when to prefer clear_automation over read_automation or write_automation, so routing guidance is mostly implied.

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

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

With no annotations, the description carries the behavioral burden. It discloses the MIDI-track requirement, the no-overwrite behavior, and the fact that the result is read-back verified. It does not state the exact error/failure mode for occupied slots or invalid inputs, which would make the behavior fully transparent.

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

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

The description is front-loaded with a one-sentence summary, then organized into compact Args, Returns, and Note sections. There is no filler; each section provides necessary operational 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 create operation with no annotations, the description covers the Session context, MIDI-track requirement, occupied-slot caveat, and verification return. It is complete for normal invocation; only edge-case failure behavior is left unspecified, which is a minor gap.

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

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

Schema coverage is 0%, so the description must compensate, and it does: all four parameters are documented with semantic meaning beyond the schema. Track is an index into song.tracks and must be MIDI, slot is an index into track.clip_slots, length_beats is loop length in beats with a default, and name is optional.

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 an empty MIDI clip of specified length in a Session slot. It also clarifies that the target must be a MIDI track, which distinguishes it from general clip operations and siblings like write_clip_notes.

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

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

The core use case is clear from the first sentence, and the note adds an explicit when-not: it does not overwrite occupied slots and directs agents to call delete_clip first when replacing. It does not explicitly route to sibling tools such as write_clip_notes for workflows that need note content, so it stops just short of 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?

With no annotations, the description carries the disclosure burden. It explains track renumbering, resolved-index semantics, returned status/counts, and the measured Live version. The first line promises a resolved index while the Returns section mentions a dictionary, leaving a minor ambiguity about where the index appears.

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 text is organized into Args, Returns, and Note sections, front-loaded with the action, and every sentence contributes technical detail. 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 a three-parameter tool with no annotations and zero schema descriptions, the description covers parameter semantics, edge cases, side effects, return shape, and version context. An agent can invoke it correctly without needing extra inference.

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

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

Schema coverage is 0%, so the description must fully explain the parameters. It does this clearly: kind choices, insertion-index behavior including -1, and name's optionality, all adding meaning beyond the bare schema.

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

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

The description names a specific action, 'Insert a MIDI, audio, or return track', and states the output it returns. This clearly differentiates it from sibling tools like create_clip or delete_track by focusing on track creation and index resolution.

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

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

It provides explicit per-kind behavior and index semantics, including the special -1 case and the fact that index is ignored for return tracks. It does not name alternative sibling tools, so it stops short of full alternative 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?

With no annotations, the description carries the full burden and it succeeds: it discloses the destructive action, the mandatory confirmation flag, the dry-run behavior, and the return dictionary. This is strong transparency for a mutation tool.

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

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

The description is front-loaded with the purpose, then the safety behavior, then concise parameter docs and return type. No filler or redundant restatement of the schema.

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

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

For a simple three-parameter tool with an output schema, the description covers selection, deletion, safety flag, parameters, and return value. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. The Args section explains track as an index in song.tracks, slot as an index in track.clip_slots, and confirm as the execution gate—adding meaning beyond bare property names. It could be slightly stronger with index base or default handling, but it is sufficient.

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

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

The description states a specific verb and resource ('Delete the clip in a Session slot') and clarifies the confirm-gated deletion behavior versus the dry-run inspection mode. This clearly distinguishes it from sibling tools like delete_track or delete_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?

It explicitly says deletion requires confirm=True and that confirm=False inspects the slot and reports what would be deleted, which is concrete usage guidance. It does not name alternatives or state when not to use the tool, but the context is clear enough for an agent to select it for deleting clips.

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

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

With no annotations, the description carries the full burden and excels: it discloses the destructive gate (confirm=True), the dry-run reporting mode (confirm=False reports device details and parameter count), the side effect that subsequent device indices shift down by one, and even the Live 12.4.5 measurement date. This is exactly the behavioral context an agent needs before invoking a destructive operation.

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

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

The action and the critical confirm requirement are front-loaded in the first two sentences, followed by scannable Args/Returns/Note sections. Each element — the index-shift warning, the pending-loss-report return, the version measurement — earns its place, and the whole description stays under roughly 100 words.

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

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

For a three-parameter destructive tool with no annotations and an output schema present, the description is essentially complete: action, safety protocol, all parameter semantics, return summary ('Dictionary reporting deletion status or pending loss report'), post-deletion side effect, and an alternative operation. The output schema covers the return structure, so the slightly cryptic 'pending loss report' phrase is an acceptable summary rather than a gap.

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

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

Schema description coverage is 0%, but the Args section fully compensates: track is mapped to 'Track index in song.tracks', device to 'Device index within track chain', and confirm to 'Confirmation flag required to execute deletion.' Every parameter receives domain meaning beyond its raw type, and the confirm default-of-false interacts correctly with the stated 'Requires confirm=True' behavior.

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

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

The description opens with a specific verb-resource pair — 'Remove a device from a track device chain' — and the 'device chain' scoping distinguishes it from sibling deletes like delete_clip and delete_track. It stops short of 5 because the phrasing closely mirrors the tool name itself, so the clarity leans partly on the function name rather than on original framing.

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

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

The confirm=True requirement plus the explain-confirm=False-preview behavior imply a two-phase safe-usage pattern, and the note that devices can be reordered via song.move_device hints at an adjacent alternative. However, there is no explicit when-to-use versus when-not-to-use statement, and the move_device note covers reordering, not a competing deletion path.

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

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

Annotations are absent, so the description carries full burden. It discloses the destructive action, index-shift side effect, the confirm gate, and the exact preview contents (track name, devices, filled Session slots, Arrangement clips). This is far more transparent than a bare mutation note.

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

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

Well structured with Args/Returns/Note and the core action is front-loaded. Minor redundancy: 'renumber subsequent tracks' repeats in the Note, and 'Requires confirm=True' repeats in the Args.

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 two-parameter tool, it covers invocation, preview behavior, return type, and side effects; the output schema fills in the exact return shape. No critical missing context remains despite the lack of annotations.

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

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

Schema description coverage is 0%, yet the description fully documents both parameters: track is the index into song.tracks, and confirm is the flag that must be true to delete while false yields a loss report. It compensates for the schema's bare titles.

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?

First sentence names the exact operation and resource: 'Delete a track' and adds the side-effect 'renumber subsequent tracks'. This distinguishes it from sibling delete_clip/delete_device and leaves no ambiguity about what is acted on.

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

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

The description makes the invocation condition explicit: execution 'Requires confirm=True' and confirm=False acts as a dry-run loss report. It doesn't explicitly mention when to prefer delete_clip or delete_device, so it stops short of full alternative 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?

With zero annotations, the description carries the full disclosure burden and meets it: it states the Live 12.4.5 version requirement, the precondition that the connected set be loaded, that rack display is not implemented, that deep describes are slow with unmeasured cost, and that the tool falls back to probing parameter indices and reports which of two answer kinds it is returning. All of this is behavior beyond what the schema could 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?

Purpose statement is front-loaded, followed by context, a clean Args block, then behavioral constraints — a good scan order for an agent. It is long, but every sentence carries information an agent needs. The final paragraph is structurally garbled ('Live 12.4.5. When that happens this tool falls back...') and appears to belong with the with_parameters explanation, which hurts scannability.

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

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

For a runtime-introspection tool with 3 parameters, no annotations, and an output schema, the description is nearly complete: purpose, all parameter semantics, performance risk, version/platform preconditions, fallback behavior, and routing to lom_call/lom_enums/browser. Notable gaps are the lack of any distinction from the lom_describe sibling and no statement of error behavior for invalid paths, though the presence of an output schema relaxes the need to describe return values.

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 schema provides no parameter help, so the description must compensate fully. It does: path gets concrete LOM examples (song.tracks[0].devices[1]) plus a pointer to ableton://catalog, depth gets a cost caveat, and with_parameters gets its complete effect (name, value, min/max, quantized steps, display unit) and its diagnostic purpose.

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 and resource: 'Introspect any live object: class, properties, children, and methods,' which enumerates the exact outputs and separates it from get_* tools, lom_get, and lom_call. However, it never addresses the near-identically-named sibling lom_describe, so an agent cannot tell whether describe is an alias, a wrapper, or a distinct operation.

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

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

Explicitly states when this tool is the right choice ('the route to the dynamic surface...which no catalog can know in advance') and gives direct when-not guidance with named alternatives: 'Methods are never callable through a path. Use lom_call' and 'call lom_enums for rack.lom_parameters and browser for presets.' It also tells when to set with_parameters (diagnose an unconfigured plug-in).

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

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

With no annotations, the description carries the full burden and over-delivers: it reveals the filled-slot precheck, the generic-bridge limitation for waring-mode fields, the verified vs. hypothesis status of specific fields, and the measured fact that writing waring changes time values. It also honestly notes what is and is not established about the mechanism.

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 purpose is front-loaded and later paragraphs are clearly structured by topic. The content is unusually long, but most of it is substantive caveat material; some measured-detail sentences could be tightened without losing meaning.

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

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

Given an output schema exists, the description need not explain return values, and it covers the important behavioral complexity: missing bridge commands, verification status, warp_mode hypothesis, and invalidation of returned time fields. The main gap is that the parameters themselves are left essentially undocumented.

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

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

The schema has 0% description coverage and the description does not explain 'track' or 'slot' beyond mentioning 'slot' in the filled-slot check. It does not state indexing, coordinate meaning, valid ranges, or how the clip is addressed. For two unannotated integer parameters, more parameter guidance is needed.

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

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

Opens with a precise verb plus resource: 'Read one Session clip's properties' and lists the property groups. It also distinguishes itself from siblings by stating that notes and automation are not properties and routing those to read_clip_notes and read_automation.

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 names alternatives ('read_clip_notes', 'read_automation') and states when they should be used instead. It also gives a direct after-write guideline: call this again after any write to 'warping' rather than reusing prior results.

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

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

The genuine get_devices content is highly transparent: it explains the configure_needed flag, why a one-parameter third-party plug-in signals an unconfigured device, that the probe only settles one-vs-many, that order can change, and that the call lives on the Song. With no annotations, however, the description carries the full burden, and the appended paragraph describing instrument replacement and non-recoverable loss misattributes destructive behavior to this listing call.

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 useful content is front-loaded in a clean first sentence, but the description then drifts into a move_device tangent, a garbled measured fragment, and a loading-order paragraph that appears to belong to load_device. Length without coherent structure makes the agent's parse more expensive, not less.

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?

An output schema exists, so return-value details need not be spelled out, and the core configure_needed semantics are covered thoroughly. Still, kind is never documented, edge cases like a missing track are absent, and the off-topic load_device content adds confusion rather than completeness.

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 was expected to compensate, but it never explains the kind parameter (default track) or how to address the track. The only parameter-related hint is 'a track's device chain', which adds nothing beyond the schema's track integer property.

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

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

The first sentence states a specific verb and resource: it lists a track's device chain with names, class names, on/off, and parameter counts. It also distinguishes itself from describe by pointing to it for the full parameter list. However, the trailing paragraphs about move_device and loading order dilute the core purpose and could be mistaken for this tool's own responsibilities.

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 one explicit routing rule: call describe with with_parameters=True for the full parameter list, and it mentions lom_call for song.move_device. But it never says when get_devices is preferable to get_track or describe, and the final paragraph about loading order reads as advice for load_device, which is misleading in this context.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It adds useful context: measured round-trip latency (~450 ms), group track arm state returning null, and a fallback probing strategy when Live reports zero tracks. It does not explicitly state read-only behavior, but 'Survey' strongly implies non-mutating intent.

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

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

The description is well-organized into Args, Returns, and Note sections. Every sentence provides useful information: parameter meaning, return shape, performance characteristic, an edge case, and a fallback behavior. No filler or redundancy.

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

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

Even without annotations, the description covers the key behavioral details an agent needs: what the tool returns, how each parameter affects the call, a known edge case, and latency/fallback caveats. An output schema exists, so the return dictionary structure does not need to be spelled out here. This is sufficient for an agent to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must fully document parameters, and it does. It explains clips as 'Sweep Session slots for active clips', devices as including device chains per track, and max_scenes as the cap on scenes probed. This adds genuine meaning beyond the bare boolean/integer 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 uses a specific verb ('Survey') with a clear resource ('the running set') and enumerates the components covered: script handshake, song fields, tracks, clips, devices. This makes it easy to distinguish from targeted siblings like get_track, get_clip, and get_devices.

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

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

The description makes the usage context clear: call this when you need a session-wide snapshot including tracks, clips, devices, and script handshake state. It does not explicitly name alternatives or state when not to use it, but the whole-session scope is evident from the first sentence and the Returns summary.

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

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

With no annotations, the description carries the full behavioral burden and does so excellently. It discloses non-linear volume/panning scale, dB display behavior, the guard for reading arm only when can_be_armed allows it, the null result when not applicable, and the index-probing batch strategy for device names and clip slots. This is rich, measured context beyond what any schema could convey.

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

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

The description is front-loaded with a one-sentence purpose, then uses short labeled paragraphs for arguments and behavior caveats. Every sentence adds essential information, and the structure makes the caveats easy to scan without bloating the 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?

Given the tool has an output schema and only two parameters, the description is complete. It covers the main return categories, the special scaling of volume/panning, the arm edge case, and the probing limitation with Live's collections. An agent has everything needed to invoke it correctly and interpret results.

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

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

Schema description coverage is 0%, so the description must fully explain the parameters. It does: track's interpretation changes based on kind, kind accepts track/return/master, and track is ignored for master. It also clarifies nuanced output semantics tied to these parameters, such as arm read restrictions and normalized volume/panning.

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

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

The description begins with a specific verb and resource: 'Read one track's mixer state, flags, device chain, sends and clip slots.' This clearly distinguishes it from sibling tools like get_session, get_clip, and get_devices. The scope is precise and actionable.

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

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

The description gives clear context for when get_track is appropriate: when reading a single track's state, including mixer, flags, devices, sends, and clip slots. It does not explicitly name alternatives or state when not to use it, but the read-only, single-track focus is obvious enough to guide 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?

No annotations are provided, so the description carries the full burden. It clearly discloses that the tool targets the currently selected track rather than an explicit track argument, explains rack/drum rack destination behavior, and notes that instruments replace while effects append. This is valuable behavior not inferable from the 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?

The description is organized with a clear summary, step breakdown, Args list, Returns, and Notes. It is slightly lengthy but every section adds needed behavioral context. The most critical usage information is front-loaded in the first two 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?

Given no annotations, 6 parameters at 0% schema coverage, and an output schema present, the description provides a complete picture: how to search, how to confirm, what the parameters mean, the target-selection side effects, and the return value. An agent has enough to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It explains each parameter's role (query, root, uri, item_path, limit, confirm) in the context of the two-step workflow, giving semantics beyond the bare schema names and defaults. It also clarifies the relationship between uri, item_path, and confirm.

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 has a clear verb+resource: 'Search Live's browser and load a device onto the currently selected track.' It explains a two-step search-then-confirm process, which distinguishes it from generic device operations and sibling tools like get_devices or lom_call.

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

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

The description explains the two-step workflow: first call with confirm=False to search, then call with confirm=True and a uri/item_path to load. It does not explicitly name sibling tools as alternatives, but the workflow guidance is enough for an agent to understand when to use confirm and why.

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

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

With no annotations, the description carries the full burden and does an excellent job: it discloses that Live does not recompute between operations, that reads after transport jumps return stale values, that this specific failure does not raise, and that it produces misleadingly clean results. This is precisely the behavioral context an agent 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?

The description is well-structured with clear Args, Returns, and Note sections. It is longer than average, but the extra detail about the batch stale-read failure mode earns its place because it prevents a subtle incorrect conclusion.

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

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

Given the tool's complexity, the description covers execution semantics, return shape, atomic behavior, and the critical caveat about transport reads inside batches. Combined with the abundant schea parameter docs, 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 description adds meaning beyond the schema by explaining ops as a list of operation dictionaries and clarifying atomic as stopping on first error. The schema covers the details of op, path, args, value, and method, so the high-level summary in the description is sufficient.

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

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

The description clearly states the tool executes multiple raw LOM operations (get, set, call) in a single round trip. This is a specific verb+resource combination that differentiates it from the sibling single-operation tools lom_get, lom_set, and lom_call.

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 indicates this is for batching multiple operations to reduce round trips and explicitly warns that moving transport should be sampled 'one call per position, never inside a batch.' It could name alternatives more explicitly, but the when-not guidance is strong 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?

With no annotations provided, the description carries the behavioral burden. It discloses that the return value is a dictionary reporting execution status and that only allowlisted methods can be invoked, which is useful context. However, it does not mention potential side effects of calling methods, error behavior, or whether calls may mutate the Live session.

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

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

The description is concise, front-loaded with the core purpose, and organized into Args and Returns sections. Every sentence provides useful information without redundancy or 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?

The description covers the essential invocation inputs and return shape, and an output schema exists so return details need not be fully restated. However, for a generic method-calling tool with no annotations and many siblings, it leaves gaps: the allowlist itself is not defined or linked, side-effect risks are unaddressed, and no guidance is given for choosing between lom_call and related batch/get/set tools.

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

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

Schema description coverage is 0%, but the description compensates by explaining each parameter: path is a dotted LOM path, method is an allowlisted method name, and args is an optional list of positionals. This adds meaning beyond the bare schema titles of 'Path', 'Method', and 'Args'.

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

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

The description clearly states the tool invokes an allowlisted method on a Live object, which is a specific verb and resource. It is distinguishable from sibling tools like lom_get, lom_set, and lom_batch by focusing on method invocation, though it does not explicitly name or contrast those alternatives.

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

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

The description implies this tool should be used when a method on a LOM object needs to be called, rather than for reading or writing properties. However, it provides no explicit guidance on when to prefer lom_call over siblings like lom_get, lom_set, or lom_batch, and it does not define what qualifies as 'allowlisted'.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly indicates a read-only introspection operation, explains the effect of the 'depth' parameter on nested collections, and summarizes the return content. It does not mention error behavior or permissions, but 'Introspect' strongly implies non-mutation and the return schema is described adequately.

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

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

The description is compact, front-loaded with the core purpose, and uses a clear Args/Returns structure. Every sentence yields information, and there is no filler or redundant restatement.

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

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

Given the tool's complexity, the description covers the main inputs, the meaning of depth, and the return content; an output schema exists to clarify the exact dictionary structure. The only gaps are usage context and possible error behavior, but for a generic introspection tool the description is largely sufficient.

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

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

Schema description coverage is 0%, so the description must compensate. It does so by defining 'path' as the target LOM path and 'depth' as the traversal depth for nested child collections, with a note on its default. This adds meaning beyond the bare type definitions in the schema, though it lacks examples or syntax details.

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 ('Introspect') and resource ('an object generically by LOM path'), and the Returns section clarifies that it reports class, properties, children, and allowed methods. It is clear about its generic scope, but it does not explicitly distinguish itself from the sibling tool 'describe', which could overlap.

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

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

The description provides no explicit guidance on when to choose this tool over alternatives like 'describe', 'lom_get', or 'lom_call'. The word 'generically' hints at a use case, but there are no exclusions or comparisons, so the agent must infer the appropriate context.

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

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

With no annotations provided, the description must carry the behavioral disclosure burden. It clearly signals a read-only query operation and describes the return shape and the effect of omitting type_name. It does not discuss invalid input behavior, but that is a minor gap for a simple query tool.

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

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

The description is compact and well-structured: a one-sentence summary followed by Args and Returns sections. Every sentence adds useful information with no redundancy or 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 single-optional-parameter query tool with an output schema, the description is complete. It covers the parameter semantics, the default behavior, and the return type. Nothing critical for correct invocation is missing.

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

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

The schema only provides a defaulted string parameter with no description. The tool description fully compensates by explaining the dotted enum name format, giving a concrete example ('Song.Quantization'), and stating the behavior when omitted. This is exactly what an agent needs to invoke it correctly.

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

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

The description states a specific verb ('Query') and resource ('Live enum types'), and mentions the returned data ('member names and integer values'). It is clear about what the tool does, though it does not explicitly differentiate itself from sibling tools like lom_describe.

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

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

The description provides parameter-level guidance ('Omit to list enum types') and the purpose implies use when enum information is needed. However, it does not explicitly state when to prefer this tool over alternatives such as lom_describe or lom_get, leaving tool-selection comparisons 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?

With no annotations, the description carries the full burden. It clearly states this is a read operation and describes the return dictionary. However, it doesn't disclose edge cases like invalid paths, permission requirements, or whether missing properties yield errors or null values.

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

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

The description is compact and front-loaded with the core action, followed by a concise Args/Returns structure. Every sentence contributes without repetition or 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?

Given the tool's simplicity (one parameter, no annotations) and the presence of an output schema, the description covers the essential invocation details and return shape. It lacks usage context versus siblings, but that gap is already scored in usage_guidelines and doesn't undermine basic callability.

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

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

Schema coverage is 0%, so the description must compensate. It does meaningfully explain the single parameter: 'Dotted LOM path starting with 'song', 'app', or 'song.view''. This adds real semantic value beyond the bare 'path' string in the schema, though exact value formats and examples are absent.

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

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

The description states a specific verb ('Read') with a clear resource ('property value by LOM path') and gives a concrete scope ('starting with 'song', 'app', or 'song.view''). This distinguishes it from most siblings by name/mechanism, though it doesn't explicitly contrast with get_track or get_session.

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 provided on when to use this tool versus the sibling getters, describe, or others. The allowed path prefixes imply a read context, but there are no explicit conditions, exclusions, or alternative tool recommendations.

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

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

With no annotations, the description carries the full burden, and it discloses many important behaviors: stale read-back, asynchronous writes, silently ignored unknown properties, collections not being assignable, and object-reference restrictions. However, the repeated out-of-range passages contain an internal inconsistency between 'does not accept an out-of-range value silently' and 'sometimes accepts out-of-range values silently,' which lowers reliability.

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 sentence is usefully front-loaded, but the description is very long and contains three near-identical paragraphs about out-of-range values and read-back. The duplication, contradictory wording, and garbled terms make it bloated and harder 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 complex tool with no annotations and no detailed output schema, the description covers most calling scenarios: scalar writes, object-property writes, routing-type references, collection limitations, stale reads, and failure modes. The main gap is the contradictory out-of-range note, which leaves an agent uncertain about one of the tool's core behavioral guarantees.

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 is the only real documentation for path and value. It explains dotted LOM paths, scalar values versus object reference dicts {'__path__': '...'}, and gives concrete examples such as song.view.selected_track and available_input_routing_types. This far exceeds what the bare input 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?

The description opens with a specific verb and resource: 'Write a property value by LOM path and return verification read-back.' This clearly distinguishes lom_set from siblings like lom_get and lom_call, and names the write-plus-verification behavior without ambiguity.

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

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

The description gives strong context for when to set a scalar property versus an object property, warns that collections cannot be assigned, and explains how object references are resolved through the same mechanism as lom_call. It does not explicitly enumerate alternative tools or state 'use lom_call for method calls,' so it stops short of full exclusion guidance.

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

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

With no annotations provided, the description carries the full burden and does so well: it states the action, the conditional resume behavior, and the expected return. The explanation of continue_playing versus restarting adds useful behavioral nuance.

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

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

The description is compact, front-loaded with the core purpose, and structured into Args and Returns sections. Every sentence contributes useful information without 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?

This is a simple two-parameter tool with an output schema available. The description covers the behavior, parameter semantics, and return status sufficiently. There are no missing prerequisites or edge-case warnings that an agent would need 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, and it does: 'from_beat' is explained as an optional beat-based cue position, and 'continue_playing' is explained as resuming from the current position rather than restarting. This adds real meaning beyond the schema's bare defaults.

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

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

The description opens with a specific verb and resource: 'Start transport playback', and adds a distinct read-back behavior ('read back is_playing status'). This clearly differentiates it from sibling tools like 'stop' and 'arrange'.

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

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

The description clearly implies usage: call it when you need to start transport playback and confirm playback state. It does not explicitly name alternatives or state when not to use it, but the context is clear enough for 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool uses mode='replace' and that it verifies the result, which tells the agent this is a mutating operation. It also explains the strength and quantize_ends behavior. A slight gap is that it doesn't state whether the operation is destructive to undo history or whether it can be applied to empty/session clips, but overall it gives meaningful behavioral detail beyond the 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?

The description is compact and front-loaded with the core action and target, followed by clear parameter explanations. Every sentence earns its place, including the write/verify behavior. Slight verbosity: 'Reads notes, calculates quantized positions, writes back using mode='replace', and verifies the result' could be tightened, but it is still efficient.

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

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

The description covers the core workflow (read, quantize, write, verify), parameter meanings, and return value. An output schema exists, so the return dictionary details are not required. The tool is a mutation that replaces clip notes, and the description makes that clear. Minor gaps: no mention of what happens on invalid track/slot indices or whether the operation preserves note velocity/other note properties, but these are not critical for an agent selecting and invoking the 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 the meaning of grid (with example values 0.25 and 0.5), strength (0.0 no change to 1.0 full snap), and quantize_ends (whether durations are quantized). track and slot are only referred to as 'Track index' and 'Scene/slot index', which matches their schema titles but adds the contextual detail that they are indices into song.tracks and track.clip_slots. This is strong compensation for the missing schema descriptions.

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

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

The description states a specific verb ('Quantize') and resource ('MIDI clip note positions and lengths') with an explicit target ('to a specified beat grid'), and it distinguishes itself from related editing tools like transpose_clip and write_clip_notes by focusing on quantization. The action 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?

The description implies when to use this tool: when a MIDI clip needs note positions/durations snapped to a beat grid. It does not explicitly name alternatives or exclusions, but the sibling context makes the differentiation clear (e.g., read_clip_notes/write_clip_notes for raw note editing). Lacks explicit 'use X instead' guidance, so it does not reach 5.

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

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

With no annotations, the description carries the behavioral disclosure burden. It explains the optional start/end positions, the default behavior of skipping an initial beat 0 guard, the clamping of points to 2-512, and the return shape. It does not mention whether this is a pure read or whether it requires any specific state, but it is clearly a read operation and the return description adds meaningful transparency.

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

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

The description is compact, clearly structured with Args and Returns sections, and front-loads the core purpose. Every sentence adds information. It could be slightly more concise in the Returns line, but it is appropriately sized.

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 an output schema exists (so return values need not be fully detailed) and 6 parameters, the description is largely complete. It covers parameter semantics, defaults, constraints, and return contents. The only minor gap is the exact format of the LOM path and whether any special track/slot indexing conventions apply, but these are not severe given the output schema and sibling context.

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

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

Schema description coverage is 0%, so the description must compensate, and it does. It explains track, slot, parameter, start, end, and points in plain terms, including that start is in clip-local beats and that points is clamped. It could add more detail on the LOM path format for parameter, but it covers all 6 parameters meaningfully.

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 ('Sample') and resource ('envelope curve for a parameter on a Session clip'), clearly distinguishing it from sibling tools like write_automation and clear_automation. Its 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?

The description implies this tool is for reading automation/envelope data from a Session clip, and sibling names make the contrast with write_automation/clear_automation obvious. It does not explicitly state when to prefer it over alternatives such as read_clip_notes or lom_get, but the specific scoping to envelope curves provides clear context.

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

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

With no annotations provided, the description carries the full burden, and it delivers extensively: muted notes are included and marked, times are clip-local beats, time_span is a length not an end beat, and returned notes are sorted by time then pitch. It also documents Live's surprising pitch-first ordering with a dated measured example, which is exactly the kind of behavioral disclosure an agent cannot infer from the 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?

The description is long but structured with Args, Returns, and Note sections, and the core purpose is front-loaded. The extended Live ordering anecdote is verbose but earns its place by documenting a subtle, plausible bug that could silently corrupt musical interpretation.

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 six parameters, no schema descriptions, no annotations, and subtle runtime behavior, the description is complete: every parameter is semantically covered, return contents are summarized, edge cases are disclosed, and the alternative for Live-native ordering is provided. Nothing required to call the tool correctly is missing.

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

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

Schema description coverage is 0%, but the description compensates fully. Each parameter is explained beyond its type: track and slot get index semantics, from_time/time_span get omit behavior and beat units, and count_only/check get precise behavioral meaning including ignored cases.

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 MIDI notes of a Session clip, query a specific window, or count notes.' It clearly distinguishes this from sibling tools like write_clip_notes and read_automation, and even names get_notes_extended when contrasting ordering behavior.

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

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

The description explains when windowing and counting are appropriate ('no way to ask a small question'), clarifies the semantics of check with and without a window or count_only, and explicitly directs users to get_notes_extended via lom_call when Live's native note order is desired. This gives an agent concrete decision rules rather than leaving usage 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?

With no annotations, the description carries the full burden of behavioral disclosure. It states the core side effect (moving the playhead) and mentions the return value includes a write confirmation and read-back time, which adds transparency beyond just 'set'. However, it does not disclose whether the operation affects playback state, whether fractional beats are accepted, or what happens if the target beat 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?

The description is concise and well structured: an action sentence followed by clearly labeled Args and Returns sections. Every sentence contributes meaning, with no repetition or filler. The core behavior is front-loaded.

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

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

For a simple one-parameter tool with an output schema, the description is largely complete. It explains the input semantics and the type of return value, and the output schema covers the return structure. It lacks only optional behavioral context such as bounds or playback interaction, which is a minor gap for this tool's complexity.

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

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

Schema description coverage is 0%, so the parameter explanation in the description is essential. The description defines 'at_beat' as 'Target song time in beats from timeline start', giving the unit (beats), the reference point (timeline start), and the intended meaning. This fully compensates for the bare schema property name 'At Beat'.

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

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

The description clearly states the action: move the Arrangement playhead to a beat position and return a read-back position. It names a specific resource and operation, so an agent understands the tool's purpose. However, it does not explicitly differentiate it from sibling tools like 'arrange' or 'set_locator', which could overlap in function.

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

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

The description explains what the tool does but gives no guidance on when to use it versus alternatives. Sibling tools such as 'set_locator', 'arrange', and 'set_loop' exist, but no conditions, exclusions, or preferred scenarios are provided. An agent must infer usage context from the name alone.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden, and it delivers. It clearly states that the operation toggles via song.set_or_delete_cue, can either add or delete a locator, requires confirmation, and reports current positions when confirmation fails. This is unusually transparent for a potentially destructive operation.

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

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

The description is compact and well-structured: the core action appears first, followed by the critical confirmation caveat, then parameter details and return behavior. Every sentence adds useful information and there is no filler or redundancy.

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

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

Given the tool's moderate complexity and the presence of an output schema, the description covers the essential ground: what the tool does, its toggling behavior, the confirmation requirement, argument semantics, and return format. The only minor gap is explicit sibling-tool differentiation, but the operation is self-contained and well-specified enough 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, and it does. Each parameter receives an explanatory line: at_beat is a timeline position in beats, name is optional for the new locator, and confirm is a required flag for execution. The explanations are correct but somewhat brief; for example, the description could clarify whether at_beat accepts fractional values or how missing names behave, so it is not a perfect 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?

The description clearly states the tool's verb and resource: 'Place or remove an Arrangement cue locator.' It also explains the underlying toggle behavior, so the purpose is unambiguous. It does not explicitly distinguish itself from sibling tools, but the operation is specific enough that an agent can understand what it does.

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

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

The description explains the confirmation semantics ('Requires confirm=True') and what happens when confirm=False, which guides correct invocation. It does not, however, discuss when to use this tool versus alternatives such as set_arrangement_time or other arrangement-related tools. Usage context for the tool itself is implied rather than explicitly contrasted with siblings.

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

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

No annotations are supplied, so the description must disclose side effects. It does state that it returns a dictionary with 'write status and before/after verification values,' confirming the operation persists a change and self-reports results. However, it does not mention failure conditions, constraints, reversibility, or what happens if the loop is currently disabled, so it only partially carries the burden.

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

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

The description is compact and well-organized into purpose, args, and returns sections. Each sentence contributes either a parameter definition or the response contract, with no filler or repetition. The main clause is front-loaded and immediately reveals the tool's role.

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

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

For a simple optional-parameter setter, the description covers the core action, parameter semantics, and the verification-style return contract, and an output schema exists to fill in structured details. It does not address when the loop brace applies during playback or how enabled interacts with start and length, leaving a modest gap for an agent choosing among many set_* siblings.

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 property definitions contain no descriptive text. The description compensates by explaining each argument: enabled is a boolean state, start and length are in beats, and all are optional. It stops short of specifying constraints such as non-negative values or the interaction between enabled and start/length, but the added semantic detail is material.

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 ('Configure') tied to a precise resource ('Arrangement loop brace parameters') and enumerates the three settings. This clearly identifies what the tool does and helps distinguish it from siblings like set_tempo or set_mix, though it does not explicitly compare with set_arrangement_time or arrange.

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 provided on when to use this tool versus related siblings such as set_arrangement_time, arrange, or set_locator. The description implies the loop-brace context by naming it, but offers no conditions, exclusions, or alternative directions.

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

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

With no annotations, the description carries the disclosure burden and does a solid job: it notes mute/solo are unsupported on master, track is ignored for master, volume uses normalized scaling with a 0 dB reference, and the return includes before/after verification readings. It does not disclose failure behavior or atomicity, but the essentials are 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?

The description is compact yet information-dense: one purpose sentence, a complete parameter list, and a brief returns statement. Every line earns its place, and the most important scoping fact ('single round trip') is front-loaded.

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

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

An output schema exists, so the description correctly avoids re-explaining return structure while still noting the verification nature of the response. All seven parameters, edge cases, and normalization conventions are covered. For a 7-parameter tool with zero annotation coverage, 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 fully compensates by defining every parameter: track indexing, volume normalization, pan range, sends keying, mute/solo applicability, and kind values. This is exactly the semantic enrichment an agent needs beyond bare schema types.

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 'Set mixer parameters (volume, pan, sends, mute, solo) in a single round trip,' giving a specific verb, resource, and named mixer dimensions. It clearly distinguishes itself from siblings like lom_set or set_parameter by framing this as an aggregate mixer setter.

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 conveys the primary use case: updating multiple mixer parameters efficiently in one call. It implies when this tool is appropriate through the 'single round trip' phrasing, but it does not explicitly name alternatives or state when not to use it. The master-track caveats are more parameter semantics than usage 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?

With no annotations, the description carries full burden and excels. It discloses that parameter values are normalized, not displayed units; that the curve from 0..1 is nonlinear and device-specific, illustrated with a concrete example; that quantization can cause read-back to differ; and that such discrepancies are reported as clamps. It also states the return format. These are precisely the kind of behavioral facts an agent needs to avoid silent mistakes.

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

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

The description is long but every sentence earns its place. It is structured with clear sections: purpose, args, returns, and a note. The note's density is justified because silent factor-of-30 errors and quantization clamps are critical for correct use. No filler or redundant repetition exists.

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

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

Given the tool's complexity (5 parameters, normalization, nonlinear mapping, quantization, no annotations) the description is remarkably complete. It covers parameter addressing, kind handling, return content, precondition to check min/max, nonlinear curve caveat, and quantization behavior. An agent has everything needed to select and invoke the tool correctly.

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

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

Schema description coverage is0%, so the description must compensate — and it does. It explains each parameter: track is interpreted in song. tracks or song.return_tracks and ignored for master; device is an index within the chain; parameter is a string index or glob; value is target value; kind accepts 'track', 'return', or 'master'. This adds semantic depth far beyond the bare schema types.

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

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

The description opens with a specific verb and resource: 'Set a device parameter by numeric index or name/glob and verify read-back.' This clearly distinguishes it from siblings like lom_set (generic LOM setter) and set_mix (mixer). The method of addressing parameters is also explicit, leaving no ambiguity about the tool's function.

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

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

The description gives explicit guidance on how to use the tool: how to specify track, device, parameter, value, and kind, including the special case of master. It also advises using 'describe' to read min/max instead of assuming a range. However, it does not explicitly state when to prefer this tool over alternatives like lom_set or set_mix, or when not to use it. That keeps it one step below a fully explicit usage guidance.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose that the operation writes and reads back the tempo, and mentions catalog validation with a numeric range. However, it doesn't discuss side effects, persistence, reversibility, or any session/context requirements.

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

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

The description is compact and well-structured: a direct summary sentence, then an Args block, then a Returns block. Every sentence adds useful information 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?

For a one-parameter mutation tool with an output schema present, the description covers the action, the parameter's meaning and range, and the return shape. It could be more complete by noting whether the tempo applies globally, to a session, or to an arrangement, but the core invocation information is sufficient.

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

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

Schema description coverage is 0%, so the description must compensate. The Args section fully explains the single parameter: units (BPM), meaning (target tempo), and validated range (20.0 to 999.0). This goes well beyond the bare number type in the schema.

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

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

The description clearly identifies the action ('Set') and the resource ('song tempo in BPM'), and adds the read-back behavior. It doesn't explicitly distinguish from siblings like set_parameter, but the tempo-specific scope makes the tool's purpose unambiguous.

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

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

No guidance is given about when to use this tool rather than related tools such as set_mix or set_parameter. The usage is only implied through the tool name and short description, not explicitly stated with conditions or alternatives.

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

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

With no annotations, the description carries the disclosure burden and mostly meets it: it states the transport stop, optional clip stopping via song.stop_all_clips, the quantization effect, and the returned status dictionary. It does not expand on what 'adheres to global launch quantization' means in timing terms, but the main side effects are visible.

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

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

The description is compact and front-loaded, with a clear Args/Returns structure. Every sentence earns its place and no boilerplate is included.

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-optional-boolean stop tool with an output schema, the description covers the core behavior, both parameters, and the return contract. The only mild gap, explicit alternative routing, is already reflected in usage guidance.

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 explain both parameters, and it does: clips is tied to song.stop_all_clips, and quantized is tied to global launch quantization. The Args section adds behavioral meaning that the bare boolean schema lacks.

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

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

The description opens with a specific verb and resource: 'Stop transport playback' and clearly marks the optional Session-clip behavior. This is unmistakably distinct from sibling tools such as play and make_clip.

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 intended use is implied by the verb ('Stop transport playback'), but the description never explicitly says when to prefer this tool over alternatives or when not to use it. It offers no direct routing to sibling tools such as play or get_session.

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

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

With no annotations, the description carries the behavioral disclosure burden. It provides concrete behavior: MIDI notes are transposed, audio uses pitch_coarse, out-of-range notes can error/clamp/drop, and the return value is a dict. It adds a measured version-specific detail for Live 12.4.5, but doesn't explicitly mention in-place mutation or side effects beyond the transposition itself.

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

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

The description is well-structured: a one-line summary, a concise Args block, a Returns line, and a short measured note. Every section earns its place and the core purpose is front-loaded without unnecessary elaboration.

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

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

For a tool with no annotations, no schema param descriptions, but an output schema, the description covers the input semantics, return type, and an implementation constraint. Minor gaps remain, such as what happens if audio semitones exceed the -48..48 pitch_coarse range, but overall an agent can invoke the tool confidently.

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

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

Schema description coverage is 0%, so the description must fully document parameters. It does: track is an index into song.tracks, slot into track.clip_slots, semitones can be positive or negative, and out_of_range lists the three allowed actions. This is exactly the meaning an agent needs beyond the bare schema names.

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

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

The description uses a specific verb ('Transpose') and resource ('clip'), and clearly scopes the operation to MIDI clips via note pitch and audio clips via pitch_coarse. This distinguishes it from sibling tools like quantize_clip or write_clip_notes without ambiguity.

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

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

It clearly states what the tool operates on (MIDI or audio clips) and how transposition is performed, giving an agent solid context for invocation. It does not explicitly name alternatives or list when-not-to-use conditions, but no transpose sibling exists among the provided tools, so this is still clear enough.

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

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

No annotations are provided, so the description carries full behavioral burden. It discloses destructive behavior via clear_first, the verify/read-back comparison mechanism, and the shape of the returned dictionary. This goes well beyond a bare 'write' statement, though it doesn't discuss failure modes or permission requirements.

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

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

The purpose is front-loaded, and the remaining content is organized into Args, Returns, and Note sections. Every sentence adds practical value, including the workflow note about arrangement, with no filler or redundancy.

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

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

For a 9-parameter tool with an output schema, the description documents all parameters, summarizes the return dictionary, and explains the post-write arrangement workflow. There is no meaningful gap that would prevent an agent from calling it correctly.

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

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

Schema property descriptions cover 0%, so the description must carry parameter meaning, and it does. The Args block defines track/slot indices, parameter as a LOM path with an example, points format with units, interpolation options, exponent semantics, resolution units/default, and clear_first/verify behavior. This fully compensates for the empty schema descriptions.

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

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

The first sentence says exactly what it does: 'Write an automation envelope curve into a Session clip and verify read-back.' This names a specific verb, resource, and target, and the verify-read-back behavior distinguishes it from writing clip notes or setting a single parameter.

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

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

The description gives clear workflow context: automation envelopes can be written directly to Session clips, and the note advises arranging afterward to transfer automation to the Arrangement timeline. It doesn't explicitly name alternative tools like set_parameter or read_automation, but the intended use case is clearly implied.

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

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

With no annotations, the description carries the full burden, and it delivers: it discloses remove-then-write semantics, the silent-doubling risk with append, tolerance-based verification, handling of note_id and unknown keys, and measured floating-point deviations in times and durations. It even explains why equality testing should never be used. This is exceptionally transparent.

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

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

Although long, the description is tightly structured: a one-line summary, an Args block, Returns, and a Note section. Every paragraph addresses a real failure mode or clarification an agent would need before calling the tool. The detailed precision measurements may be verbose, but they directly support the warning never to test note times for equality.

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 annotations, the description is complete: it covers replacement vs. append behavior, clearing, verification semantics, key validation, round-tripping from read_clip_notes, time units, and numeric precision. An agent has everything needed to call this tool correctly and interpret its results.

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

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

Schema description coverage is 0%, so the description must explain parameters, and it does thoroughly: track and slot indices, notes as dictionaries with required and optional keys, mode values, and verify's read-back diff behavior. It adds meaning well beyond bare parameter names, including the clip-local beat convention and which keys are tolerated versus refused.

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

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

The opening sentence states a specific verb and resource: 'Write MIDI notes into a Session clip.' It also immediately distinguishes default behavior ('Replaces notes by default') from the sibling read tool. No ambiguity remains about what this tool is for.

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

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

The description gives explicit mode guidance: use 'replace' by default, 'ask for append by name when adding is the intent,' and notes that an empty list with 'replace' clears the clip. It also warns that Live's own set_notes appends, explaining why the default replacement behavior matters. This is actionable guidance for choosing behavior within the tool.

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