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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Beyond the destructiveHint annotation, the description warns that Live will overwrite edits from memory on next save, that confirm=False performs a dry run, that ambiguous expressions are refused, and that index counts expression matches rather than project tracks. It also discloses that a backup is written first. These are significant behavioral facts an agent needs before calling a file-mutating tool.

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

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

The description is front-loaded with the core purpose and confirm requirement, and the paragraphs are structured by operation. However, it is quite long and includes tangential material such as the 174-project corpus statistics and the sidechain wiring median, which do not help an agent invoke the tool correctly. The 'use lom_set for the open set' guidance is also repeated, adding 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 complexity, 14 parameters, and destructive nature, the description is remarkably complete: it covers the return shape, operation-specific behavior, dry-run semantics, backup/restore flow, expression sourcing, Live-process caveats, and escape hatches to sibling tools. An agent has enough context to call this tool safely and correctly.

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

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

The input schema already documents all 14 parameters with 100% coverage, so the baseline is 3. The description adds value beyond the schema by explaining which parameters each operation reads, clarifying that index counts match occurrences rather than tracks, and showing where expressions come from via als_read. This is useful semantic context, though some of it does overlap with the schema text.

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

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

The description opens with a specific verb and resource: 'Edit a saved .als project file on disk.' It then enumerates the four supported operations, making the tool's scope immediately clear. It also distinguishes itself from sibling tools by explicitly saying 'for the set open in Live, none of these: use lom_set, set_parameter or set_mix.'

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

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

The description gives explicit selection guidance: sidechain and configure for things LOM cannot do, attribute for anything else in the file, restore for undo, and als_read for generating expressions. It also clearly warns when not to use the tool: when Live holds the target file, use lom_set-family tools instead. This is model guidance for routing an agent to the right tool.

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

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

The description discloses far more than the annotations already provide: device dependency and failure mode, measurement position in the chain, dependence on master fader, peak maxima that only rise, reset semantics, and the important caveat that this proves signal values but never audibility. There is no contradiction with the readOnly/idempotent hints, since reading the analyzer is non-destructive.

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 earns its length: dedicated sections for output meaning, measurement position, and reset behavior are front-loaded after a one-sentence purpose. The bulleted list and bold lead-ins make it scannable, and no sentence is padding.

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

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

For a measurement tool with three parameters and an output schema, the description covers everything necessary: required device, failure path, return-value semantics, placement caveats, reset workflow, and interpretation limits. The presence of the output schema means the 'what comes back' section is supplementary, not required, but it is still richly provided.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema by explaining how peaks integrate since reset, why reset=true is needed for peak measurement, and how window_ms affects only averaged figures while loudness keeps its own EBU windows. This strengthens the agent's understanding of parameter behavior without merely repeating schema text.

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

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

The first line states a specific verb and resource: 'Measure the audio itself' and then enumerates the exact quantities measured (loudness, true peak, stereo phase, band balance). It also names the mechanism (LiveMaestro Analyzer over loopback OSC), which clearly separates it from siblings that read set state such as get_session or lom_get.

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

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

The description gives explicit when-to-use context: it is the only tool requiring the LiveMaestro device, reports device_not_found with loading steps when absent, and every other tool works without it. It also gives a precise procedure for measuring peaks: call with reset=true, let material pass, then call again. This is actionable guidance beyond generalities.

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

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

The description goes well beyond the annotations by explaining the copy-not-move semantics, that editing one clip leaves the other alone, that repeated calls add another copy rather than replacing the first, and that the response includes clip counts for verification. This complements the idempotentHint=false annotation with concrete behavioral detail.

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 operation, then adds behavioral nuance, return-value context, and a practical note. Every sentence earns its place; there is 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?

Together with the rich input schema and the presence of an output schema, the description covers the operation, its non-idempotent behavior, prerequisites via create_clip and write_clip_notes, and a verification strategy using the returned clip count. Nothing critical is missing for correct invocation.

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

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

Schema coverage is 100% and each parameter already has a clear description. The tool description reinforces at_beat and to_track indirectly but adds no new parameter-level meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a precise operation: 'Copy a Session clip onto the Arrangement timeline at a beat position.' It immediately clarifies this is a copy, not a move, and explains its role in turning Session ideas into arrangement material, distinguishing it from related clip tools like create_clip and write_clip_notes.

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

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

The description gives clear when-to-use context: to bring a Session clip into the Arrangement timeline and to get write_automation output there. It also provides a workflow with create_clip, write_clip_notes, set_arrangement_time, and play. It does not explicitly name alternatives or when-not-to-use conditions, so it misses the top bar by a small margin.

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

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

Annotations already mark destructiveHint=true, but the description adds substantial behavioral context: confirm=True is required for actual deletion, confirm=False is a dry run, a cleared envelope falls back to the outside-clip value rather than the first breakpoint, and the dry run's sampling can miss narrow features. This goes well beyond the annotation flags.

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

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

The description is well-organized with Returns and Note sections, but it repeats 'Requires confirm=True' verbatim in consecutive paragraphs, which is avoidable waste. The remaining detail is dense but mostly necessary, so it is more verbose than ideal.

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

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

For a destructive tool with 5 parameters, the description covers the action, prerequisites, dry-run semantics, return shape, irreversibility, sampling limitations, and alternatives. The presence of an output schema means the return value does not need further elaboration, so nothing important is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful parameter behavior: it explains the interaction between parameter and all_envelopes, clarifies what the confirm flag does, and warns about the difference between one named parameter versus whole-clip has_envelopes reporting. This supplements the schema without repeating it.

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

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

The description opens with a specific verb and resource: 'Delete automation envelopes on a Session clip.' It clearly distinguishes this from sibling tools like write_automation and read_automation by framing the action as removal, not modification or inspection.

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 routing: 'To change a curve rather than remove it, write_automation with clear_first=True... This tool is for leaving the parameter unautomated.' It also advises sampling with read_automation before destructive clearing and using als_read for exact breakpoints, so the agent knows when to pick 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?

The description discloses behaviors beyond the annotations: occupied slots are refused rather than overwritten, the clip arrives empty, and the return value includes creation status, clip path, and read-back length. This meaningfully informs an agent about side effects and failure mode, and it is consistent with annotations.

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

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

The description is front-loaded with the core purpose, then organized into useful Returns and Note sections. It is somewhat detailed, but every paragraph adds value: type restriction, alternative call, return summary, occupied-slot behavior, and next-step workflow.

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

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

The description covers the tool's purpose, target type, alternative path, safety behavior, return shape, and follow-up workflow. Combined with a rich input schema and output schema, an agent has everything needed to decide when and how to invoke this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds important parameter context not in the schema: the track must be a MIDI track, and the slot on an audio track calls a different method. This goes beyond what the input schema conveys.

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

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

The description states a specific verb and resource: 'Create an empty MIDI clip of a given length in a Session slot.' It also distinguishes this from the audio-slot equivalent by explicitly naming lom_call with method='create_audio_clip', making the tool's scope and type constraint clear.

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

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

The description gives explicit when-to-use guidance: use this for MIDI tracks only, and use a different lom_call for audio slots. It also provides workflow direction ('Fill it with write_clip_notes... arrange'), and tells the agent to call delete_clip first when replacing a clip.

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

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

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

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

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

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

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

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

Given the tool's complexity, the 100% schema coverage, and the presence of an output schema, the description is complete. It explains the return dictionary contents, the critical index-shifting behavior, and the necessary follow-up steps. An agent has everything needed to invoke and interpret the result correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by clarifying the semantic implications of index values ('Append with -1... only value that leaves existing track indices alone'), reinforcing that the resolved index from the response should be used, and noting the return-track limitation of name/index. This surpasses baseline without fully re-explaining each parameter.

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

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

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

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

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

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

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

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

The description substantially expands on the destructiveHint annotation by explaining exactly what is removed, that confirm=True is required, that confirm=False changes nothing and returns a loss report, that slot indices do not shift, and that clips already arranged survive. These are meaningful behavioral disclosures beyond what annotations alone convey.

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

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

The description is well-structured with a concise opening, a clear confirm/return section, and a note section for important caveats. Every sentence earns its place; the text is thorough without being bloated, and the most important behavioral facts are 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 destructive tool, the description covers the key operational questions: what gets deleted, what must be passed to actually delete, what happens without confirmation, whether indices shift, how it differs from the main alternative, and how it interacts with arrangement copies. Given the annotations and output schema already exist, nothing critical is missing.

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

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

The input schema already provides full descriptions for all three parameters, including the confirm parameter's true/false behavior. The description restates the confirm requirement but adds no new parameter-level meaning beyond the schema. This matches the baseline expected when schema coverage is 100%.

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 the clip in a Session slot, its notes and envelopes with it.' It clearly distinguishes this from related operations by explaining that emptying a clip is not the same as deleting it, and by contrasting with write_clip_notes. This leaves no ambiguity about what the tool does or how it differs from its siblings.

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

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

The description explicitly tells the agent when to prefer an alternative: 'Prefer write_clip_notes with an empty list and mode="replace" where the slot should stay filled.' It also clarifies the confirm=False flow as a dry-run/look-before-committing option. This is concrete, actionable routing guidance rather than vague context.

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

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

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

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

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

The description is long (~220 words) but front-loaded with the core action and confirm semantics, then organized into Returns and a structured Note with distinct points. Every section addresses a real failure mode, but the Returns line is mildly redundant with the confirm paragraph and the track-naming rationale could be tightened. Slightly verbose, never wasteful.

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

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

For a destructive, non-idempotent mutation tool with 4 parameters, this is complete: it covers the danger gate (confirm), post-call hazard (index shift) and its mitigation, equivalent alternatives, cross-tool addressing consistency (get_devices), and a parameter edge case (master ignores track). The output schema exists, so return details need no further elaboration.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine behavioral nuance beyond the schema: that 'track' is not read at all when kind is master, that kind addresses return/main chains the same way get_devices does, and how confirm=False frames the report as a look-before-committing preview. This exceeds the baseline.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description states a specific verb and resource ('Delete a track with everything on it') and clarifies the full scope: devices, Session clips, and Arrangement clips are all removed. It distinguishes itself from sibling tools by naming delete_clip and delete_device as narrower alternatives.

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

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

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

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

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

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

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

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

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

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

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

Given the tool's complexity, the output schema, and 100% schema parameter coverage, the description is complete. It covers what the tool returns, when to use it over its main sibling, what edge cases exist, and how to continue the workflow with lom_call and set_parameter. Nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful value by explaining the behavioral difference of with_parameters, its role in diagnosing unconfigured plug-ins, and the unmeasured cost of deep depth descents. This is more than the schema alone provides, though the path parameter gains little beyond its already thorough schema description.

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

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

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

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

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

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

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

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

Annotations declare readOnly=true, idempotent=true, destructive=false, and the description reinforces and extends this with genuinely additive context: token cost per call, the fact that it reads the catalog only and therefore 'nothing here proves anything about the set that is open,' the behavior of the writes field for read-only parameter objects, and the exact semantics of all six route types. There is no contradiction between the annotations and the described behavior.

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

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

The description is long (~350 words) but well-structured: purpose first, then Returns summary, then a route-by-route Note. Every section earns its place — the device_parameter examples (filter cutoff, resonance, attack) and the arrangement_clip twin explanation prevent real ambiguity. It could be tightened slightly, but the complexity of six route types justifies the length.

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

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

For a tool with four parameters, six route types, and an output schema, the description is complete: it explains the output dictionary's top-level contents, every route's meaning, the scopes field, the writes field, the token cost, and the catalog-only limitation. Because an output schema exists, the description need not enumerate exact return keys, and the semantic meaning of each route — exactly what a schema cannot convey — is fully covered.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters (query, area, limit, access) with meaningful examples. The description adds modest complementary value — the writes field explanation connects to the access param's 'use set to filter out read-only parameter objects,' and the 1.5k-token figure ties to the limit default of 6 — but these are indirect return-value relationships rather than parameter-level guidance. Baseline 3 is appropriate.

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

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

The first sentence states a specific verb+resource pair: 'Find the mechanism that serves an intent, and the catalog rows when rows serve it.' This clearly distinguishes the tool as a discovery/routing lookup rather than a direct accessor like get_track, lom_get, or set_parameter. The route taxonomy (catalog_row, device_parameter, blocked, intent_tool, unresolved) further sharpens what the tool produces.

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

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

The description gives clear context for when to use the tool: 'This exists so that finding a path costs about 1.5k tokens instead of reading the whole catalog,' and it scopes the tool as catalog-only ('It does not touch Live'). The route descriptions function as conditional usage guidance: intent_tool tells the caller a sibling tool is the better route, and blocked tells the caller to do something in Live instead. However, it never explicitly names alternatives ('use lom_get when...'), so it falls one notch short of a 5.

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

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

Annotations already mark this read-only and idempotent, but the description adds material behaviors: slot-empty handling returns has_clip:false instead of failing, and property reads are guarded by a filled-slot check. It also discloses verification status of returned fields and the time-field invalidation caveat after warping writes, which annotations could not convey. No contradiction with readOnlyHint=true exists because the description describes an external write, not the tool writing.

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 the core purpose is front-loaded in the first sentence, followed by clearly separated return and note sections. While every section is relevant, the detailed empirical warping example and verification history add notable length and could be trimmed without losing the essential warning. It remains well-structured.

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

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

The description covers prerequisite behavior (filled slot check), exact return semantics including empty-slot handling, adjacent data routes, and the only significant stale-data hazard with a concrete directive to re-call. Given the tool's moderate complexity and the presence of an output schema, nothing needed for correct agent 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 input schema already documents both track and slot parameters with clear semantics and 100% coverage, including the 0-based indexing and slot-as-scene meaning. The description adds no new parameter-level detail, so it stands at the schema-covered baseline. It references 'slot' in the filled-check context but not in a way that deepens parameter understanding.

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

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

The first sentence specifies a concrete read operation on a Session clip and lists the exact property groups returned. It also names the sibling tools for adjacent data (read_clip_notes, read_automation), directly distinguishing this tool from those. This makes the tool's scope unambiguous.

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

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

It explicitly says to use read_clip_notes for notes and read_automation for automation, which are the closest alternatives, and clarifies what get_clip is not responsible for. It also advises re-calling after a warp write because cached property values may be stale. This gives an agent clear selection and invocation guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description's 'Reads the chain and changes nothing in it' aligns with them. Beyond annotations it adds substantial behavior: the empty-chain case returns device_count: 0 rather than an error, the configure_needed flag semantics for third-party plug-ins, the parameter_count_at_least sentinel when the probe cannot settle, and the note that only Live's GUI lifts the configuration limitation.

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 one-sentence purpose followed by the one-line safety statement, and uses clear Returns/Note sections. It is long, but the Note's content about configure_needed and parameter_count_at_least is substantive and necessary for correct interpretation. The Returns section slightly overlaps with the existing output schema, which keeps it from a perfect 5.

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

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

For a two-parameter read-only tool with 100% schema coverage, an output schema, and safety annotations, the description covers everything an agent needs: purpose, non-mutating behavior, return-shape narrative, edge case handling, the configure_needed caveat, and routing to sibling tools. No critical gap remains for correct invocation.

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

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

Schema description coverage is 100%: both 'kind' (with its enum of track/return/master) and 'track' (index in song.tracks counted from 0) are fully documented in the schema. The description adds no parameter-specific meaning beyond the schema, which is acceptable per the baseline-3 rule when schema coverage is high.

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 and resource ('List a track's device chain') and enumerates the exact fields returned ('names, class names, on/off, parameter counts'). It differentiates itself from siblings by explicitly stating it counts parameters but does not list them (that is describe's job) and that mixer/sends/clip slots belong to get_track.

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

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

The description gives explicit routing: 'call ``describe`` with ``with_parameters=True``' for parameter details, and 'call get_track instead of adding a second call here' for mixer/sends/clip slots. It also provides sequencing guidance ('Read the parameter count first') and explains that reported device indices are the addressing scheme used by set_parameter, delete_device, and song.move_device, telling the agent exactly when this tool's output is needed.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description goes well beyond this by revealing the 450 ms round-trip cost, the group track 'armed' null quirk, and the index-probing fallback when zero tracks are reported. These are non-obvious behavioral traits that materially affect invocation decisions.

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

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

The description is efficiently structured: a one-line purpose, a short invocation-placement paragraph, a return summary, and a note consolidating the most important behavioral caveats. Every sentence adds operational value, and the most critical 'call first' guidance is front-loaded.

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

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

For a read-only session-survey tool with an output schema and rich schema-level parameter descriptions, the description covers everything an agent needs: when to call it, why it is expensive, what it returns at a high level, how to narrow afterwards, and two important quirks (group track arm state and zero-track fallback). Nothing essential is missing.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description goes far beyond the annotations by detailing exactly what is destructive: instrument loads replace and silently discard the previous instrument, track names go stale after instrument loads, and rapid plug-in loads can crash Live. It also discloses measured failure modes and the need to verify results with get_devices, adding rich behavioral context.

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

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

The description is lengthy but well-structured and front-loaded: the core two-step usage appears immediately, followed by warnings and edge cases in clear sections. Some details could be trimmed or moved to a separate troubleshooting note, but for a destructive tool with this many failure modes the length is largely justified.

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

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

For a complex destructive tool with six parameters, multiple failure modes, and a two-step protocol, the description is near-exhaustive. It covers prerequisites, selection behavior, return semantics, alternatives, and verification steps, leaving an agent with everything needed to call the tool safely 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?

Even though the input schema already covers all parameters, the description adds critical operational semantics: item_path is preferred over uri because uri resolution can run out of walk budget, root narrows the second walk after a failed uri, and query is required for the search step but can be dropped for the load step. This meaningfully extends what the schema alone 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: 'Search Live's browser and load a device onto the currently selected track.' It also clearly distinguishes the tool's two-step behavior from the read-only get_devices and destructive delete_device siblings by stating its precise job.

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 procedural guidance: call with confirm=False first, inspect the selection, then call with confirm=True. It names get_devices as the tool to use before confirming and for reading the chain back, and recommends song.move_device via lom_call instead of reloading for reordering. This is strong when-to-use and when-not-to-use guidance.

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

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

The description transparently explains the atomic parameter's effects: 'True stops at the first error, leaving the operations before it applied and the ones after it untried. False runs every operation and reports each result. Neither rolls anything back.' It also notes the absence of verification, which is a behavioral trait. This does not contradict the annotations.

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

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

The description is moderately verbose and includes a somewhat meandering example about 'Four jumps interleaved with four reads' that does not add meaningful guidance. The core information is present, but it could be tightened without losing clarity.

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 main aspects needed: batching, atomic behavior, no rollback, and preference for dedicated tools. It does not detail the exact return format, but the output schema likely handles that. Given the tool's complexity, the description is largely complete, though slightly lacking in explicit error handling details.

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

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

The schema already covers parameter meanings extensively (100% coverage). The description adds context about 'raw' operations and the lack of rollback, but does not introduce new parameter semantics beyond what the schema and the atomic explanation provide. Thus a strong score but 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 purpose: 'Execute multiple raw LOM operations (get, set, call) in a single round trip.' It also distinguishes itself from sibling tools by advising to prefer dedicated tools for covered functionality, making its role 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 explicitly explains when to use this tool versus alternatives: 'Prefer a dedicated tool for anything it covers. get_session, get_track and get_devices already batch their own reads, and set_mix writes a whole mixer in one trip, each with verification this does not perform.' It also clarifies the atomic flag behavior, giving clear usage direction.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description explicitly says to prefer a dedicated tool wherever one exists, names several such tools, and directs property access to lom_get/lom_set and multiple calls to lom_batch. It also instructs the agent to follow up with a matching read because method calls have no read-back. This is explicit, actionable routing guidance.

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

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

Annotations already mark this as read-only and idempotent. The description adds important behavior beyond that: it reports child collections as counts, warns that device parameters may be misreported as zero due to Live Vector len() issues, clarifies that describe falls back to index probing, and states that listed methods are names, not calls. This is meaningful, non-obvious behavioral context.

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

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

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

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

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

Given the output schema exists, the description does not need to explain return values in full, but it still covers the key behavioral details: what the dictionary contains, how methods are represented, when to prefer another tool, and an important failure mode. For this tool's complexity, nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by warning that raising depth multiplies the work and that the cost is unmeasured, which is not present in the parameter schema. It also reinforces the path semantics with examples already in the schema, but the depth warning is a genuine extra.

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context about Live's internal integer representation, the dual lookup direction, and the conditional return shape based on the type_name parameter.

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

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

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

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

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

The tool is simple with one optional parameter and an output schema. The description covers why the tool exists, when to use it, how to interpret the result, and which sibling handles the adjacent concern. Nothing essential is missing for correct invocation.

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

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

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

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

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

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

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

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

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

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

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

Beyond the readOnly/idempotent/destructive annotations, the description details error semantics (non-song/app/song.view roots refused before contacting Live, Live-rejected paths return ok:false with Live's code), sentinel handling via the 'means' field, and the shape of the return dictionary. This is valuable behavioral context.

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

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

The description is compact and well-organized: purpose, return summary, then a note on edge cases and usage. Each paragraph earns its place with no fluff, and the core purpose is front-loaded.

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

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

For a one-param read tool with strong annotations and a schema, the description covers the practical invocation concerns: path syntax constraints, error responses, catalog meaning, and fallback positioning relative to sibling getters. Nothing essential is missing.

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

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

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

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

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

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

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

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

The description explicitly directs agents to prefer a dedicated getter: 'Reach for a getter first where one exists,' and frames lom_get as the fallback for fields no getter exposes. It names get_session as an example, giving concrete routing guidance.

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

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

Beyond annotations (readOnlyHint: false, idempotentHint: true, destructiveHint: false), the description discloses major behavioral traits: Live rejects out-of-range values loudly, quantized values clamp, writes can apply asynchronously causing stale reads, unknown properties are silently ignored, collections are not assignable, and object-valued properties need special __path__ references. No contradiction with annotations exists.

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

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

The description is long but tightly organized: purpose, sibling routing, return shape, then a sequence of concrete behavior warnings with examples. Each paragraph earns its place by preventing a distinct failure mode. The most actionable guidance is front-loaded.

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

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

Given the tool's complexity, the description is remarkably complete. It covers the return dictionary fields, device-parameter extras, out-of-range behavior, quantized snapping, async writes, silent failures, collection assignment, object-valued properties, and routing-property constraints. With an output schema present and no missing operational guidance, nothing critical is left 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?

Although schema coverage is 100%, the description substantially enriches parameter understanding: it explains the trailing .value convention for mixer controls, the plain scalar forms of value, the {'__path__': ...} dict form for Live-object properties, and the routing-property reference restrictions. These are essential semantics not inferable from the schema alone.

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

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

The description opens with a specific verb and resource: 'Write a property value by LOM path and return verification read-back.' It then names the sibling tools it is not (set_parameter, set_mix, set_tempo, lom_call, lom_batch), making the tool's role as the generic property write 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 explicitly tells the agent when to avoid this tool: prefer set_parameter for a device knob, set_mix for a mixer control, set_tempo for tempo, lom_call for a method, and lom_batch for multiple writes. This is direct routing guidance with no reliance on inference.

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

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

Beyond the annotations, the description discloses important behavioral traits: the read-back proves transport running but not audibility, the transport is left as found, nothing stops it automatically, and a played Session clip can change Arrangement behavior until back_to_arranger is pressed. This substantially exceeds what the annotations already provide.

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

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

The description is organized into clear sections: purpose, return value, and behavioral notes. It is longer than a minimal description, but each paragraph earns its place by conveying non-obvious information. Only minor trimming would be possible without losing value.

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

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

The description is thorough for a transport-control tool with an output schema and annotations. It covers side effects, edge cases, alternative tools, and state transitions, so an agent has enough context to decide when to invoke it and what to expect afterward.

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

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

The schema covers both parameters with full descriptions, so the description does not need to repeat parameter semantics. The description does add context about from_beat by mentioning set_arrangement_time as an alternative way to move the playhead, but that is more usage guidance than parameter semantics. Schema coverage is 100%, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Start transport playback' and read back is_playing. It clearly distinguishes the tool's function from related siblings by naming stop and set_arrangement_time as alternatives, and by describing its return value.

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 routing guidance: 'Use stop to halt, and set_arrangement_time to move the playhead without starting.' It also warns about the Session-clip behavior and the Back to Arrangement button, so the agent knows when this tool is appropriate and what follow-up actions may be needed.

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

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

The description discloses the full behavioral pipeline: reads notes, calculates quantized positions, writes back using mode='replace', and verifies the result. It also warns that quantizing modifies notes in place and is not undoable, adding important safety context beyond the annotations. There is no contradiction with readOnlyHint=false or idempotentHint=true.

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

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

The description is well structured and front-loaded: purpose, process, return value, parameter notes, side-effect warning, and alternatives. Every section earns its place, and the language is tight without redundancy.

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

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

Given the tool's complexity, the description is complete: it explains return contents, irreversible in-place modification, parameter interactions, and alternative tools. Required parameters track and slot are fully covered by the input schema, so nothing necessary 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?

Schema coverage is 100%, so parameters are already documented. The description adds value by explaining parameter interactions: strength scales displacement from 0.0 to 1.0 with partial-use guidance, and quantize_ends behavior is clarified with articulation-preservation context. This goes beyond the schema without needing to repeat basic field meanings.

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: 'Quantize MIDI clip note positions and lengths to a specified beat grid.' It clearly distinguishes itself from siblings by explicitly naming transpose_clip for pitch shifts and write_clip_notes for custom off-grid notes, so an agent can select the right tool without opening schemas.

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

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

The description provides explicit when-to-use guidance and alternatives: use transpose_clip to shift pitch instead of timing, and write_clip_notes for custom or micro-timed off-grid notes. It also instructs the agent to call read_clip_notes first if original unquantized timing may be needed, which is clear prerequisite guidance.

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

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

The description adds substantial behavior beyond the annotations: it evaluates at 'points' positions rather than exposing breakpoints, returns a dictionary with specific contents, and warns that Session-clip automation is invisible in Arrangement clips. This complements the readOnlyHint/idempotentHint annotations without contradicting them.

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

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

The description is front-loaded with the core action and result, then adds only high-value distinctions and caveats. Each paragraph earns its place: sampling semantics, return contents, session/arrangement contrast, and the false-envelope nuance. Nothing is redundant or padded.

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

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

Given the annotations, full schema coverage, and presence of an output schema, the description covers all non-obvious context an agent needs: what the tool returns, how sampling differs from breakpoints, when no envelope exists, and which sibling tools to use instead. It is complete for correct invocation and interpretation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that 'points' controls sampling resolution and that the answer is a sampling rather than the stored breakpoints, but it does not materially extend the already-detailed per-parameter schema descriptions for start, end, track, slot, or parameter.

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

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

The opening sentence states a precise action and resource: 'Sample a clip envelope into a list of values and report what it found.' It also distinguishes itself from breakpoint-based reading by explicitly saying the result is a sampling, and it names als_read as the alternative for breakpoints, making sibling differentiation clear.

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

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

The description explicitly says when not to use it ('an Arrangement clip has none to read'), names the alternative for saved-project breakpoints ('als_read'), and identifies companion mutation tools ('write_automation' and 'clear_automation'). It also clarifies a subtle interpretation trap: a flat result with envelope flag false is not the same as an envelope holding the current value.

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

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

The annotations already indicate a safe read-only operation, and the description adds substantial behavioral detail: muted notes are included with mute:true, time_span is a length not an endpoint, results are sorted by time then pitch, returned data can exceed the tool-result cap, and count_only executes inside Live. This goes far beyond what the annotations or schema convey.

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

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

The description is long but tightly organized with Returns and Note sections, and every paragraph carries load-bearing information about behavior, performance, ordering, or parameter semantics. The core purpose is stated up front, and the detailed caveats are front-loaded where they matter most.

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 six parameters, an output schema, and subtle ordering and windowing behavior, the description is complete. It covers return values, validation behavior, performance constraints, note ordering, and the right way to count notes in large clips, so an agent can select and invoke it correctly without additional probing.

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

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

Even though schema coverage is 100%, the description adds critical semantic nuance: time_span is defined as a duration, count_only transfers only an integer, check is ignored with count_only, and windowed reads validate only the window. The slot and track parameters are already clear from the schema, so the description layers extra meaning where needed.

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

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

The description opens with a specific verb and resource, 'Read MIDI notes of a Session clip', and further distinguishes three modes: full read, windowed query, and note counting. This clearly separates it from write_clip_notes and other siblings while establishing the exact scope of the tool.

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

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

The description gives explicit guidance on when to use count_only for large clips, explains how windowing changes the check behavior, and directs users to get_notes_extended through lom_call when Live's native note order is required. This is strong routing advice with concrete alternatives.

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

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

The description discloses that it writes song.current_song_time, that it moves the playhead without starting playback, and includes a specific caveat about batch reads reporting stale positions. This goes beyond the annotations by explaining side effects and edge cases.

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

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

The description is tight and well-organized: a clear main action, a brief elaboration on the side effect, an alternative guidance, and a note about batching. No redundant 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 simple one-parameter tool, the description covers the action, side effects, alternatives, and a critical batch caveat. It provides enough context for an agent to decide when and how to call it correctly.

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

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

The single parameter 'at_beat' has a thorough schema description covering fractional beats and bar references, fully clarifying its meaning. The tool description also reinforces its purpose by mentioning 'to a 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') and the resource ('Arrangement playhead'), with an additional readback. It also distinguishes this tool from 'play' and 'play with from_beat' by explaining what it does not do (start playback).

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

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

Explicitly tells when to use this tool versus alternatives: 'Use play to begin, or play with from_beat to do both in one call.' The note about lom_batch further advises against using it in batch scenarios, providing clear usage 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 sparse annotations, the description carries the behavioral burden and does so thoroughly. It discloses the non-idempotent toggle, the confirm=True requirement, the confirm=False preview behavior, the return dictionary contents, and the fact that locators do not move the playhead. No contradictions with annotations are present.

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

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

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

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

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

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

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

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

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

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

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

The description opens with a concrete verb and resource: 'Place or remove an Arrangement cue locator.' It immediately distinguishes the tool from related siblings by explaining what it does not do—moving the playhead or marking a region—so an agent can recognize its specific scope.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description explicitly explains the optional-argument behavior, clarifies when not to use it ('no bearing on Session clip looping'), names the alternative (get_clip), and even documents the no-argument read mode as the cheap way to inspect the current brace. This gives an agent clear selection and invocation guidance.

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

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

Annotations declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false; the description adds meaningful context beyond these: master-track mute/solo 'are refused there rather than silently ignored,' 'track is not read at all when kind is master,' values are absolute rather than relative, volume/pan use a non-linear normalised scale ('0.85 is 0 dB (measured)'), and the return dictionary reports before/after values plus Live's dB display. The description is consistent with the annotations, so there is no contradiction.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains normalization, non-linear scaling, the meaning of the value parameter in device-specific terms, and the glob/refusal behavior of the parameter name. This goes beyond what the schema already states without repeating it.

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

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

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

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

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

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

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

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

The description goes far beyond the annotations: it discloses that probes write nothing, only a single final value is written, two round trips occur, endpoints are never probed because they can crash Live, and the returned value is not audibility. This is rich behavioral context and is consistent with readOnlyHint=false, destructiveHint=false, and idempotentHint=true.

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

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

Although long, the description is front-loaded with the essential purpose and return shape, then uses structured paragraphs to explain rationale, safety, edge cases, and alternatives. Every paragraph earns its place and the text is dense with useful information rather than filler.

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

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

For a complex, inverse-search tool with an output schema and 100% parameter documentation, the description covers the critical extra context: why sampling is used, why real-write bisection is dangerous, endpoint crash risk, no-unit refusal, and sibling tool routing. Nothing needed for correct invocation appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds meaningful semantic context on top: target is a display reading, not a normalised value, and unit handling clarifies refusal on mismatched units. It also explains why probes avoid min/max, which informs the parameter boundaries implied by the schema.

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

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

The description opens with a specific verb and resource: 'Set a device parameter by the reading it should show, not by its raw value.' It immediately differentiates the tool from set_parameter by naming it as the inverse, so an agent can recognize which tool to use without opening schemas.

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

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

The description explicitly states when to use this tool versus set_parameter: it exists because there is no invertible formula, and for devices that report no unit it says 'use set_parameter with a normalised value and calibrate by ear once.' It also provides a concrete failure mode of write-based bisection, giving strong situational 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?

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

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

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

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

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

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

For a single-parameter tool with an output schema and annotations present, the description covers everything needed: global scope, return shape, the scene-launch override caveat, and cross-references to sibling tools. No material gap remains for an agent to call it correctly.

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

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

Schema coverage is 100% and the bpm schema description already gives the unit and validation range, so baseline is 3. The description adds value by flagging that BPM is 'a real unit, which makes this tool the exception among the setters,' warning the agent not to send a normalized 0..1 value. This goes beyond what the schema states.

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

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

Opens with a specific verb+resource: 'Set the global song tempo in BPM and read back the stored value.' The description immediately distinguishes scope ('One tempo governs the whole set, Session and Arrangement alike. There is no per-track tempo'), which prevents confusion with per-track setters like set_parameter or set_mix.

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

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

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

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

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

Beyond the annotations, the description discloses the quantized stop timing (clips may lag up to the next grid point), the fact that an immediate read may still show a clip playing, and the envelope side effect that stopping does not restore a parameter to a baseline. These are non-obvious behavioral traits that an agent needs to interpret results correctly, and they do not contradict the annotations.

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

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

The description is compact and well-structured: one opening sentence, a short Returns note, and a focused behavioral note. Each paragraph earns its place; the envelope side effect is not padding and the usage alternatives are integrated naturally.

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 rich input schema for both parameters and the presence of an output schema, the description covers all essential behavioral context: stop scope, quantized timing, return value, resume/rewind alternatives, and the envelope side effect. Nothing an agent needs to invoke 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?

The schema already describes both boolean parameters thoroughly (100% coverage), so the baseline is adequate. The description adds value by explaining the quantized=True behavior in terms of grid timing and the implication for immediate reads, complementing rather than repeating the schema exactly. The clips parameter is only summarized, but the schema carries its detail.

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

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

The opening sentence states a specific verb and resource: 'Stop transport playback, and optionally every playing Session clip.' It clearly distinguishes the action from siblings like play and set_arrangement_time by naming those tools for resume/rewind in the note, so an agent can tell what this tool 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 gives clear context for stopping playback and explains that play should be used to resume and set_arrangement_time(time=0) to rewind. It does not spell out explicit when-not-to-use conditions, but the alternative routing is present and sufficient for this tool.

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

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

The description goes well beyond annotations by explaining relative cumulative behavior on both MIDI and audio paths, the pitch_coarse write mechanism, the bound uncertainty, and the information-loss consequences of clamp/drop. This is rich behavioral context that annotations alone do not provide.

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

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

The description is well-structured with clear sections, front-loads the core behavior, and every sentence earns its place. The guidance about clamps/drops and read-back evidence is dense but directly useful for correct invocation.

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

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

For a tool with this complexity, the description is complete: it covers MIDI vs audio behavior, relative semantics, out_of_range trade-offs, and when to use alternatives. Since an output schema exists, the return-value note is a bonus rather than a requirement.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema, particularly the cumulative relative effect ('calling it twice with 2 moves the clip by 4') and the recoverability guidance tied to out_of_range. This elevates it above the baseline.

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

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

The description opens with a specific verb and resource: 'Transpose a MIDI clip by note pitch or an audio clip via pitch_coarse.' This clearly distinguishes the tool's two target modes and states exactly what it operates on. It also differentiates from write_clip_notes and quantize_clip through explicit contrast.

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

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

The description provides an explicit 'When to use' and 'When NOT to use' section, naming concrete alternatives: write_clip_notes for melody/voicing edits and quantize_clip for timing/groove changes. This gives an agent unambiguous routing guidance.

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

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

With only false-valued annotations, the description carries the full burden of behavioral disclosure, and it excels: it reveals that verification compares stored vs generated curves, that audible output is not guaranteed on disabled devices or muted tracks, that clear_first=False layers points and can create mixed curves, and that playing leaves the parameter at the curve's last value. This is rich, honest, and actionable.

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

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

The description is long but every section earns its place: a one-line summary, a return-value note, and focused warnings about audible verification, retry behavior, and playhead side effects. The most important scoping statement is front-loaded, and the notes are grouped for skimmability.

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 9-parameter tool with side effects and no meaningful annotation context, this description is remarkably complete. It covers purpose, return behavior, alternatives, retry dangers, audibility caveats, and playback side effects, while an output schema exists to handle return-value details.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful behavior around specific parameters: it explains the consequence of clear_first=False in terms of failed retries, and it clarifies the verify read-back semantics by stating the result reports the stored envelope rather than the requested one. This goes beyond the schema's per-parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Write an automation envelope into a Session clip and verify the read-back.' It clearly distinguishes itself from siblings like read_automation and clear_automation by describing the write-and-verify workflow rather than merely restating the tool name.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: it explains that Arrangement envelopes cannot be written directly and must go through a Session clip plus arrange, and it names clear_automation for clearing and read_automation for inspecting before retrying. This is strong routing behavior beyond what the schema or annotations provide.

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

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

With annotations supplying almost no behavioral signal (all false), the description carries the burden and does so thoroughly. It discloses clip-local beat timing, the replace-vs-append semantics with measured evidence, note_id tolerance and key rejection behavior, the absence of defaulting, and floating-point round-trip deviations with a clear warning never to compare for equality.

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 purpose, returns, usage notes, and behavioral warnings front-loaded. It is somewhat verbose in the floating-point precision narrative, which could be trimmed without losing the core warning, but the detail is informative rather than redundant.

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

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

For a mutating tool with five parameters and an output schema, the description covers all essential context: units, mode semantics, note object key handling, verification behavior, and precision pitfalls. An agent has enough information to call 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?

Although schema coverage is 100%, the description adds substantial input-construction guidance: note_id and tolerated keys are dropped, unrecognized keys are refused, pitch/start_time/duration are never defaulted, and the 'pos'/'dur' spelling is explicitly not accepted. This goes well beyond the schema's field-level 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 opening sentence states a specific verb and resource: 'Write MIDI notes into a Session clip.' It clearly differentiates from siblings like read_clip_notes and delete_clip, and the description of replace vs append modes further clarifies what the tool 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 explicitly tells when to use alternatives: read_clip_notes for inspecting before rewriting, quantize_clip for timing, transpose_clip for pitch, and delete_clip for emptying a clip. It also gives a concrete rule for choosing mode='append' when layering notes.

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