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

Annotations already declare destructiveHint=true and openWorldHint=false, so the mutation risk is known. The description adds two real behavioral facts beyond that: the apply is single-shot ("once") and is gated by an operator startup policy that may refuse it. However, it never says what that policy is, what a refusal looks like, whether the plan is consumed on failure, or whether the change is undoable.

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

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

A single front-loaded clause pair with no filler; the verb and the scope arrive immediately. The only weakness is that "operator startup policy" is unexplained jargon occupying a third of the text's information budget.

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

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

This is a destructive, non-read-only operation with no output schema and an undocumented sole parameter, so the description bears the full burden. It leaves unaddressed what apply returns, whether the plan is consumed, what happens on a second call with the same id, and how to recover — all material for a destructive tool.

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

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

Schema coverage is 0% and there is one required parameter, so the description must carry the meaning — and it does partially, making clear that plan_id is an opaque handle to a previously returned preview rather than a user-chosen identifier. It adds nothing about handle lifetime, invalidation after use, or format, so an agent still cannot predict failure modes from the parameter.

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

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

States a specific verb ("Apply") on a specific resource ("a previously returned preview"), which implicitly ties it to the agent_*_preview siblings that produce such previews. An agent can tell this is the commit step rather than a preview, though the description never names the producer tool explicitly and "preview" remains an abstract object.

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?

"once" and "previously returned" imply the prerequisite (a preview must exist first) and hint at single-use semantics, but the description never states when to prefer this over re-running a preview or over applying edits directly via edit_* tools. No explicit exclusions or alternative routing is given.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is partly covered. But the description says the tool will 'save' and the schema exposes a save_path, which is at odds with a read-only hint and is never reconciled. It also never explains the preview contract (does anything persist? what does agent_apply do next?).

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

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

It is short and front-loaded, but it is a fragment with ambiguous slash syntax ('duplication/transforms') rather than a sentence, so brevity comes at the cost of parseability.

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?

A four-parameter, zero-coverage arrangement tool with no output schema needs a real explanation of inputs and the preview/apply workflow. This definition supplies neither, so an agent has essentially nothing to call it correctly with.

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

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

Schema description coverage is 0% across all four parameters, so the description must carry the load and it does not. It name-drops sections, transforms and automation without stating shapes or meaning (what a 'transform' or 'duplication' is), and save_path is not mentioned at all.

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 is a slash-delimited noun list ('sections, duplication/transforms, automation and save') hung off the verb 'Preview' rather than a statement of what the tool actually does. It gives no hint of how it differs from the many other preview siblings (agent_preview, agent_loop_preview, agent_midi_preview, agent_arrange_timeline), so an agent cannot route on it.

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?

There is no when-to-use guidance, no prerequisites, and no named alternative. In a sibling set with agent_preview, agent_apply, agent_loop_preview and agent_arrange_timeline, the definition never says when an arranging preview is the right call versus those.

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 readOnlyHint=true and destructiveHint=false, and the description is consistent with a preview operation. It adds useful context about the max batch size of 32 and inter-batch checkpoints, but does not explain whether checkpoints are written, what the preview returns, or what happens beyond the batch limit.

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

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

A single sentence with zero filler, front-loading the verb and key constraints. It is appropriately sized for the amount of information it chooses to include.

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 input schema has three parameters with nested object arrays and no field descriptions, and there is no output schema. One sentence is not enough to explain how to construct placements or markers, or how checkpoints should be used, so the definition is incomplete for a tool of this complexity.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions checkpoints and timeline mutations, but does not explain that placements is required, what markers represent, or the structure of checkpoint_paths; parameter meaning is largely left to the raw schema.

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

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

States a specific verb ('Preview') and resource ('timeline mutations'), plus a batch-size constraint. It does not explicitly distinguish the tool from nearby siblings like agent_arrange_preview or agent_apply, so it is clear but not sibling-differentiating.

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 says it previews timeline mutations but gives no when-to-use guidance, exclusions, or alternatives. It does not explain whether to call this before agent_apply, or how it relates to agent_arrange_preview.

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

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

Annotations already declare the safe read-only, non-destructive profile, and the description adds two useful caveats: bounded job waiting and no guarantee of audible content. However, 'bounded job waiting' is undefined (no timeout value, no behavior on exceeding the bound) and there is no explanation of what the preview produces or where it writes, so the added transparency is partial.

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

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

A single front-loaded sentence with no filler, and the key scoping constraint leads. The phrase 'bounded job waiting' is slightly jargon-heavy for the amount of information it conveys, but overall it is efficient.

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

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

For a four-parameter tool with 0% schema coverage and no output schema, the definition is too thin. It does not say what the preview returns (job handle, paths, status), how path/folder are used, or what 'bounded' waiting means, so an agent cannot reliably invoke it without guessing.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It only partially does: 'explicit beat range' covers start_beat/end_beat, but the path and folder parameters are never explained, leaving half the inputs undocumented in both schema and 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?

It states a specific verb and resource ('Preview render/stems') plus a scoping detail ('explicit beat range'), so the core action is clear. It never contrasts itself with the many adjacent tools (export_render, export_stems, agent_preview, agent_loop_preview, agent_midi_preview), leaving the agent to guess which preview/export variant to pick.

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 word 'Preview' hints at a pre-commit check, but there is no explicit when-to-use or when-not-to-use guidance. Nothing tells the agent how this differs from export_render/export_stems or from the other agent preview tools, so selection among them is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds one genuinely new behavioral fact — that returned metadata is untrusted data and should not be acted on as instructions — which is real value beyond the structured fields. It still omits what the inspection returns and why the limit is capped at 32.

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

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

Two short fragments with zero padding and the primary purpose front-loaded, which is good. But the terseness reflects under-specification rather than disciplined editing — the security note consumes half the text while core semantics are absent.

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

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

With no output schema and an undocumented parameter, the description must explain what is inspected and roughly what is returned; it does neither. The untrusted-data warning is the only substantive content, leaving the agent unable to predict the response shape.

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

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

Schema coverage is 0%: the single optional 'limit' parameter has no description, bounds explanation, or unit. The description never mentions it, so the agent cannot tell whether it limits items, bytes, or depth. With low coverage the description was expected to compensate and does not.

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

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

"Compact project inspection" essentially restates the tool name (agent_inspect) without saying what part of the project is inspected or what comes back. It does not distinguish itself from siblings like agent_status, session_info, or agent_measure, which all sound like project-level reads.

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 word "compact" hints that this is the cheap/lightweight read, but there is no explicit when-to-use, when-not-to-use, or named alternative. With a dozen agent_* siblings, the agent is left to guess which inspection tool to call.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so safety is covered. The description adds two genuine behavioral facts beyond that: the result is deterministic (implying the seed reproduces output) and it uses live instruments rather than samples. It omits whether anything is written to the session, whether audio is rendered, and what the preview returns.

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

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

A single front-loaded sentence with no filler, which is good, but it is under-specified rather than concise. The word budget spent on 'native' and 'four-part' would be better spent on parameters or usage.

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?

Two optional parameters with no descriptions, no output schema, and an ambiguous relationship to the other preview/apply tools leave real gaps. An agent knows roughly what domain this touches but not what it produces or when to call it instead of agent_midi_preview or agent_preview.

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

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

Schema description coverage is 0% — bpm and seed are documented only by min/max bounds. The description's word 'deterministic' hints that seed controls reproducibility, but neither parameter is named, defaulted, or explained, and the bpm-to-loop relationship is unstated. With low coverage the description should compensate and does not.

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

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

States a specific verb (Preview) and a resource (four-part electronic loop), but the qualifiers 'deterministic', 'native', and 'live instruments' are unexplained jargon. It gives no signal distinguishing it from the many sibling preview tools (agent_preview, agent_midi_preview, agent_repeat_preview, agent_arrange_preview), so an agent cannot tell which preview to pick from the name alone.

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

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

No statement of when to use this over alternatives, despite five-plus sibling '*_preview' tools in the same family. There is no mention of prerequisites (loaded instruments? active session?), no note on whether the preview must be followed by agent_apply, and no exclusions.

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

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

Annotations only say readOnlyHint=false, destructiveHint=false, openWorldHint=false; the description adds no behavioral detail beyond a disclaimer. It never says whether 'propose' writes state, what the measurement covers (LUFS, peak?), how long it takes, or what a proposal contains — and 'measure' superficially suggests a read-only operation while the annotation says otherwise, leaving the agent unsure of side effects.

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

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

Very short and front-loaded, so nothing is wasted, but the brevity comes at the cost of clarity: three dangling clauses separated by commas read as notes rather than a self-contained instruction.

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

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

With no output schema, zero parameter documentation, and thin annotations, the description needed to explain what is measured, what the proposal looks like, and what if anything changes. None of that is present, so an agent could not reliably invoke this tool without experimentation.

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

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

Schema description coverage is 0%, so the description carries the full load for source, target, and seconds — yet it only obliquely implies 'master or track' via the resource nouns, with no mention of accepted formats for the oneOf source, what target means, or the 1–30 second analysis window.

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 fragment 'Measure master or track' names a verb and two resources, and 'propose mastering chain' hints at a second output, but the phrasing is telegraphic — it's unclear whether this analyzes audio, writes anything, or returns a chain proposal. It does not distinguish itself from close siblings master_check, master_targets, and master_build_chain.

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

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

No when-to-use context is given, and no alternative is named even though master_check, master_targets, and master_build_chain occupy adjacent territory. 'No perceptual claims' is a caveat, not guidance about when to select this tool.

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

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

Annotations already declare readOnlyHint and destructiveHint=false, and the description adds genuinely new constraints: the file must be local and 'bounded ... under output-root' (a sandbox restriction), and metadata is 'never applied' (no side effects on the session). It stops short of saying what the preview response contains, which matters given there is no output schema.

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

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

A single dense sentence with the action front-loaded and no filler. It is compressed to the point of using unexplained jargon, but nothing is redundant.

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

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

With no output schema and 0% parameter coverage across three required params, the description should explain the track/slot addressing and what the preview reports. It only covers the read-only nature and path bound, leaving the caller unable to predict the response or fill in track/slot confidently.

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

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

Schema description coverage is 0% and all three parameters are required, so the description carries the full burden. It hints at a path restriction ('under output-root') but says nothing about what 'track' (string or integer) or 'slot' (0-255) mean or how they select the previewed data.

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

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

States a specific verb pair ('parse ... and preview MIDI notes') and a specific resource type (SMF/RMID files), which is enough to separate it from generic siblings like agent_preview or agent_arrange_preview. The jargon 'SMF/RMID' and 'output-root' are unexplained, but the core action is unambiguous.

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

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

'preview ... metadata is reported, never applied' implies a read-only dry-run step, so an agent can infer this precedes something like agent_apply. However, no sibling is named and no explicit condition says when to use this versus agent_preview or agent_arrange_preview.

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 (readOnlyHint=true, destructiveHint=false, openWorldHint=false) already establish that this is a safe, non-executing, local operation, and "Preview" is consistent with that. The description adds the symbolic-reference convention, which is genuinely useful context, but it never says whether steps are validated, whether refs are resolved and reported, or what the preview returns.

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

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

A single tight sentence with the core purpose front-loaded and the reference syntax appended as a second clause. No filler, though the brevity comes at the cost of specification covered under other dimensions.

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

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

This is a batch-orchestration tool (up to 128 steps, aliases, wait flags, cross-step references) with no output schema and 0% parameter documentation; one sentence cannot carry that load. An agent cannot determine execution semantics or how to construct a valid step list from this definition alone.

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

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

Schema description coverage is 0% and the schema has a nested step object with method, params, as, and wait, yet the description explains only the {$ref: alias.id} syntax. It leaves the meaning of label, steps, method, wait, and the alias-binding behavior of "as" entirely undocumented in both schema and prose.

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?

"Preview" is a clear verb, but the object "composable official calls" is jargon that never states these are batched MCP tool invocations described by method/params steps. It also fails to distinguish this generic preview from the many specialized preview siblings (agent_loop_preview, agent_arrange_preview, agent_midi_preview), leaving the agent to guess which preview to pick.

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?

There is no statement of when to use this tool versus agent_apply (the obvious execute counterpart) or any of the specialized preview tools. No prerequisites, no exclusions, no alternatives are named.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that spacing is driven by an explicit native length in beats, which is useful context, but it never states what the preview returns or how it relates to agent_apply.

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

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

A single front-loaded sentence with no wasted words. It is efficiently structured, though the brevity reflects under-specification rather than disciplined editing.

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

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

For a 7-parameter tool with no schema descriptions and no output schema, one sentence is not enough. An agent cannot tell what markers or checkpoint_paths do, what a preview result looks like, or how this pairs with the apply step.

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

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

Schema description coverage is 0% across 7 parameters, so the description carries the full burden. It only illuminates native_length_beats; track, slot, count, start_beat, markers, and checkpoint_paths are left completely undocumented.

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

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

The verb 'Preview' and object 'consecutive placements' give a rough idea, but 'placements' is jargon for what is presumably repeated clip placement. It does not distinguish itself from siblings agent_preview, agent_loop_preview, agent_arrange_preview, or agent_midi_preview, all of which are also previews.

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?

There is no statement of when to use this versus the other agent_* preview tools or when to follow up with agent_apply. The only implied usage is 'use this when you want a repeat preview,' which the agent must infer from the name.

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, destructiveHint=false and openWorldHint=false, so the safety profile is known. 'Enforced operator policy' adds a real hint that this reports constraints the agent must obey, but it doesn't say whether the policy is static, per-session, or what happens if violated.

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

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

A single short clause with no filler, and the key term (capabilities/policy) is front-loaded. Nothing is wasted, though the compactness comes at the cost of specificity captured in other dimensions.

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

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

With no output schema and no parameters, the description is the only place an agent can learn what this returns. It lists three noun categories but not their shape, size, or whether calling it has any cost or side effects on the agent loop, leaving the agent unable to judge relevance confidently.

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

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

The tool takes zero parameters and the schema is closed (additionalProperties: false), so there is nothing for the description to disambiguate. Baseline 4 applies.

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

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

The phrase names the information surfaced (provenance, capabilities, operator policy), which hints at an introspection/status tool, but 'Catalog' is ambiguous as verb-vs-noun and the description never says whose status is being reported (the agent's own build, or the session). It also gives no differentiation from siblings like agent_inspect or session_info.

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?

There is no guidance on when to call this rather than agent_inspect, session_info, or the preview/apply tools. An agent must guess whether this is a prerequisite check before agent_apply or just a diagnostic read.

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

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

Annotations already declare this as a safe read-only operation, but the description adds useful behavioral detail: it reads actual output PCM, rejects peak levels below the silence floor as silent or dither-only, and mentions the default threshold of -80 dBFS. It still does not explain how pass/fail results are returned, but the key rejection criterion is disclosed.

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

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

The description is a single dense but front-loaded sentence with no wasted words. The core action and the key failure condition are both stated immediately.

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 has no output schema, five parameters with zero schema descriptions, and only one required parameter. The description covers the main checks and failure condition, but it does not explain the return format, tolerance behavior for expected_seconds, or how optional parameters affect verification.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains silence_floor_dbfs and its default, and implicitly maps duration/rate/channels to expected_seconds, sample_rate, and channels, but it leaves path semantics and the effect of omitting optional parameters undocumented.

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

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

The description names a specific verification action on WAV output: reading PCM and checking duration, rate, channels, and non-silence. This is clearer than a generic tool, but it does not explicitly distinguish itself from nearby siblings such as analysis_file, agent_measure, or master_check.

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 states what the tool checks but gives no explicit guidance on when to use it versus alternatives. There are no exclusions or named sibling tools, so an agent must infer that it is for post-render audio verification.

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 it as a safe, closed-world read, so the safety profile is covered. The description does add two non-obvious traits — the wait is time-bounded and a timeout does not restart the job — but it never says what the agent receives at timeout (partial result, error, or status) or what progress reporting looks like.

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

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

A single front-loaded sentence with no filler; efficient, though its brevity is under-specification rather than true density.

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 polling/waiting tool with an undocumented deadline parameter, no output schema, and nearby siblings named jobs_wait and jobs_get, the description leaves too much unexplained: deadline units and defaults, timeout return behavior, and progress semantics.

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

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

Schema description coverage is 0%, so the description must carry both parameters, yet it explains neither. It implies a deadline via 'bounded' but gives no units (seconds?), no default, and no explanation of the 'job' integer beyond the ambiguous word 'job'.

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 phrase 'bounded job waiting' names a verb and resource, but 'job' is undefined in an environment that also exposes jobs_get and jobs_wait, so the agent cannot tell from the description alone how agent_wait differs from those 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?

No statement of when to prefer this over jobs_wait, jobs_get, or agent_status, and no exclusion conditions. The only hint is a behavioral property (no restart on timeout), not a selection rule.

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

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

Goes well past the annotations: it discloses the significant side effect that playback starts if stopped (explaining readOnlyHint=false), that the call is asynchronous and returns a job id rather than results, and that only one capture may run at once. These are exactly the traits an agent needs before invoking a non-readonly, non-idempotent tool.

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

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

Front-loads the action, then the payload, then the async contract and the concurrency caveat. The metric enumeration is a long semicolon chain, but with no output schema each listed field is genuinely informative rather than filler.

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

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

With no output schema, the description is the only documentation of what comes back, and it delivers that alongside the async retrieval path, the playback side effect, and the single-capture constraint. An agent can select and invoke it correctly from this text alone.

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

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

Schema coverage is 100%, so the schema already documents source, seconds and start_transport. The description restates the default duration and 1-30 range and clarifies 'master or one track', but adds no syntax or semantics beyond the structured fields.

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

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

States a specific verb and resource: capture what the master or one track plays and analyze it. The scope (live transport vs. offline file) implicitly distinguishes it from analysis_file and analysis_compare, and the enumerated metrics make clear exactly what kind of analysis this is.

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

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

Gives a clear operating context (live capture, kicks playback if stopped) and an explicit follow-up path: 'Returns a job id at once: call jobs.wait with it.' It also states the concurrency rule 'One capture at a time.' It does not explicitly say when to prefer this over analysis_file or analysis_compare for a rendered file, so no exclusion clause.

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

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

Annotations already cover safety (read-only, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real behavior: both inputs must be finished captures, results are ordered strongest-first, and the intended remediation path is an EQ cut set up via two other tools.

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

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

Two sentences, zero padding. The scenario and the returned axis come first, and the recommended fix is tucked into a trailing parenthetical rather than competing with the core statement.

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

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

There is no output schema, so the description must convey the return value, and it does in summary form: per-band levels plus the bands where both sources sit within a few dB, sorted strongest first. Exact field names and units are left unstated, which keeps it from a 5.

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

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

Schema coverage is 100% and both parameters are documented as job ids, so the schema does the heavy lifting (baseline 3). The description contributes the additional constraint that the referenced jobs must be *finished* captures, which is meaning the schema does not encode.

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

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

States a concrete verb-and-resource: comparing two finished captures band by band, returning levels and overlapping-energy bands ordered strongest first. The musical examples (kick/bass, vocal/guitars) make the resource unambiguous. It does not name a sibling to contrast with, so it stops short of 5.

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

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

The framing "where two finished captures compete" implies usage and implies the inputs must be completed analysis jobs, and it points at follow-up tools (devices_add EQ + devices_set_params) as the cure. But it never says when not to use it or how it differs from analysis_capture / analysis_file, leaving the agent to infer the workflow position.

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

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

Adds important behavior beyond the annotations: only the first 10 minutes are read, and the call is asynchronous, returning a job that must be resolved with jobs.wait. The annotations already cover safety (readOnly, idempotent, non-destructive), so the remaining gap is minor.

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

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

Two dense sentences with no waste. Core purpose and file formats come first, followed by usage routing, then the key behavioral constraints (10-minute limit, async job). Everything 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-parameter analysis tool with no output schema, the description covers purpose, formats, sibling routing, truncation, and the async job pattern. It doesn't describe the job result contents, but that is reasonably delegated to jobs.wait.

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 has full schema coverage, so baseline would be 3, but the description adds meaningful constraint by listing accepted file formats (WAV, FLAC, MP3, OGG, AIFF). This helps the agent validate the path argument beyond the schema's 'Absolute path' 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?

States a specific verb and resource ('Analyse an audio file') plus supported formats, and distinguishes this tool from siblings by naming the related workflows (analysis.compare for reference tracks, master.check for exported masters). An agent can tell what it does without opening the schema.

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

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

Explains the two intended use cases clearly: reference track comparison via analysis.compare, or master verification via master.check. It doesn't explicitly state when NOT to use it, but the context is strong enough to route the agent correctly.

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

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

Beyond the annotations, the description discloses the refusal condition (existing clips in range), the atomic 'one undo step' behavior, and that audio tracks are reported as skipped. There is mild tension worth noting: clearing timeline clips via clear_existing is a removal, while destructiveHint is false, though the opt-in and refuse-by-default design makes this defensible rather than contradictory.

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

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

It is dense and front-loaded with the core mechanism first, then constraints and the next step. The semicolon-chained clauses make it a single run-on sentence that takes a second read, but nearly every clause carries information.

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

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

For a mutating, non-idempotent tool with no output schema, the description covers the important behavior: input model, refusal condition, undo granularity, and skip reporting. It could say a bit more about what the call returns (e.g. which sections/markers were created) but nothing essential to 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 the baseline would be 3, but the description adds genuine semantics the schema lacks: 'scene' is a scene row, 'bars' is the per-section length, 'markers' produces one marker per section, and clear_existing scopes removal from start_beat onward. That meaningfully raises it above the schema-only 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 gives a specific verb and resource (lay a song out on the timeline from session scenes) plus the mechanism: one scene row per section, MIDI clips copied and repeated to fill the row, a marker per section, TOMNIC patterns expanded to notes. This clearly separates it from siblings such as arrangement_place_clip (single clip) or arrangement_edit_clip.

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

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

It provides concrete usage context: an example section plan (intro 8, verse 16, drop 16, outro 8), the precondition that the target range must be empty unless clear_existing is set, and the follow-up action 'Then arrangement.play.' It does not, however, contrast itself with alternative arrangement-building routes like agent_arrange_timeline or arrangement_place_clip.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds two things annotations cannot: the operation is undoable, and clips are matched by start position rather than overlap — a meaningful distinction for a destructive range operation. It does not say whether clips spanning the boundary are preserved or what the response contains.

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

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

One sentence carrying action, selection rule, scope and defaults, followed by a one-word reversibility marker. Nothing is padded and the destructive defaults 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 3-parameter destructive tool with full schema coverage and no output schema, this covers action, matching semantics, defaults and undo. It stops just short of telling the agent how many clips were removed or how to identify them afterwards.

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 earns above that by supplying the per-call defaults in one place — no track means all tracks, no start means 0, no end means the end of the arrangement. That said, it does not address the schema's warning that index-based track ids shift when tracks move.

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

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

States a specific verb ('Remove') plus resource ('timeline clips'), with the precise selection rule ('starting inside a range') and scope ('on one track or all'). The 'starting inside' qualifier also implicitly sets it apart from range-overlap or single-clip removal siblings such as arrangement_remove_clip.

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

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

The '(default: all)' note signals that calling with no arguments wipes the whole arrangement, which is useful context for the caller. But there is no explicit guidance on when to pick this over arrangement_remove_clip, clips_clear, or edit_undo, leaving the agent to infer the choice from names alone.

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

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

Annotations already establish that this is a non-read-only, non-destructive, non-idempotent mutation. The description adds meaningful behavior: the copy is independent (deep copy, not linked), MIDI clips can only be copied to MIDI tracks, and the operation is undoable. It does not mention permissions or return values, but the added constraints are useful.

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

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

Three compact sentences with no waste. The core action is front-loaded, followed by the independence and undoability details.

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

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

For a four-parameter mutation tool with full schema coverage, safety annotations, and no output schema, the description covers the essential behavior: copying, track compatibility, independence of the copy, and undoability. It could be strengthened by explicitly distinguishing this from sibling tools, but nothing critical to 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 the baseline is 3. The description adds meaning beyond the schema by clarifying that to_beat is the start beat of the copy and that to_track must be track-type compatible (MIDI clips go to MIDI tracks). It does not elaborate on clip or track index semantics, but it does add value for two parameters.

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

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

States a specific verb and resource: copying one timeline clip to another beat, optionally across tracks. This distinguishes it reasonably from generic placement or duplication tools, though it never names the closest siblings such as arrangement_place_clip or clips_duplicate.

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

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

The description implies when to use it by explaining that the copy is independent and can be edited or muted to make a variation. However, it gives no explicit when-not guidance and does not name alternatives or explain how it differs from arrangement_place_clip or clips_duplicate.

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

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

Annotations already declare non-readonly, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely new behavior: partial-update semantics (unspecified fields preserved), type-dependent length constraints (MIDI grows or shrinks, audio only shrinks), and reversibility ("Undoable"). It does not cover failure modes or the response shape, keeping it at 4.

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

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

Three tight sentences: the core operation and its editable fields come first, the patch rule second, an example third, with "Undoable" as a one-word tail. Every sentence carries distinct information with no redundancy against the schema or annotations.

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 mutation tool with no output schema, the description covers the essentials an agent needs: what changes, what is preserved, undo availability, and the audio/MIDI length asymmetry. Minor gaps remain around error conditions (nonexistent clip index, out-of-range gain) and confirmation behavior, but nothing critical for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns above baseline by explaining semantics the schema cannot: omitted fields retain their value, and length_beats behaves differently by clip type (MIDI can extend, audio cannot). It also cross-references where the clip and track indices come from (arrangement.get, tracks.list).

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

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

States a specific verb and resource ("Change one timeline clip") and enumerates exactly which attributes can be modified: position, length, mute, name, gain. It also pins the identifier source ("index from arrangement.get"). It does not explicitly differentiate itself from near siblings such as arrangement_place_clip, arrangement_copy_clip, arrangement_remove_clip, or clips_set_length, so an agent must infer that this is the in-place mutation tool.

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

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

Provides a concrete usage scenario ("mute the bass in the second half of a drop after copying it there") that clarifies the intended editing workflow, plus the patch rule "Fields left out stay," which tells the agent it can make partial updates safely. No explicit when-not-use or named alternative, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety needs no restating. The description adds real value by disclosing the shape of the payload — playing state, loop region, markers, and clips with start/length in beats — which matters especially because no output schema exists. It stops short of noting cost or size on very large sessions.

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

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

One compact sentence with no filler, and the resource ('the song on the timeline') is front-loaded. It loses a point because the verbless noun-phrase opening reads more like a field list than a declaration of what the call does.

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 parameterless getter with annotations covering the safety profile and no output schema, the description carries enough return-value detail to set expectations. It is not exhaustive — units, size and ordering of the returned clips and markers are unstated — but nothing needed to invoke it is missing.

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

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

The tool takes zero parameters, which sets the baseline at 4. There is nothing to clarify, and the description correctly adds no fictitious filtering or scope arguments that would mislead an agent.

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

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

The description names the resource precisely and enumerates the concrete contents returned (length, play state, loop region, markers, per-track clips with beat positions). That is a clear read operation, but there is no explicit verb and no differentiation from siblings that also surface clip/track data, such as clips_list or tracks_list.

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

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

There is no statement of when to call this versus alternatives like clips_list, tracks_list or transport_get, and no mention of preconditions. Usage is only inferable from the list of returned fields, which is the same gap the calibration MID example was penalized for.

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

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

The description adds useful behavioral context beyond the annotations: the operation is undoable, applies to MIDI tracks, and repeats the clip when length_beats exceeds the clip length. It does not clarify overlap behavior or whether repeated calls create duplicate timeline clips, which matters for a non-idempotent mutation.

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

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

The description is short, front-loaded with the core action, and every clause adds relevant information. The telegraphic phrasing is compact without being 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?

For a four-parameter placement tool with complete schema coverage and annotations, the description supplies the key constraints: MIDI-only applicability, undoability, and repeat behavior for length_beats. It could be more complete by explicitly distinguishing itself from arrangement_copy_clip and by clarifying overlap or duplicate-call behavior.

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

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

Schema description coverage is 100%, so the schema already carries most parameter meaning. The description adds value beyond the schema by explaining that length_beats longer than the source clip causes repetition, which is not stated in the length_beats 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 states a specific action on a specific resource: copying a session clip onto its track's timeline at start_beat. It implicitly distinguishes the source as a session clip rather than an arrangement clip, which helps against siblings like arrangement_copy_clip, but it does not explicitly name or contrast those alternatives.

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

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

Usage is implied by the phrase 'Copy one session clip onto its track's timeline,' and 'MIDI tracks' gives an applicability constraint. However, there is no explicit guidance on when to use this versus arrangement_copy_clip, arrangement_edit_clip, or clips_launch, and no when-not conditions are stated.

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

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

With annotations already declaring readOnly=false, idempotent=true, and destructive=false, the description adds the key behavioral effect: all tracks resume following the arrangement, the playhead moves, and playback starts. It does not explain how existing session clip playback is overridden, but it supplies substantive state-change context beyond the annotations.

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

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

The definition is a single front-loaded sentence with a helpful parenthetical analogy and no wasted text. Every clause contributes to explaining the action or its effect.

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 playback command with full annotation coverage and no output schema, the description explains what happens and the main side effect. It could be slightly richer about its interaction with transport_stop or transport_play, but it is sufficient to invoke correctly.

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

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

Schema description coverage is 100%, and the single from_beat parameter is already documented in the schema as 'Start (default 0)'. The description only echoes 'from a beat' without adding units, range, or behavioral detail, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Play the timeline from a beat') and distinguishes this from generic transport playback by noting that every track follows the arrangement again, like Back to Arrangement. It does not explicitly name the transport_play sibling, but the arrangement-specific behavior is clear enough to separate the two.

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 use case is implied — re-engaging arrangement playback from a beat, similar to Back to Arrangement — but the description never explicitly says when to choose this over transport_play or when not to use it. No prerequisites or exclusions are given.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered; the description adds the non-obvious side effect that later clips on the track shift down one index, plus that the operation is undoable. That reindexing warning is exactly the kind of consequence an agent cannot infer from annotations.

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

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

A single parenthetical-loaded sentence with zero filler; the destructive action, the index source, the reindex consequence, and undoability are all 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 two-parameter destructive mutation with no output schema, the description covers safety, side effects, and recovery, which is what an agent needs before calling. Return value is not described, though 'Undoable' covers the main post-call concern.

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 both schema fields already explain the clip index source (arrangement.get) and the track id/index distinction. The description merely echoes the index provenance, so baseline 3 applies.

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

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

Specific verb and resource ('Delete one timeline clip') with an explicit scope qualifier ('one') that separates it from bulk siblings like arrangement_clear and clips_clear. The delete target and index source are stated in the same breath.

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?

'Delete one timeline clip' plus the pointer to arrangement.get implies this is the single-clip removal path rather than the bulk clear tools, and 'Undoable' tells the agent recovery is available. It stops short of naming alternatives or stating prerequisites explicitly.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the bar is lower. The description still earns credit by adding 'Undoable', a genuinely non-derivable behavioral fact, and by clarifying the enabled flag can also turn the loop off rather than only set it.

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

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

One short sentence with the action front-loaded and zero filler; 'Undoable' is appended as a compact trailing fact. Nothing to cut and nothing buried.

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?

A simple three-parameter setter with full schema coverage, clear annotations, and no output schema, so little prose is required. It is nearly sufficient, with only minor gaps: what happens to an existing loop when a new range is set, and whether start_beat must be less than end_beat (the schema does not enforce it).

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 three parameters and baseline 3 applies. The description does add unit semantics ('in beats') that the schema's terse 'Loop start.'/'Loop end.' entries omit, but contributes nothing else beyond the schema.

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

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

States a specific verb ('Set and enable (or disable)') and a specific resource ('the arrangement loop region'), scoped by unit ('in beats'). An agent can distinguish it from arrangement_get or arrangement_build_song, though it does not name those siblings explicitly.

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

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

Usage is implied rather than stated: you'd call it to define the transport loop range. There is no explicit when/when-not, no mention of arrangement_get as the read counterpart for inspecting the current loop, and no note on interaction with transport_play or scene/clip loop behavior.

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

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

Annotations already declare the write/mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower, and the description still adds real value: the required file-access permission and the explicit 'Undoable' reversibility guarantee. It does not say what happens if the target slot already holds a clip, which is the one behavioral gap.

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

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

Two compact sentences, front-loaded with the action and supported formats, followed by the sequencing hint and prerequisites. No filler or redundancy.

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

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

For a 3-parameter mutation with full schema coverage and no output schema, the description covers formats, destination, permission prerequisite, undoability, and the follow-on step. Only the overwrite/occupied-slot behavior is left unaddressed.

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

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

Schema description coverage is 100% and all three parameters are well documented, including the UUID-vs-index tradeoff for track and the 0-based slot semantics. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (load) plus the resource (audio file), enumerates supported formats, and pins the destination as a session slot on an audio track. The analogy to browser drag-and-drop and the pointer to arrangement.place_clip for timeline placement separate it from siblings unambiguously.

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

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

Explains the prerequisite (file access granted in Omni's Settings) and routes the agent to arrangement.place_clip for the timeline-placement step, which implicitly defines this tool's scope as session-slot loading only. It stops short of naming an explicit when-not-to-use case or contrasting with audio_transcribe/audio_split_stems.

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 it as non-read-only, non-idempotent, closed-world, and non-destructive, but the description adds important behavior beyond them: the model downloads on first use, the call returns a job rather than finished files directly, and the job result contains four file paths. The file-access requirement is also disclosed.

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

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

Three sentences with no wasted wording. The core operation is front-loaded, followed by the return/job behavior and prerequisite 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 tool with no output schema, the description explains the return shape (a job whose result has four file paths) and the downstream audio.import step. It is nearly complete, though it could name jobs_get or jobs_wait for the job-polling workflow.

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

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

Schema coverage is 100%, so both parameters ('path' and 'folder') are already fully described in the input schema. The description reinforces that the input is a WAV mix and the folder is for stems, but adds no new syntax, constraints, or edge-case guidance.

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

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

States a specific verb and resource: 'Split a WAV mix into vocals, drums, bass and other with Demucs'. It also names the downstream consumer ('audio.import can load'), which helps distinguish it from siblings like audio_import and export_stems.

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

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

Gives clear operational context and a prerequisite ('Needs file access (Settings, AI Create)'), and indicates that the resulting stems can be loaded with audio.import. It does not explicitly state when not to use it or compare it to export_stems, so it stops short of full 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 the readOnly/idempotent annotations, it discloses that the call is asynchronous ("Returns a job"), what the job result contains (notes in beats at project tempo plus detected length), and the permissions prerequisite. The main remaining gap is that it never says how to retrieve the job, leaving the agent to infer jobs_get/jobs_wait.

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

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

Four dense sentences with no filler; the core transformation and input options are front-loaded, followed by output shape, then the permission caveat. Every clause carries actionable information.

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

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

With no output schema, the description does the work of explaining the job/result model and the note format, which is what an agent needs. The one omission is the job-retrieval path (jobs_get/jobs_wait) and whether polling or waiting is expected.

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 genuine meaning the schema lacks: path and slot are alternative input routes rather than independent settings, and the enum values are glossed (poly = chords, melody = one line, bass). It does not touch min_ms, sustain, or sensitivity, which are left to the schema.

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

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

The opening clause states a concrete transformation (audio to notes) and names the engine (Basic Pitch), then enumerates the two input sources (file path or session slot) and the three modes. An agent can distinguish this from audio_import or audio_split_stems purely from the text, without opening the schema.

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

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

It clarifies input selection (a file path OR a track+slot pair) and the prerequisite that file paths require file access enabled in Settings / AI Create. It also points forward to clips.write_midi as the consumer of the result, which implies the intended workflow. It stops short of explicit exclusions such as when to prefer audio_import or clips_generate_melody instead.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, so the safety profile is covered. The description adds non-obvious behavior beyond annotations: the automation lane is preserved but left empty, and the action is undoable — both useful facts an agent wouldn't know otherwise.

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

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

A single tight sentence with the key scope constraint parenthetically front-loaded. No filler; every clause earns its place.

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

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

For a 2-param destructive mutation with full schema coverage and no output schema, the description covers the essential behavioral facts (lane remains, undoable). Minor gap: no mention of error behavior or confirmation, but annotations carry most of the profile.

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

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

Schema coverage is 100% and both parameters are fully documented in the schema (param types, track id/index semantics). The description adds nothing about parameters beyond the schema, so baseline 3 applies.

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

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

States a specific verb (Remove) and resource (the automation of one parameter on a track), plus the scope clarification that the lane remains but empty. Clearly distinguishable from automation_list and automation_write by sibling names alone.

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?

Implicitly conveys usage (clearing automation), but never explicitly contrasts with automation_write or says when-not to use it. An agent can infer the intent but gets no explicit routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is fully covered. The description adds the shape of the returned data (per-lane key, segment and point counts, beat span), which is genuinely useful given there is no output schema, but says nothing about ordering, lane limits, or behavior for tracks with no automation.

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

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

A single dense sentence with zero padding, front-loaded on the resource and followed by the returned fields. It is a noun phrase rather than a complete statement, which makes it slightly less crisp as an opener.

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

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

For a one-parameter read-only list with full annotation coverage and no output schema, the description covers both the resource and the return contents. Only minor gaps remain: no guidance on when to call it relative to the automation write/clear siblings.

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

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

Schema description coverage is 100% and the schema already explains the UUID-vs-0-based-index duality and the index-shifting caveat in detail. The description contributes nothing about the track parameter, so the baseline of 3 applies.

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

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

The description names a specific resource — the automation lanes of a track on the arrangement timeline — and enumerates what is returned (key, segment/point counts, span in beats). It never uses an explicit verb like 'list', and it doesn't name the sibling it complements (automation_write / automation_clear), but the resource is unambiguous.

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

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

There is no statement of when to use this versus automation_write or automation_clear, and no prerequisite context (e.g., 'call before writing to see existing lanes'). The read-only intent is inferable only from the name and annotations, not from the description.

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 important behavior beyond annotations: the lane is created automatically if needed, existing automation is replaced, the result plays with the arrangement, and the operation is undoable. These details are consistent with readOnlyHint=false, idempotentHint=true, and destructiveHint=false because replacement is idempotent and undoable.

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 scope, followed by a useful concrete example and two short behavioral notes. Every sentence adds value without unnecessary length.

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

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

Given full schema coverage, annotations covering safety and idempotency, and no output schema, the description is complete enough to call the tool correctly. It covers purpose, replacement behavior, playback timing, and undoability.

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

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

Schema coverage is 100%, so the schema already documents track, param, points, and curve. The description reinforces beat/value semantics and provides a concrete example, but it does not add new meaning for curve or the track id-vs-index distinction beyond what the schema provides.

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

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

The description gives a specific verb and resource: automate a track's volume, pan, or any parameter over the song. It also distinguishes the write behavior by stating that the lane is created if needed and existing automation is replaced, separating it from automation_list and automation_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?

It provides clear context for use: writing breakpoints at song beats over the arrangement, with an example of a filter sweep. It does not explicitly name alternatives like automation_list or automation_clear, or state when not to use this tool, so it falls short of full routing guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's real contribution is 'Undoable' (reversibility via edit_undo) and the enumeration of what content is wiped. It stops short of saying whether the slot becomes empty or the clip is removed entirely.

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?

Eight words, front-loaded with the action and target, with the reversibility caveat appended. Nothing wasted and nothing buried.

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 mutation tool with rich annotations and full schema coverage, the description covers target, effect and reversibility. Only the post-clear state of the slot is left ambiguous.

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

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

Schema description coverage is 100%, with both 'track' (UUID vs shifting 0-based index) and 'slot' (0-based scene row) fully documented in the schema. The description adds no parameter meaning beyond that, so baseline 3 applies.

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

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

States a specific verb and resource: 'Empty a session clip slot', and enumerates what gets removed (notes, audio, sequencer). The word 'session' implicitly separates it from arrangement_clear and clips_stop, but no sibling is named explicitly.

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

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

Usage is only implied by the noun phrase 'session clip slot'; there is no explicit when-to-use, no prerequisites (e.g. clip must exist), and no routing away from clips_stop or arrangement_clear. The 'Undoable' note is the only contextual cue.

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

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

Annotations already declare readOnly=false, idempotent=true, destructive=false, so safety is partly covered. The description adds the two facts an agent actually needs before calling: the target slot's existing clip is overwritten, and the operation is undoable. The overwrite wording sits in mild tension with destructiveHint=false, but 'Undoable' reconciles it, so no genuine 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?

Three short sentences, front-loaded with the action, then the compatibility constraint and the overwrite/undo consequences. Nothing restates the name and nothing 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 4-parameter mutation with full schema coverage and no output schema, the description covers the essential unknowns: type-compatibility restriction, target overwrite, and undoability. Minor omissions are what the call returns and whether the source clip remains in place.

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

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

Schema coverage is 100% and both track parameters are fully documented (UUID vs 0-based index, slot ranges), so the schema does the heavy lifting. The description only implicitly clarifies that to_track is optional ('same track or another one') and adds no slot or index semantics beyond the schema.

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

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

States a specific verb and resource (copy a session clip to another slot) plus the scope constraint (same track or another of the same kind, MIDI→MIDI, audio→audio). That framing cleanly separates it from arrangement_copy_clip and clips_write_midi without needing to name them.

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

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

The description supplies the operative condition: destination must be the same track or a track of the same kind, which tells the agent when this call will succeed. It stops short of naming an alternative (e.g. arrangement_copy_clip for timeline copies) or stating when not to use it.

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

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

Annotations already declare non-read-only, idempotent, non-destructive; the description adds two real facts beyond them — determinism from the seed and that the write is undoable. It does not say whether existing notes in the slot are replaced or merged, nor any clip-length handling, which is the main behavioral question for a write into an existing slot.

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

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

Two sentences, front-loaded with purpose then the harmonization rule, with no filler. The full enumeration of twelve style values restates the schema enum and is the one segment that does not earn its space.

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

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

For a 9-parameter, nested-object write tool with no output schema, the description covers the core decision points (style, harmonic source, determinism, reversibility). The remaining gap — overwrite versus merge semantics for the target slot — is the one thing an agent still has to guess.

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 78% and the description adds meaning on top: the seed's determinism contract, and how chords_from relates to the slot's chord lane with a concrete example. The twelve style names are repeated from the enum, so it adds little for style itself.

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?

"Write a melody into a MIDI slot with the piano roll's melody generator" gives a specific verb, resource, and the generator it uses, and the parameter roll-call (style, key, bars, register, density) makes it clearly distinct from clips_write_midi (explicit notes) and clips_write_progression (chords).

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 explains the harmonic source decision: the slot's own chord lane by default, or chords_from pointing at another slot, with a concrete workflow example (the pad slot written by clips.write_progression). It never states when to prefer this over clips_write_midi or what happens if the slot already has notes, so the guidance is clear but not exclusive.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real value beyond that by disclosing the return contents and the unit convention (times in beats), which the agent cannot get from any output schema since none exists. It stops short of saying what happens for an empty slot or a non-MIDI clip.

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

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

A single front-loaded sentence fragment with zero filler; every token carries information. It reads as a return-value spec rather than an action statement, which is slightly less scannable than a verb-first sentence but costs no waste.

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

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

With no output schema, the description is the only source on return values and it does list the fields, but not their structure (flat list? per-note objects?) or ordering, and it says nothing about empty slots or non-MIDI clips. Adequate for a simple two-parameter read, but not fully self-sufficient.

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

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

Schema description coverage is 100% — both 'track' (UUID or shifting 0-based index) and 'slot' (0-based scene row, 0-255) are fully documented in-schema. The description adds no parameter-level detail beyond implying that track+slot identify the clip, so the baseline 3 applies.

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

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

Names the exact resource — notes of a session MIDI clip — and enumerates the returned fields (pitch, start, duration, velocity) plus loop length, so the agent knows precisely what it gets. It does not distinguish itself from nearby siblings such as clips_list (finding the clip) or arrangement_get (non-session clip data), leaving that inference to the agent.

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

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

The phrase 'session MIDI clip' implicitly scopes usage: not arrangement clips, not audio clips. There is no explicit when-to-use guidance, no mention of using clips_list to discover a valid track/slot first, and no stated alternatives or preconditions.

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

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

Annotations already declare non-destructive, idempotent, non-read-only, so the bar is lower; the description still adds real value by disclosing the transport side effect ('starts the transport unless start_transport is false') and the quantised launch timing. It does not say what happens when the target slot is empty.

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

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

Two short sentences, no filler, with the core action stated first and the transport side effect immediately after. Every clause earns its place.

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

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

For a 3-parameter tool with full schema coverage and no output schema, the description covers the action and its main side effect. It falls slightly short on failure behaviour (empty slot, invalid track) which an agent might need before committing.

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 carries its own description, including the track UUID-vs-index tradeoff and the start_transport default. The description only echoes start_transport, adding nothing beyond the schema, so baseline 3 applies.

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

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

A specific verb (Play) and resource (a session clip) with a scoping qualifier ('quantised like a click on its slot'). It is clearly distinguishable from clips_stop and from scenes_launch, but it never names those siblings to make the boundary explicit.

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

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

Usage is implied by the verb and the quantisation note, but there is no explicit guidance on when to choose this over scenes_launch (whole-scene) or transport_play, nor any mentioned prerequisites such as the track/slot needing an existing clip.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds value by enumerating the reported fields, which substitutes for the absent output schema. It does not state ordering (scene index order?), whether empty slots are always included, or what 'queued' means operationally.

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

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

One dense sentence with no filler and the resource scope front-loaded before the field enumeration. It is a noun-phrase fragment rather than a sentence, which is slightly terse for an agent skimming for selection cues, but nothing is wasted.

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

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

For a one-parameter read tool with full annotation coverage and no output schema, the field enumeration covers most of what an agent needs. Missing: result ordering, whether empty slots appear, and any hint of result shape (array of objects vs. keyed map), which the absent output schema would otherwise carry.

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?

Single parameter with 100% schema description coverage; the schema already explains the UUID-vs-index tradeoff and the index instability caveat. The description says nothing about the track argument, so baseline 3 applies — it neither adds nor detracts from what the schema provides.

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

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

The description names the specific resource — the session clip slots (scene rows) belonging to one track — and enumerates the per-slot facts reported (empty/occupied, kind, loop length, note count, playing/queued). An agent can distinguish this from scenes_list (whole scenes) and clips_get_notes (note payload of one clip) without opening a schema. It lacks an explicit verb ('list'), but the resource scope is unambiguous.

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

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

Usage is only implied: an agent infers this is the way to survey what fills a track's scene slots before doing anything clip-related. There is no explicit when-to-use statement and no named alternative (e.g. scenes_list for a per-scene cross-track view, clips_get_notes when note content 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 idempotent=true and destructive=false, but the description adds value beyond them: 'notes past the end stay but do not play' discloses the non-destructive side effect on out-of-range MIDI, and 'Undoable' confirms recoverability. It does not say what happens when the target slot is empty or whether an error is raised.

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

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

One front-loaded clause plus a precisely chosen parenthetical and a one-word reversibility note. Nothing is padded and the most decision-relevant constraint (beats, retention behavior) comes first.

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

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

For a three-parameter mutation with full schema coverage, annotations, and no output schema, the description covers purpose, side effects, and reversibility. It stops short of stating failure modes or preconditions for slot occupancy.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning for length_beats by explaining the consequence of shortening the loop (content is retained, not truncated). Track and slot semantics are left entirely to the schema.

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

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

States a specific verb ('Set'), a specific resource ('loop length of a session clip'), and a unit ('in beats'). The 'session clip' scoping cleanly separates it from siblings like arrangement_set_loop and clips_transform without needing to name them.

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

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

The single-purpose nature makes the use case inferable, but there is no explicit guidance on when to use this versus alternatives such as clips_transform or clips_duplicate, and no stated preconditions (e.g. a clip must already exist in that slot).

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

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

The annotations already establish that this is a non-read-only, idempotent, non-destructive operation. The description adds the important behavioral detail that omitting track stops all tracks, but it does not describe any additional side effects, return behavior, or prerequisites.

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 definition is a single front-loaded sentence with no wasted wording. It communicates the core action and the all-tracks default efficiently.

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

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

For a simple one-parameter mutation with annotations covering safety and no output schema, the description is largely complete. Its main gap is the lack of explicit comparison with alternative clip or transport controls.

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

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

Schema coverage is 100%, and the schema already explains UUID versus 0-based index semantics. The description adds meaning beyond the schema by stating that no track means every track, which clarifies the optional parameter's default scope.

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

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

The description uses a specific verb and resource: stopping the session clip of one track or all tracks. It is clear and scoped, but it does not explicitly distinguish itself from nearby siblings such as clips_launch, clips_clear, or transport_stop.

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 explains the effect of omitting track (stop every track) and supplying one (stop that track), which is useful invocation guidance. However, it gives no explicit when-to-use guidance versus alternative clip or transport tools, and no exclusions.

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

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

Annotations already declare the safety profile (readOnly=false, destructiveHint=false, idempotentHint=false). The description adds two behaviors not in the structured data: the operation applies to *every* note in the clip (whole-clip scope) and the change is undoable, which is essential for a bulk mutation on a non-destructive tool.

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

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

Two compact sentences, front-loaded with the operation and scope, followed by a single-word reversibility note. Nothing is padded or restated from the schema.

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

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

For a 7-parameter, 2-required bulk mutation with annotations and no output schema, the description covers what is changed and that it is reversible. It omits what the call returns (e.g., count of notes edited) and whether passing no transform params is a no-op or an error, minor gaps given the full schema documentation.

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

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

Schema coverage is 100%, so every parameter is already documented. The description contributes one genuinely useful detail ('0.25 = 1/16 in 4/4') and clarifies the scale-then-offset ordering for velocity, but leaves quantize_strength's default and the interaction between optional params to the schema.

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

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

States a specific verb and resource ('Edit every note of a MIDI clip at once') and enumerates the transformations (transpose, quantize, velocity scale/offset), which clearly separates it from write/get/clear siblings. It stops short of naming which sibling to use for related tasks such as reading notes or replacing them wholesale.

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

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

Usage is implied rather than stated: the tool operates on an existing clip's notes in bulk, and 'Undoable' hints at a reversible mutation. There is no explicit when-to-use/when-not, no mention of clips_get_notes to inspect first or clips_write_midi to replace notes instead.

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 disclose readOnly=false, idempotent=true, destructive=false; the description adds real context beyond them by stating that the existing pattern is replaced, that merge preserves untouched lanes, that writes are undoable, and that polymeters are allowed. That is meaningful mutation-behavior disclosure, though it does not mention permission/eligibility requirements.

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

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

Front-loads the verb and resource, then scoping, then notation rules and the replace/merge guarantee. The example patterns are compact and directly operational; no sentence is 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 5-parameter mutation tool with full schema coverage and annotations covering the safety profile, the description supplies everything an agent needs to construct valid calls: notation semantics, rate interpretation, replace-vs-merge behavior, and undoability. No output schema is needed since only a write acknowledgment is expected.

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

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

Schema coverage is 100%, so baseline is 3, and the description still adds value: it explains the step alphabet (x/X/.), that bars may be marked with '|' or spaces, that lane lengths may differ, and that at 1/16 sixteen steps equal one 4/4 bar. It goes beyond the schema field text rather than repeating it.

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

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

States a specific verb and resource ("Write a drum pattern into a session slot") and immediately scopes it ("a TOMNIC track"), explicitly contrasting with clip-note writing, which is what sibling clips_write_midi does. An agent can route between the two without opening either schema.

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

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

Implies the target condition (TOMNIC tracks that use their own step patterns) and explains mode selection ("Replaces the pattern, or with mode merge only the lanes given"). It does not explicitly name the alternative tool for non-TOMNIC tracks, so guidance is clear but not fully routing.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, but the description adds real behavior: the slot is created if empty, 'replace' leaves exactly these notes (i.e. prior notes are discarded), the clip loops, and the operation is undoable. That last point is the key mitigation for replace-mode overwriting. The mild tension between replace-mode deletion and destructiveHint=false is disclosed rather than hidden, so 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?

Four short sentences, front-loaded with the action and the slot-creation condition, then mode semantics, then length defaults, then units, then the launch pointer. Every sentence carries information the agent needs and none repeat the schema verbatim.

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

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

For a 5-parameter mutation with no output schema, the description covers creation behavior, overwrite semantics, defaults, units, undoability, and the natural next call. The one gap is what the tool returns (e.g. whether it hands back the new clip reference), which an agent would want before chaining into clips.launch.

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 earns above that by explaining defaults and units the schema does not: length_beats defaults to the notes rounded up to whole bars, and times are in beats with '1 beat = a quarter note; in 4/4 a bar is 4 beats'. It also restates the replace/merge semantics of mode with more precision than the schema's one-liner.

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

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

The description opens with a specific verb+resource+location: 'Write notes into a session clip slot of a MIDI track', and adds the create-if-empty condition. It implicitly separates itself from arrangement_* and clips_get_notes by naming the session clip slot, but never explicitly contrasts with close siblings like clips_write_drums or clips_transform, so it stops short of a 5.

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

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

It gives useful operating guidance — 'replace' is the default, 'merge' adds, length_beats defaults to whole bars, and 'launch it with clips.launch' as the follow-up. What it lacks is any when-to-use-this-vs-alternative routing: nothing tells the agent why to pick this over clips_write_progression, clips_generate_melody, or clips_transform.

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

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

Adds real behavior beyond the annotations: it warns that existing clip notes are replaced, that the loop length is inherited from the progression rather than chosen, and that the operation is undoable. The 'Replaces the clip's notes' caveat is exactly the kind of consequence destructiveHint=false alone would not convey, and it is consistent with the annotations rather than 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?

Four short sentences, front-loaded with the action and destination, then the consequences (loop length, note replacement, undo). Nothing is padded or restated from the title.

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

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

For a three-parameter nested write with no output schema, the description covers the important semantics: what is written, what is overwritten, loop length source, and undo safety. It leaves out what is returned (e.g. the created/updated clip reference) and behavior when the target slot already holds a clip, which the reader must infer from 'Replaces the clip's notes.'

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 67% with deeply nested objects, and the description adds meaning the schema does not: the three mutually exclusive ways to supply a progression (inline chord text, a named library entry, or generated output) are surfaced as alternatives, and the chord-lane side effect explains why slot/track matter. It does not touch the perform sub-options, leaving some nested semantics to the schema.

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

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

Specific verb and resource: 'Render a chord progression ... into a session slot of a MIDI track and set the clip's chord lane.' That clearly separates it from note-level writers like clips_write_midi or clips_write_drums, and the parenthetical points at theory.progression as the source. It stops short of explicitly naming the sibling tools it is an alternative to.

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

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

Usage is implied rather than stated: it points to theory.progression for building the progression, and 'The loop length is the progression's' hints at how it differs from clips_set_length. But there is no explicit when-to-use/when-not guidance versus clips_write_midi, clips_write_drums, or clips_generate_melody.

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

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

Annotations already declare non-readonly, idempotent, non-destructive behavior, and the description usefully adds that the operation replaces existing notes and is undoable. That clarifies the mutation’s effect beyond the structured hints, though it does not cover permissions or return behavior.

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

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

The description is front-loaded and fits into one long sentence with no irrelevant material, though the examples make it slightly denser than strictly necessary.

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

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

With a fully described schema and annotations covering safety/idempotency, the description supplies the critical replacement and undoability context. It is complete enough for an agent to invoke correctly, though it could mention the relationship to slicing tools like sampler_slice.

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

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

Schema coverage is 100%, so the schema already documents slice, start, duration, velocity, pitch, track, and slot. The description restates the key step fields but adds little syntax or meaning beyond the schema.

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

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

The description states a specific verb and resource: writing slice playback steps for a sliced audio clip, replacing its notes. It clearly distinguishes this from generic MIDI writing by tying the operation to slice indices and audio-clip slices.

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

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

It provides implied usage context—melodic single-slice playback versus rearranged breaks with many slices—but never explicitly says when to use this instead of siblings like clips_write_midi or clips_transform.

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

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

Adds genuinely non-schema context: the effect starts at default settings, the call returns the chain, and the operation is undoable. "Undoable" in particular is not derivable from the annotations, which only say destructiveHint=false and idempotentHint=false. It does not explain failure modes (invalid device name, full chain), so not a 5.

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

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

Three short sentences with zero filler, front-loaded with the action, then the follow-up tool, then the return/undo facts. Every clause carries information an agent would otherwise have to infer.

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

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

With a 100%-covered schema and no output schema, the description covers what the tool does, how to configure afterwards, what it returns, and reversibility. Missing only edge-case behavior such as an out-of-range position or an unknown device name.

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 still adds value by stating that omitting position appends to the end of the chain, a semantic the schema does not spell out. It also anchors the device parameter to the devices.types vocabulary.

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

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

States a specific verb and resource ("Insert a builtin effect ... into a chain") plus the target scope (end of chain or an explicit position). This cleanly distinguishes it from siblings such as devices_remove, devices_set_params, and devices_list without requiring schema 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?

Routes the agent to devices.types for valid effect names and to devices.set_params for configuring the newly inserted effect, which is concrete alternative-routing guidance. It stops short of explicit exclusions or prerequisites (e.g. track must exist, chain length limits), so it is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description earns credit for genuinely additive behavior: values are returned in real units (dB, Hz, ms, %) rather than normalized 0..1, and choice parameters expose an index-to-option mapping (Shape 4 = HighPass) — both are non-obvious and prevent misreading the response. It does not say what happens for an empty slot or a non-builtin/plugin device, which keeps it below 5.

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

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

It is a single tight sentence with no filler, but it is front-loaded with return-value detail rather than the tool's action, which is the wrong lead for an agent scanning for a verb and resource. The content is efficient; the ordering is not.

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

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

With no output schema, the description carries the burden of explaining return values and does so partially: parameter value/range/default/unit/group and enumerated choices are covered. But it omits the top-level shape (does it also return device name, type, bypass state?), leaves 'builtin effect' undefined against plugin devices, and says nothing about failure on an empty slot. Adequate for a 2-parameter read, with clear gaps.

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

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

Schema description coverage is 100%: slot is documented as a 0-based signal-order position and chain is documented with the track/return_bus/master union, including the id-vs-index tradeoff. The description adds nothing about either parameter, so the baseline 3 applies — the schema does all the work here.

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

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

The description never states the operation explicitly — it never says 'retrieve the device at a chain slot' and never names the device as the resource being fetched. Instead it jumps straight into describing the shape of the returned parameter list, from which an agent must infer that this reads a builtin effect's parameters. It also does not distinguish itself from nearby siblings like params_list, devices_list, or midi_fx_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?

There is no when-to-use guidance, no prerequisites, and no named alternative. With siblings such as params_list and devices_list present, an agent is left to guess whether this is the right call for inspecting effect parameters versus listing devices.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the burden is light, and the description adds real value by disclosing the returned fields per device — slot, name, kind (builtin/plugin/script), bypass, and parameter count — plus that results come back in signal order. That return-shape and ordering information is nowhere in the structured data and is exactly what an agent needs to plan a follow-up call such as devices_set_params.

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

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

It is a single compact sentence with no filler, but it is grammatically a fragment and front-loads an abstract phrase ("The effects of a chain in signal order") ahead of the actual operation. The per-device field list is the most useful part and arrives last.

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

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

With one fully documented parameter and no output schema, the description partially compensates by enumerating returned fields and their meaning. It still leaves open what happens for an empty chain or invalid track id, whether MIDI effect chains are included, and whether devices add more fields than the five listed.

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

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

Schema coverage is 100% and the schema description already spells out {"track": <id or index>}, {"return_bus": <index>} and "master", including the stability caveat for indices. The description restates the same three forms without adding syntax or edge-case semantics, so it does not exceed the baseline for a fully documented 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 never states the verb ("list") or the resource ("devices"); it opens with "The effects of a chain in signal order," which is a noun phrase about the chain rather than about the tool. An agent can infer it enumerates devices in a track/return/master chain, but only after parsing the parenthetical forms, and nothing distinguishes it from devices_get or devices_types.

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?

There is no statement of when to call this rather than devices_get, devices_types, params_list, or mixer_get, despite those siblings sitting in the same namespace. No prerequisites, no context cues — the agent must guess from the names.

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

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

Adds two facts annotations cannot express: that subsequent slots re-index upward after removal, and that the operation is undoable. This meaningfully softens the destructiveHint and tells the agent a follow-up re-index is needed for any stored slot positions. Return payload and failure modes (invalid slot, empty chain) remain unstated.

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

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

Two dense clauses, front-loaded with the action, then the side effect, then the safety note. Nothing is wasted or repeated from the schema.

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

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

For a two-parameter mutation with rich annotations and a fully documented schema, this covers the essential surprises (index shifting, undoability). It leaves out only error/edge behavior and whether the chain must be non-empty, which is minor given the rest of the definition.

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

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

Schema coverage is 100% and both parameters are documented in-schema, so the baseline of 3 applies. The description adds only indirect context ('later slots move up' clarifies that slot indices are positional and shift), but gives no guidance on the chain variants (master/track/return_bus) or on preferring stable track IDs over indices.

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

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

Names a specific verb+resource ('Remove an effect from a chain') and states the resulting state change ('later slots move up'). It is clearly distinct from devices_add/set_bypass, though it uses 'effect' while the tool/sibling names use 'device', which adds a small terminology hop.

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

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

Usage is implied by the name and the removal semantics, but there is no explicit when-to-use or when-not guidance. It never distinguishes itself from the adjacent removal tools such as midi_fx_remove or mixer_remove_return, so the agent must infer that this one is for audio/instrument device chains.

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 idempotent, non-destructive, non-read-only. The description adds genuine domain behavior beyond that: the switch crossfades with no click, and the change is undoable, pointing the agent at edit_undo. It does not say what happens if slot is out of range or the device is missing, which keeps it below 5.

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

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

Three short clauses with no filler and the core action front-loaded. The opening phrase 'Bypass (true) or enable an effect' is slightly garbled (the object of 'bypass' is implicit), costing a little clarity in an otherwise tight two-sentence block.

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 3-parameter fully documented tool with annotations covering safety and idempotency, the description covers the essentials plus undo and click-free behavior. But with a near-identical sibling (midi_fx_set_bypass) unaddressed and no mention of failure conditions, an agent still has gaps to infer.

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 of chain/slot/bypassed is documented in the schema itself, so the baseline is 3. The description only disambiguates the boolean polarity (true = bypass), adding marginal value over the schema text 'Bypass the effect.'

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

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

States a specific verb and resource: bypass or enable an effect device. However, the title/aliasing against the sibling midi_fx_set_bypass is absent, so an agent looking at both 'set_bypass' tools gets no signal about which applies to audio devices vs MIDI FX. The polarity clarification ('true' = bypass) is helpful and specific.

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

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

One concrete use case is given ('compare before / after with mix.meters'), which implies an A/B workflow, but there are no exclusions and no naming of the sibling alternative midi_fx_set_bypass. Usage is implied rather than directed.

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

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

Adds real behavior beyond the annotations: all values are range-checked before any change (atomic), the whole batch is one undo step, and the device is returned with new values. The annotations already declare idempotency and non-destructiveness, so this extra transactional detail is what earns the score.

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

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

Three tight sentences with no filler; the core action comes first, then validation/undo semantics, then the return 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?

For a 3-parameter mutation tool with full schema coverage and annotations, the description covers validation, atomicity, undo granularity, and the response. Only error behavior on out-of-range values is left unstated.

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 value: values are interpreted in the parameter's own unit, and names are case-insensitive and match what devices.get reports. That resolves the main ambiguity in the loosely-typed 'values' map.

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

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

States a specific verb and resource: sets parameters of a builtin effect, in bulk, addressed by name or index. It distinguishes itself from devices_set_bypass and midi_fx_set_params through the 'builtin effect' scope, though it never names those siblings explicitly.

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

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

The phrase 'set several parameters ... at once' implies bulk use and the reference to devices.get implies prerequisites, but there is no explicit statement of when to prefer this over params_set, midi_fx_set_params, or devices_set_bypass.

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 establish that this is a safe, read-only, idempotent operation, so the description has a lower burden. It adds useful domain context that these are Omni builtin effects grouped by family, but it does not clarify the return shape, whether the catalog is static, or what 'creative ones' includes.

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 definition is a single front-loaded sentence with no wasted preamble, and the family list is useful for understanding scope. The phrase 'and creative ones' is slightly vague but does not undermine the overall efficiency.

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 zero-parameter catalog with rich annotations, the description is mostly adequate and does mention that types come with their family. However, with no output schema, it should more explicitly state what is returned and better distinguish this from sibling tools like midi_fx_types and devices_list.

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

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

The tool takes no parameters and the schema is empty, so there are no parameter semantics for the description to explain. A baseline of 4 is appropriate for a zero-parameter tool.

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

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

The description identifies a specific resource: builtin effect types that devices.add can insert, and enumerates their families. This distinguishes it reasonably well from devices_list and devices_add, though it is phrased as a noun list rather than explicitly saying it returns the available device types.

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

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

Usage is implied by the connection to devices.add, suggesting the tool is for discovering insertable effect types. However, it gives no explicit when-to-use guidance, no exclusions, and does not mention alternatives such as devices_list or midi_fx_types.

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

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

Annotations already declare this is a non-readonly, non-idempotent, non-destructive edit. The description adds one piece of context beyond them: that the call returns what was redone. It does not disclose history-stack scope (per session vs global), error behavior when nothing is undone, or whether repeated calls walk further forward.

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

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

Two short sentences, front-loaded with the action, and nothing redundant is included. It is terse to the point of omitting useful behavior, but that is a completeness issue rather than verbosity.

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

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

No output schema exists, so the description's single return-value sentence is doing real but minimal work. For a stateful, non-idempotent history operation in a large DAW toolset, missing details about the undo/redo stack scope and empty-stack behavior leave gaps.

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

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

Zero parameters, so the schema carries no semantics to add to; baseline is 4. The description correctly avoids inventing argument descriptions.

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

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

States a clear verb (redo) and resource (the last undone edit), and the phrase 'step undone last' implicitly distinguishes it from the sibling edit_undo without naming it. No explicit routing sentence, so not a 5.

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

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

The word 'undone last' implies the prerequisite that a prior undo must exist, which is the only usage context given. There is no explicit when-to-use vs edit_undo statement, no mention of what happens when the redo stack is empty, and no alternatives named.

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

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

Annotations already declare the safety profile (not read-only, not idempotent, not destructive), so the bar is lower. The description adds meaningful context beyond that: the undo target is a single labeled history step and the call reports what was undone, though it says nothing about what happens when history is empty or how deep the history goes.

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

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

Two compact sentences with the action front-loaded and the parenthetical scope note earning its place by explaining what a 'step' means.

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

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

Given no parameters, no output schema, and annotations covering the safety profile, the description is largely complete: it names the target and the return ('what was undone'). Only failure/empty-history behavior is left unstated.

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

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

Zero parameters, so baseline is 4. The description reinforces that the tool takes no selection input by specifying it always acts on the newest history entry, which is a useful semantic clarification.

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

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

States a specific verb (undo) and resource (the newest step in Omni's history), which is clearly distinct from the sibling edit_redo. It doesn't explicitly name edit_redo as the counterpart, but an agent can tell the two operations apart from the text alone.

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 clarifies scope ('newest step', 'the user's or yours') and that every API edit call is one step labelled 'API: ...', which implies when this is useful. However, it never states when-not to use it or names edit_redo as the alternative for re-applying an undone step, so guidance is implied rather than explicit.

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

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

Adds substantial behavioral context beyond the annotations: writes only absolute .wav paths, will not overwrite unless asked, session clips only sound if recorded into the arrangement, and the call returns an async job rather than the finished file. These are exactly the surprises an agent would otherwise hit.

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

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

Front-loaded with the core action and mode choice, then return/job semantics, then write-safety notes — a good ordering. It is a single dense paragraph with some stacked parentheticals, but almost every clause carries information.

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

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

With no output schema, the description steps in to describe the job handle, waiting on it, and the result payload (path plus file analysis). Remaining gaps are minor: no note on expected runtime for real-time renders or on failure behavior for invalid paths.

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 still adds meaning by noting the beat range defaults to the whole song, that optional normalisation targets a loudness goal from master.targets, and that "fast" means the same mix rendered offline. Dither and bit-depth interplay with dithering is left entirely to the schema.

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

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

States a specific verb and resource ("Render the arrangement ... to a WAV file") with scope (start_beat to end_beat, default whole song). The real-time vs fast-offline framing and the "as the Export dialog does" analogy make it clearly distinct from siblings such as export_stems and agent_export_preview.

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

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

Explains the two rendering modes and their tradeoff (real time vs faster-than-real-time identical mix), and tells the agent what to do with the returned job ("jobs.wait until done"). It does not explicitly say when to prefer export_stems or agent_export_preview over this, so exclusion guidance is missing.

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

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

Goes well beyond annotations by explaining that rendering is offline/faster than real time, that each stem is a soloed track including send returns but excluding the master chain unless through_master, the file naming pattern, and that the tool returns a job whose result lists files (valuable since no output schema exists). It does not address file-overwrite behavior or failure cases, but annotations already cover the non-destructive safety profile.

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

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

Front-loads the action and output ('Render one WAV per track ... into a folder') and every clause carries information. The opening sentence is long and multi-clause, which slightly hurts readability, but nothing is redundant.

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

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

For a file-writing operation with no output schema, the description covers the essential gaps: the return value (a job with a result file list), the exact file naming, and the default stem composition. Overwrite semantics and prerequisite that the folder must exist are left to the schema, which is acceptable given full schema coverage.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantive meaning: what a 'stem' includes compositionally, what through_master actually changes about the output, and that 'tracks' defaults to every non-group track. It adds no detail for dither, bit_depth, or start/end beats, leaving those entirely to the schema.

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

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

States a specific verb and resource: 'Render one WAV per track ... into a folder', which unambiguously identifies per-track stem export. It does not, however, distinguish itself from siblings like export_render (presumably a full mixdown) or audio_split_stems (separation of imported audio), so an agent must infer the boundary.

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

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

Usage is implied by 'all audible tracks, or the ones listed' and the master-chain toggle, giving a sense of when this is the right export mode. But there is no explicit when-to-use/when-not guidance and no named alternative (export_render, audio_split_stems), so routing remains inferential.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds real domain context beyond that: the exact set of groove attributes returned (style, amount, grid, accent, lean, humanize) and the per-track opt-out semantics that determine whether a clip actually follows the groove.

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

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

A single compact sentence with the resource scope front-loaded and the field list trailing; nothing is wasted. The semicolon-and-parenthetical packing is slightly dense but still readable in one pass.

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

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

With no parameters and no output schema, the description carries the burden of describing the return value and does so by naming the groove fields plus the track-level exception. It stops short of stating the response shape (a single groove object with a list of straight-playing tracks), which would have closed the last gap.

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

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

The tool takes zero parameters, so the baseline of 4 applies and there is nothing for the description to clarify beyond the returned content, which it does list.

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

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

The description identifies the resource precisely (the project-level groove) and enumerates its fields, and the parenthetical 'unless its track opts out' plus 'which tracks play straight' separates it from groove_set_track. It never states the verb (read/return), relying on the name 'groove_get' to imply retrieval, which keeps it just short of a 5.

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

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

Usage is only implied through the get/set naming family — nothing says 'use this to inspect current groove before changing it with groove_set' or when to prefer groove_set_track. An agent can infer this is the read-side of a groove pair, but the description provides no explicit when/when-not guidance.

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

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

Annotations already declare non-destructive, idempotent writes, so the description doesn't need to repeat safety. It adds real value beyond that: patch semantics ('fields left out stay'), the interaction rule for style defaults, and 'Undoable', which tells the agent it can reverse the change via edit_undo.

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

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

Front-loaded with the action and patch semantics, then the parameter enumeration and the default rule. It is dense and efficient, though the parameter list largely restates enum values already in the schema.

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

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

For an 8-param optional-field mutation with full schema coverage and no output schema, the description covers what changes, what stays, default resolution, and reversibility. It stops short of saying whether the groove applies to already-recorded clips or only future playback, which would be the one remaining gap.

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

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

Schema coverage is 100%, so each parameter is already documented; baseline would be 3. The description earns above-baseline credit by stating the cross-parameter rule that selecting a style without amount or grid inherits the style's own values, which the schema cannot express.

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

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

States a specific verb and resource ('Change the project groove') with a scope qualifier ('project') that implicitly separates it from the sibling groove_set_track. It doesn't name the sibling outright, but an agent can tell project-level vs track-level apart from the wording alone.

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

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

Usage is implied by 'project groove' and the sibling name groove_set_track, but the description never says when to prefer this over the per-track variant or when to use groove_get first. The default-behavior note ('Picking a style without amount or grid takes the style's own') is helpful behavior, not routing guidance.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, so the description does not need to restate safety. It does add two things beyond them: that the change is undoable (pointing at edit_undo) and the concrete playback consequence of false (a straight bass under swung hats). It stops short of saying whether the change is audible immediately during playback.

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