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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond that with the caveat that an adapter record does not prove a loaded copy is writable, plus the offline framing and the contents of the returned knowledge.

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 tight sentences with the purpose front-loaded and the caveat/alternative following. Minor overlap between 'knowledge' and the enumerated 'controls, adapters', 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?

An output schema exists, so return values need not be explained, and the description still covers purpose, the key semantic caveat, and the sibling relationship. It is complete enough for an agent to call this correctly without opening the schema.

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

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

Schema coverage is 100% and the single product_id parameter is already well documented (exact id, not a display name). The description adds no syntax or format detail beyond the schema, 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?

States a specific verb and resource ('Read one Plugin Atlas product') and enumerates the payload (vendor, controls, adapters, alternatives), which distinguishes it from the multi-result atlas_search/atlas_recommend siblings. It also names atlas_match_loaded as the related tool, though it does not explicitly contrast itself with atlas_search.

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 context ('Offline and read-only') and an explicit alternative for a related goal ('join catalog knowledge to live targets with atlas_match_loaded'). It does not spell out when-not-to-use conditions, but the routing to the sibling is concrete enough to be actionable.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description still adds real value beyond them: it explains that it reads the live inventory, that each row includes a control-adapter status, and that a match is not proof of ownership or writable controls.

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

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

Front-loaded with the purpose, then scope, then caveat and next step; every sentence carries information. It is a little dense across four wrapped sentences but nothing 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?

With an output schema present the description need not detail return shape, yet it still sketches what comes back (target, candidate products, adapter status). Scope limits, uncertainty caveat, and the confirmation path are all covered, leaving no practical gap for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description does summarize all three knobs (only_used limits mixer tracks, match_limit caps candidates, include_weak adds uncertain matches) and frames them as bounded matching options. Its summary is slightly less precise than the schema's own notes, so it adds context rather than new semantics.

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

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

States a specific verb+resource pair (identify the open project's loaded plug-ins against Plugin Atlas) and distinguishes itself from plugin_list_loaded by naming the Atlas-matching dimension. 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?

Gives clear context (inspect loaded inventory and see candidate Atlas products per effect/instrument) and routes to a follow-up tool: 'confirm controls with plugin_list_parameters'. It does not, however, state when to prefer atlas_search or plugin_list_loaded instead, so the exclusion side 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior. The description adds genuinely non-obvious context beyond that: it is 'offline static knowledge: not proof of availability or ownership,' and stock-alternative mode 'uses that product and limit instead of normal recommendation criteria.' It doesn't discuss result ordering or failure behavior, 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?

Four dense sentences, front-loaded with the core action, then mode mechanics, then the key caveat, then the follow-up tool. No filler or restatement of the title.

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

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

An output schema exists, so return-value detail is not needed. The description covers both modes, the parameters that trigger each, the reliability caveat about static data, and the natural next step (sound_plan_palette), which is everything an agent needs to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds relational meaning the schema states only in fragments: that product_id is meaningful only with stock_alternatives=true, that limit bounds results, and that prefer_stock favors stock plug-ins 'without asserting licensing.' The nested request wrapper is also clarified by the goal-criteria framing.

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: 'Rank Plugin Atlas products for a production problem or technique.' The two operating modes (normal ranking vs. stock-alternative lookup) further pin down what the tool returns, distinguishing it from atlas_search and atlas_get_product. It stops short of naming those siblings explicitly, so it's clear but not fully differentiated by name.

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

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

Gives concrete mode-selection rules: normal mode is driven by query/problems/techniques/sources/kind, while 'product_id and stock_alternatives=true' switches to listing stock alternatives. It also routes the agent onward ('Use sound_plan_palette to assign sounds from what is loaded'). No explicit when-not-to-use or named alternatives among atlas_* siblings, so it lands at a strong 4.

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 readOnly, idempotent, non-destructive, and closed-world (openWorldHint=false). The description adds genuinely useful context beyond them: the catalog is bundled/offline, requires no FL connection, and search hits do not imply installation or ownership. It does not mention pagination or result ordering, but the safety/behavior profile is well covered.

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

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

The scoping statement and the offline/no-ownership caveat are front-loaded, followed by a compact enumeration of filters and a routing sentence naming the three alternatives. Every sentence carries information; nothing is redundant with 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?

An output schema exists, so return-shape detail is unnecessary. The description covers the tool's offline nature, the meaning of a hit, the filter set, and the sibling alternatives an agent might otherwise confuse it with, which is everything needed to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents every filter, its default, and its bounds. The description only paraphrases the schema by listing which fields narrow results and that limit caps hits, adding no format or edge-case detail beyond it. Baseline 3 applies when the schema does the heavy lifting.

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 (Search) and resource (the bundled offline Plugin Atlas for products) and explicitly scopes it with 'by text and filters'. It also differentiates itself from siblings by naming atlas_get_product, atlas_recommend, and atlas_match_loaded with their distinct roles.

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

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

Explicitly routes the agent: atlas_get_product for one product's details, atlas_recommend for a production goal, atlas_match_loaded to identify plug-ins in the open project. It also sets the expectation that no FL connection is needed and that a hit does not mean the product is installed or owned.

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 read-only, idempotent, non-destructive behavior, but the description adds meaningful context beyond them: it clarifies that only a rendered file is analyzed and live FL output is inaccessible. It also enumerates outputs at a high level, though it does not discuss rate limits or authentication, so it stops short of full behavioral disclosure.

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

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

The description is front-loaded with the core purpose in the first sentence, then adds useful routing and return-context sentences. The return-value list is somewhat lengthy given that an output schema exists, but it still helps an agent understand the tool's scope without wasting words.

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

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

Given a read-only measurement tool with an output schema and safety annotations, the description supplies what an agent needs: purpose, a limitation (no live output), and explicit alternatives. Return values are covered by the output schema, so the description is complete without duplicating them in detail.

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 all three parameters are fully documented in the input schema. The description only alludes to 'optional pitch' and does not add syntax, format, or constraint details beyond what the schema already provides, making the baseline 3 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?

First sentence names a specific verb (Measure) and concrete resource (one rendered file) plus the measured attributes, so an agent immediately knows what the tool does. The later sentences explicitly name the sibling tools it differs from (audio_diagnose_mix, audio_compare_files, audio_list_recent_bounces), enabling correct selection without opening schemas.

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

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

The description states a clear operating constraint (reads the file only; FL's live output is not available) and explicitly routes the agent to alternatives for diagnosis, reference comparison, and finding the latest export. This provides both when-to-use and when-to-use-another-tool guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered; the description reinforces this with 'changes nothing' and adds behavioral detail the annotations do not: the sample-synchronous requirement and the conditional nature of the suggested remedies ('when the evidence is actionable').

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

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

Front-loads the purpose in one sentence, then compactly covers what it reads, what it changes, what it returns, and the alternative tool. No wasted sentences.

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

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

With an output schema present, the description needn't detail return values, yet it still summarizes the per-band overlap and margin output. The sample-synchronous precondition and the alternative tool are covered; only explicit failure/edge-case behavior is absent, which is minor.

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 (including the max_seconds bound). The description adds only the 'sample-synchronous' qualifier on the stems, which is meaningful but marginal beyond the schema 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?

States a specific verb (measure) and resource (instrumental masking of a vocal), and explicitly names the sibling audio_diagnose_mix as the tool for judging the full mix. An agent can distinguish it from other audio_* tools without opening any schema.

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

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

Provides clear usage context: it is for per-band masking between two sample-synchronous stems, and directs the agent to audio_diagnose_mix for full-mix judgement. It does not state explicit exclusions (e.g. what it cannot do with non-synchronous stems beyond the implication), so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuine behavioral depth: alignment, loudness matching, per-band measurement over common overlap, bounded review ranges, and the condition under which actionable is false. The 'suggestions are starting points, not targets' caveat is a useful expectation-setting detail beyond structured fields.

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

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

Purpose is front-loaded in the first sentence, followed by the read-only guarantee and then the mechanics. Five sentences, each carrying information, with no filler or repetition of the title.

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

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

An output schema exists, so return-value explanation is not required, and the description still surfaces the key output concept (the actionable flag and bounded per-band ranges). Combined with annotations covering safety and idempotency, an agent has everything needed to call this 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%, so the schema already documents reference_path, candidate_path, and max_seconds in detail. The description adds no parameter-level syntax, format, or range information beyond what the schema provides, 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?

States a specific verb and resource: compares a candidate render against a reference and outputs tonal adjustment suggestions. Clear and non-tautological. However, it never distinguishes itself from adjacent siblings like audio_analyze_file, audio_diagnose_mix, or review_compare, so sibling differentiation is absent.

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 candidate-vs-reference framing and it discloses that the actionable flag is true only when alignment/readiness checks pass. But it gives no explicit when-to-use vs. when-not guidance and names no alternative among the audio analysis tools, leaving selection 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, idempotentHint, and destructiveHint=false, so safety is covered; the description reinforces this ('Reads the files; changes nothing') and adds genuinely non-obvious semantics: passing means technical, not artistic, approval. It does not mention cost/latency or the 600-second default bound beyond what the schema says, 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, front-loaded with the core action, then behavior, then the interpretation caveat and workflow note. Every sentence carries information and none is redundant padding.

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

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

With an output schema present, the description need not describe return values, and with 100% schema coverage and full annotations it need not restate parameters. What it does add — the non-artistic-approval caveat and the re-export/re-run workflow — is exactly the missing context, making it complete for a six-parameter diagnostic tool.

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

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

Schema description coverage is 100%, so every parameter (target enum, candidate_path, vocal_path, reference_path, instrumental_path, max_seconds) is already documented in the schema. The description only loosely gestures at the optional comparison and masking inputs and adds no format or constraint 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 and resource (diagnose a rendered mix) plus the comparison basis (technical thresholds for a delivery target), and enumerates the output shape (issues with severity, measurement, threshold, recommendation, export-readiness). It does not name the overlapping siblings (audio_compare_files, audio_analyze_masking, audio_analyze_file) even though its optional reference/masking features overlap with them, so it falls short of the 5 benchmark for sibling differentiation.

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

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

Gives clear situational context: it is a post-export check, and after project changes the user must export again and re-run it. No explicit when-not or named alternative tools are given, so it stops short of the 5 level.

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 explicitly states "Reads the file only" and explains the return format (best tempo/key with confidence, ranked candidates, ambiguity note to handle half/double-tempo readings). Annotations already confirm readOnly, idempotent, non-destructive, so the description adds valuable output-shape context without contradiction.

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

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

Three concise sentences, front-loaded with purpose, then behavior, then usage. No wasted words; each sentence adds distinct 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?

Given the simple two-parameter schema and existing output schema, the description covers what the tool does, how it behaves (reads only, returns confidences and ambiguities), and when to use it. Complete for an agent 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 coverage is 100%, so parameters are documented in the schema. The description doesn't add new parameter semantics beyond what the schema provides, which is appropriate given the high coverage. Baseline 3.

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

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

Specific verb (Estimate) and resource (tempo and major/minor key) with clear scope including ranked alternatives. Distinguishes itself from siblings like audio_analyze_file or audio_transcribe_melody by focusing on tempo/key estimation specifically.

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

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

"Use it to match a sample or reference before composing" gives a clear context for when to use it. It doesn't explicitly name alternatives or exclusions, but the use case is well-defined relative to other audio tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the description's 'Read-only' line is largely redundant. The genuinely additive behavioral context is the folder scope of the scan and the instruction to confirm the file with the user; ordering and limits are already in the schema. Moderate value beyond annotations.

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

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

Two sentences, zero filler, and the core action is front-loaded ahead of the usage note. Every sentence earns its place.

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

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

An output schema exists, so return-value explanation is unnecessary. Purpose, usage context, and scan scope are covered; only minor detail (e.g., what happens on an empty result or how results are grouped by folder) is absent, which is acceptable for a read-only list tool.

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

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

Schema description coverage is 100% for the single 'limit' parameter (default 20, min 1, max 200, newest-first semantics all documented). The description adds nothing about the parameter, so the schema carries the load and 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 ('List') and resource ('newest audio files') and pins down the exact search space (Rendered, Audio, Projects folders). No sibling tool lists recent renders, so an agent can distinguish it from audio_analyze_file or audio_compare_files without opening a schema.

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

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

Explicitly states when to use it: 'find the user's latest export before measuring it with the other audio_* tools,' and adds the operational caveat to confirm the file with the user. It does not name a specific alternative lister or state when-not-to-use, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, and the description usefully reinforces 'Reads the file only' plus a quality caveat (polyphonic material transcribes poorly). It stops short of noting runtime/rate characteristics or how failure modes look, but with annotations carrying the safety profile this is solid added context.

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

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

Front-loaded with the action, then constraints, then downstream routing; every sentence earns its place. Slight redundancy between 'monophonic recording (a sung or played line)' and the closing 'give it one isolated line', which costs a point.

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

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

With an output schema present, return values need no explanation, and the description covers input prerequisites, scope limits and the next step in the workflow. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so every parameter including fmin/fmax, tempo_bpm, quantize_grid_beats and minimum_note_seconds is already documented in the schema. The description only alludes to beat-positioning ('note sequence in beats'), adding no syntax or format detail beyond the schema — baseline 3 is appropriate.

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

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

States a specific verb and resource ('Transcribe a monophonic recording ... into notes') and immediately scopes it against siblings like audio_analyze_file and audio_estimate_tempo_and_key by naming the input constraint (one isolated line) and the output form (note sequence in beats). An agent can tell what this does without opening the schema.

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

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

Explicitly states when not to use it ('Chords and full mixes transcribe poorly; give it one isolated line') and routes the agent downstream to piano_roll_write_notes or compose_export_midi, which makes the place in the workflow unambiguous.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=false), the description discloses the concrete mechanism (sends one REC event at the current song position), the reported before/after values, and a critical limitation: whether an automation point was actually created cannot be read back. That non-verifiable write behavior is exactly the kind of trait an agent needs and annotations cannot convey.

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

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

Front-loaded with the core action, then prerequisites, then mechanism, then limitation, then alternative. Every sentence carries distinct load with no 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?

Prerequisites, mechanism, and the read-back limitation are all covered, and an output schema exists so return-value details need not be restated. Complete for a destructive, non-idempotent recording tool.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters including enum semantics for property and target_kind. The description adds no additional parameter-level meaning (e.g., expected_before's refuse-on-change semantics or allow_master's gating) beyond what the schema states, 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+resource+scope ('Record one automation value into FL while playback and recording run') and immediately distinguishes it from sibling setters by naming mixer_set_track and channel_set as the non-recording alternative. An agent can tell this apart from transport_set, mixer_set_track, and channel_set without opening a schema.

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

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

Explicitly states the when (writing a control change into the arrangement as automation), the prerequisites (write mode required, FL must already be playing with recording armed, set via transport_set), and the alternative path (mixer_set_track/channel_set to set a value without recording). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the 'Read-only' line is partly redundant. However, the description adds real behavioral context the annotations cannot: the returned digest, its role as an optimistic-concurrency token that makes edits refuse on change, and the current-pattern constraint.

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, front-loaded with purpose, then return/behavior, then the prerequisite. Every sentence earns its place with no filler.

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

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

Even though an output schema exists, the description usefully explains the digest's downstream purpose, and it covers the prerequisite and read-only nature. Nothing an agent needs to call this correctly or chain it with channel_set_steps 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 both parameters are already documented (channel_index from channel_list, pattern_number must be FL's current pattern). The description reinforces the 'current pattern' constraint but adds no syntax or format detail beyond the schema; 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+resource ('Read one channel's step-sequencer grid') and scope ('in the current pattern'). Clearly distinguishable from channel_set_steps and pattern_list without opening a schema.

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

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

Explicitly ties usage to a companion workflow: it tells the agent to pass the returned digest as channel_set_steps' expected_digest. It also states the prerequisite that the pattern must be the current one and names pattern_set(select=true) to satisfy 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered; the description's 'Read-only.' is largely redundant. It does add useful behavioral context beyond annotations: the full set of returned attributes and the channel_fingerprint's role as an optimistic-concurrency guard for channel_set.

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

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

Purpose is front-loaded in one sentence, followed by a compact field inventory and a single sentence of cross-tool usage guidance. The only mild waste is restating 'Read-only' that the annotations already declare.

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

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

An output schema exists, so the description need not enumerate return fields, yet the enumeration and the index/fingerprint guidance give the agent everything needed to chain into channel_set, channel_get_steps, and piano_roll. No missing precondition or failure-mode information of significance for a zero-arg read tool.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. It correctly adds no spurious parameter discussion.

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

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

The first sentence gives a specific verb (List) and resource (every Channel Rack channel) plus the scope of data returned (mix, routing, generator). It is clearly distinguishable from siblings like channel_get_steps, mixer_list_tracks, or pattern_list, which cover different resources.

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 tells the agent what to do with the returned index and fingerprint (feed them to channel_set, channel_get_steps, piano_roll, plug-in targets), which implies this is the read step preceding those calls. However, it never explicitly states when to call this tool versus alternatives, and no exclusions or preconditions 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?

Adds substantial context beyond the annotations: a bounded note-on/note-off pair, nothing recorded or saved, project unchanged, write-mode requirement, and the crucial caveat that the receipt confirms dispatch only since FL has no getter for what was heard. The only gap is that the concurrency guards (expected_before/session_fingerprint) are left entirely to the schema.

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

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

Three tight sentences, front-loaded with the action, then the persistence/side-effect statement, then the routing alternative. No filler or repetition of schema content.

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

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

An output schema exists, so return values need no explanation, and the description still covers the non-obvious behavioral facts (write mode, no persistence, receipt semantics) for what is effectively a side-effecting audition tool.

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

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

Schema description coverage is 100% and every parameter already carries a description, so the schema does the heavy lifting. The prose adds no syntax or format detail about note, velocity, duration_ms, or the guard parameters, 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+resource+scope: 'Play one short note on a channel so the user can hear the sound.' It is immediately distinguishable from siblings like piano_roll_write_notes and compose_melody, which persist notes rather than audition 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?

Explicitly names the alternative and the condition that selects it ('To add notes to the project, use piano_roll_write_notes'), and states the precondition 'Requires write mode.' Both when-to-use and when-not-to-use are covered.

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

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

Goes well beyond the annotations (destructive/non-idempotent/write), disclosing write ordering, per-write readback on a later FL tick with its own receipt, the meaning of 'verified', non-atomic failure semantics, and that it does not save. This is exactly the behavioral context an agent needs for a destructive multi-field 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?

Front-loads the core action, then conditionally layers constraints, execution semantics, and sibling routing in a tight sequence. Every sentence carries distinct information with no 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 13-parameter destructive mutation with an output schema present, the description covers precondition, execution model, failure behavior, and boundaries against sibling tools. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already carries per-parameter detail; the baseline would be 3. The description adds the 'set only the fields to change' contract and the write-order semantics, which meaningfully frame how the many optional fields interact, but it does not add per-field syntax 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 ('Change any combination of one Channel Rack channel's settings in one call') and enumerates exactly which fields it touches. It also differentiates itself from siblings by naming the tools that handle the channel's instrument, step grid, and notes.

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

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

Explicitly states the precondition ('Requires write mode (session_set_write_mode)') and routes the agent to alternatives ('Use plugin_set_parameter for the channel's instrument, channel_set_steps for its step grid, and piano_roll_write_notes for its notes'). Nothing about when to pick this tool 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 destructive/no-idempotent, but the description adds the mechanism behind them: an expected_digest optimistic-concurrency guard that refuses the edit if the grid changed, readback of changed cells on a later tick, and that nothing is persisted. This is substantive behavior beyond the structured hints.

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 tight sentences: purpose first, then prerequisites, then the guard's rationale, then the sibling pointer and the no-save caveat. No sentence 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?

An output schema exists, so return values need not be spelled out; the description still notes changed cells are reported back. With a 5-param destructive tool, the prerequisites, guard, and no-save behavior are all present.

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

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

Schema coverage is 100%, so baseline is 3, but the description explains why expected_digest exists ('refuses if the grid no longer matches expected_digest') and ties the fresh-read requirement to it, adding meaning the schema field text does not convey.

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 ('turn ... on or off') and resource ('step-sequencer cells for one channel in the current pattern'), and explicitly differentiates from piano_roll_write_notes for pitched notes. An agent can place it precisely without opening the schema.

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

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

Gives the preconditions (write mode plus a fresh channel_get_steps read), names the alternative tool and the condition selecting it ('for pitched notes and lengths'), and notes it does not save so the caller knows a save step follows.

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 non-open-world. The description adds value beyond them: determinism for a given seed, that it runs 'without touching FL' (no project side effects), and that it returns a note sequence in beats rather than writing anything.

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 purpose, followed by determinism and integration notes. Every sentence earns its place with no filler.

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

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

An output schema exists, yet the description still summarizes the return ('note sequence in beats') and names consumers. Combined with the determinism and FL-safety notes, an agent has everything needed to call it correctly and use the result.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic meaning beyond the schema by tying the progression parameter to compose_chord_progression's progression and key, clarifying that these must match for coherent output.

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 ('Generate a bass part'), names the input model ('Roman-numeral progression'), and distinguishes itself from compose_chord_progression, compose_melody, and compose_drums. An agent can tell what it produces without opening the schema.

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

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

Explicitly routes the agent: reuse the same progression and key as compose_chord_progression so parts agree, and points to downstream consumers (piano_roll_write_notes or compose_export_midi). It gives clear context but no explicit when-not-to-use guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuine extra context: determinism ('same inputs give the same notes'), the return shape (a note sequence in beats with a digest), and that it does not touch FL.

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 core action, then behavior, then integration. No filler and every sentence earns its place.

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

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

Complete for a generator whose output schema exists: it still describes the return (note sequence in beats with a digest) and points at the follow-up tools. An agent has everything needed to call it and route its output 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%, so all nine parameters (root, octave, voicing, velocity, tempo, collection, progression, beats_per_chord, custom_intervals) are already documented in the schema. The description adds no format or syntax detail beyond what the schema provides, 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+resource (generate voice-led chords) with the input domain (Roman numerals in a key) and the scoping constraint 'without touching FL'. This clearly separates it from compose_melody, compose_bassline, and compose_drums.

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 downstream workflow by naming the three tools that consume the output (piano_roll_write_notes, compose_export_midi, compose_bassline) and clarifies it produces data rather than mutating the DAW. It does not explicitly contrast when to pick this over compose_melody, so it stops short of full when/when-not 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 readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds value beyond them: determinism for a given seed, the General MIDI fallback and its mismatch risk with many FL kits, and the output shape. It does not restate the annotations, which is correct.

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 segments: purpose, determinism, then the drum_map caveat and return value. Front-loaded with the verb and resource; no filler, and every sentence carries operational weight.

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 output schema covers return values, annotations cover safety, and the description still supplies the chaining target (piano_roll_write_notes), the GM fallback caveat, and determinism. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining the consequence of omitting drum_map (GM notes that FL kits may not follow) and reinforcing seed determinism, adding decision-relevant meaning rather than restating field 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 (Generate), an explicit resource (kick, snare, and hat patterns), and a scope boundary ('without touching FL'). An agent can distinguish it from compose_melody, compose_bassline, and compose_chord_progression without opening any schema.

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

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

Gives real workflow guidance: read pads via plugin_get_pad_map and plan sounds first so hits land on the right pads, and names piano_roll_write_notes as the downstream consumer. It falls just short of explicit when-not-to-use, but the drum_map caveat effectively tells the agent when the default path is unsafe.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description adds real context beyond them: the write is local-file-only with the FL project unchanged, the file is re-opened and parsed to verify digest/tracks/events, and replacement of an existing file is refused unless overwrite=true. That discloses what is destroyed and under what condition, consistent with the annotations.

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

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

Three tight paragraphs, front-loaded with the core action, then the side-effect scope, then the alternative. Every sentence carries information; none 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?

An output schema exists so return values need not be explained, and the description covers the mutation's side effects, verification behavior, and the sibling alternative. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and every parameter (path, tracks, ppq, tempo_bpm, numerator/denominator, overwrite) is already documented in the schema. The description adds no format or syntax detail beyond what the schema provides, 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?

Specific verb+resource+format: 'Write note sequences to a standard Type-1 MIDI file and verify it.' It also explicitly contrasts with the sibling piano_roll_write_notes, so an agent can distinguish this from the in-project note-writing tool 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?

Explicit when-to-use routing: 'use piano_roll_write_notes to put notes in the open project instead,' plus the drag-into-FL workflow and the overwrite gating condition. Both the alternative and the selecting condition 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/idempotentHint true and openWorldHint false; the description reinforces this with 'without touching FL', which is consistent rather than contradictory. It adds genuinely new behavioral context beyond the annotations: seed-based determinism and the fact that output is a note sequence in beats.

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 core action, then determinism, then return shape, then integration. No filler or restatement of the title.

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

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

With an output schema present the description need not explain return values, and annotations cover the safety profile; the description supplies determinism, scope, and the downstream write step. Complete enough to call correctly, though it doesn't tie collection/scale choice to the register-fit advice it gives.

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% across 11 params, so the schema carries the load (root, collection, contour, density, register bounds are all documented there). The description only echoes 'register' and 'seed' semantics, adding determinism context for seed but no new parameter meaning. Baseline 3 is correct.

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 ('Generate a scale-aware melody within a register') and adds a scoping constraint ('without touching FL') that separates it from the sibling compose_* and piano_roll_write_notes tools. An agent can identify it immediately without opening the schema.

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

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

Gives real workflow context: fit the register to the sound via sound_plan_palette before writing with piano_roll_write_notes, and change the seed for alternatives. It stops short of stating when not to use it or naming alternatives like compose_bassline/compose_chord_progression explicitly, so no exclusion criteria.

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, so the safety profile is covered. The description adds genuinely useful non-annotation behavior: the watch keeps running after the read, and watch lifetime is process-local and ends on server restart — important operational context.

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

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

Three short sentences, front-loaded with purpose, then behavior, then lifetime constraint. No filler and every sentence earns its place.

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

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

With an output schema present, the return fields need not be explained, yet the description still names them (maximum peak, clipping frame count, last fader reading). Read semantics, lifetime, and the referenced sibling are all covered — nothing material is missing for a one-parameter read tool.

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

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

There is one parameter with 100% schema coverage, including a format pattern and a description pointing to mixer_start_peak_watch. The description adds no parameter detail beyond the schema, so the baseline 3 for a fully documented schema 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?

States a specific verb (Read) and resource (a peak watch's status and cumulative per-track peaks), and the scope is clear enough to distinguish it from mixer_start_peak_watch and mixer_stop_peak_watch. An agent can identify the tool's job without opening the schema.

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

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

The description clarifies the watch stays running after the read and that watches are process-local and end on MCP server restart, which frames when the tool is applicable. It does not explicitly compare against siblings such as mixer_stop_peak_watch, but the read-only framing is clear context.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond that: the expected_before guard workflow that explains why reading precedes writing, plus the normalized/dB duality of the fader.

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

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

Front-loaded with the core purpose, then supporting detail. There is mild redundancy in listing the return fields twice (level/pan/effects/EQ/sends then the fuller enumeration), but overall tight and well-ordered.

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 annotations, a 100%-covered single param, and an output schema present, the description carries the remaining burden well by adding the expected_before workflow rationale. Nothing an agent needs to call this correctly is missing.

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

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

Only one parameter and schema coverage is 100% – the schema already documents track_index as zero-based with index 0 being Master. The description adds no parameter-level detail, 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?

The description opens with a specific verb+resource: 'Read one mixer track's full state,' then enumerates the domains covered (level, pan, effects, EQ, sends). It distinguishes itself from the sibling mixer_list_tracks by scoping to a single track.

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

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

It explicitly names the sibling mixer_set_track and the condition that selects this tool: 'Read it before mixer_set_track to supply current values as expected_before guards.' This is concrete workflow routing, though it doesn't cover when-not-to-use or the list alternative.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the 'Read-only' line is largely redundant, but 'Index 0 is Master' is genuinely useful behavioral context the annotations don't convey. It stops short of describing ordering or pagination behavior, keeping it from a 5.

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

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

Two tight sentences, front-loaded with the returned content and follow-up routing. No filler; every clause either describes output or routes to a sibling tool.

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

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

An output schema exists, so return format needn't be explained, and the annotations cover the safety profile. Between the description, schema, and output schema, an agent has everything needed to call this 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%, so only_used, max_tracks, and include_peaks are already documented in the schema. The description adds no semantics beyond that, which is the correct baseline 3 when the schema carries the burden.

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 (list mixer tracks) and enumerates the returned fields: names, levels, mute/solo state, and loaded effects. It explicitly distinguishes itself from mixer_get_track and mixer_start_peak_watch, so an agent can choose correctly without opening schemas.

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

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

Gives explicit routing: use this to find track indices and effect slots before mixer_set_track or plugin tools; use mixer_get_track for a single track's EQ and sends; use mixer_start_peak_watch for levels over time. When-to-use and named alternatives are both present.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: nothing is applied, operations carry expected_before guards and a session_fingerprint, a rationale is emitted per track, and specific skip categories (muted, silent, Master, within 0.5 dB) are disclosed. Only minor overlap with the existing output schema keeps it from a 5.

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

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

Two tight paragraphs: the first sentence states the outcome, the second covers behavior and return shape, and the third covers the follow-up workflow. The read-only guarantee is front-loaded and nothing is padded.

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

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

For a planning tool with an output schema and full annotation coverage, this description supplies everything an agent needs: what it produces, that it is non-destructive, how to consume the result, and what to do afterward. No material gap remains.

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 all four parameters are already documented, and the description adds little syntax beyond implying a target peak and the Master-skip behavior tied to allow_master. max_adjustment_db and target_peak_dbfs semantics are left entirely to the schema. Baseline 3 is appropriate.

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

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

States a specific verb (propose) and resource (dB fader moves / gain staging) scoped to a peak watch, and immediately distinguishes itself from the mutating sibling project_apply_edits by declaring it is read-only planning. An agent can tell what it produces without opening the schema.

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

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

Gives a clear downstream workflow: review the operations, pass operations + session_fingerprint to project_apply_edits, then re-watch and re-bounce. This is strong contextual guidance, but it never states when to prefer this over alternatives like mixer_set_track or processing_plan, so it stops short of explicit when/when-not 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 cover the safety profile (destructive/non-idempotent/openWorld), and the description adds substantial context beyond them: writes execute in a stated order, each is read back on a later FL tick with its own receipt, verified is true only if all writes verify, the operation is non-atomic (earlier writes persist if a later one fails), and an unknown outcome halts the rest. This is exactly the behavioral detail an agent needs before invoking a destructive multi-write.

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

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

Front-loads the core action and field list, then adds verification/ordering semantics and sibling routing in descending priority. Dense but every sentence carries operational information; no filler.

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

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

An output schema exists, so return-shape explanation is unnecessary, yet the description still clarifies the receipt/verified model. For an 18-parameter destructive mutation with nested send/EQ guards, the description plus schema plus annotations give an agent everything needed to call it correctly.

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

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

Schema description coverage is 100% and the nested $defs document ranges, units, and guards thoroughly (volume_normalized '0.8 is 0 dB', color word layout, expected_before semantics). The description only re-enumerates the changeable fields and notes 'normalized or dB', adding little beyond the schema, so the baseline 3 is correct.

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

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

States a specific verb+resource ('Change ... one mixer track's settings in one call') and enumerates the mutable field set, so an agent can distinguish it from mixer_get_track, plugin_set_parameter, and project_apply_edits without opening a schema.

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

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

Names two explicit alternatives and the conditions that select them ('Use plugin_set_parameter for effect parameters and project_apply_edits for several tracks'), plus the prerequisite 'Requires write mode (session_set_write_mode)' and the note that it 'Does not save.' Nothing is left to inference.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), and the description adds meaningful context beyond them: it runs in the background in this MCP process, returns a first frame and watch_id, changes no project state, and that peaks are post-fader samples rather than audio analysis. It does not note the non-idempotent/non-repeatable nature or the interaction of concurrent watches, so it stops short of a 5.

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

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

Front-loads the action and its trigger, then the lifecycle and the semantic caveat. Every sentence is load-bearing, though the last sentence is dense with three distinct claims packed together.

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

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

Covers the full lifecycle (start, read, stop), the return value despite an output schema existing, the no-side-effect guarantee, and the semantic caveat that peaks are post-fader samples. An agent has everything needed to invoke and follow up 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% with defaults and ranges on all four parameters, so the schema carries parameter meaning. The description adds no parameter-specific guidance (e.g. how duration_seconds or interval_ms interact with sampling fidelity), 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 and resource ('Start sampling mixer peak meters') plus the operational context ('while the user plays the song'). It also names the sibling tools it pairs with (mixer_get_peak_watch, mixer_stop_peak_watch, mixer_plan_gain_staging), so it is clearly distinguishable from 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?

Gives an explicit workflow: start the watch, ask the user to play the section, then read with mixer_get_peak_watch or end with mixer_stop_peak_watch. It also specifies the downstream use case (mixer_plan_gain_staging to propose fader moves), which routes 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?

Annotations declare readOnlyHint=false with destructiveHint=false, and the description usefully clarifies that the stop 'changes no project state' and that the watch stays readable afterwards. That is real lifecycle context beyond the annotation flags. It does not explain whether stopping an already-stopped watch is an error (relevant given idempotentHint=false), leaving a small gap.

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

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

Two short sentences, front-loaded with the action and the return value, then the state and lifecycle consequences. No filler.

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

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

For a one-parameter terminal action with an output schema, the description covers action, state impact, and downstream usability, so return-format detail is correctly omitted. Only the repeat-call/idempotency 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?

There is a single parameter with 100% schema description coverage; the schema already documents the watch_id format and its origin tool. The description adds nothing about the 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?

States a specific verb and resource ('Stop a peak watch') plus the effect of stopping ('return its final per-track aggregate'). This clearly separates it from mixer_start_peak_watch and mixer_get_peak_watch, which an agent can distinguish without opening any schema.

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

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

'Stop a peak watch early' tells the agent the condition for using this rather than letting a watch finish, and the note that a stopped watch remains readable via mixer_plan_gain_staging clarifies the downstream workflow. It stops short of explicitly naming when to prefer mixer_get_peak_watch or mixer_start_peak_watch, but the context is clear.

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

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

Adds substantial behavior beyond the annotations: it discloses the write-mode authorization requirement, that the target slot is chosen by searching from start_pattern_number for a slot FL reports as empty (so existing patterns are not overwritten), that each step is verified with an 'outcome' field naming the first unverified step, and that the result is not persisted ('Does not save'). None of this is derivable from destructiveHint/idempotentHint alone.

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 verb and a one-line summary, followed by the precise operational detail and the alternative-tool pointer. Every sentence carries new information; the short summary-plus-detail structure aids scanning without 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?

Covers preconditions, side-effect scope, verification semantics, persistence behavior, and the sibling alternative. With an output schema present and 100% schema coverage, no essential information is missing for correct invocation.

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

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

Schema description coverage is already 100%, so the baseline is 3, but the description adds operational meaning: start_pattern_number defines the search origin for the first empty slot, and name/color/length map to the name-select-size sequence performed on that slot. It does not add syntax or format detail beyond the schema, so it stays just above 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?

States a specific verb and resource ('Create a pattern') and then enumerates the exact sub-steps (find first empty, select, name, size). It explicitly distinguishes itself from the sibling 'pattern_set', which handles modification of existing patterns, so an agent can route correctly 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?

Gives a real precondition ('Requires write mode') and names the alternative for the adjacent case ('Use pattern_set to change an existing pattern'). It does not spell out when creating a fresh pattern is the right move versus higher-level compose_* or piano_roll_* helpers, but the context is clear enough to select the tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description reinforces read-only but goes further by noting it reports whether each pattern is FL's default empty pattern, a non-obvious behavioral detail. It could add more about ordering or empty-project behavior, 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?

Two short sentences, front-loaded with the core purpose and followed by behavioral and usage notes. Efficient and well-organized, with minimal waste.

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

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

For a no-parameter list tool with an output schema present, the description covers purpose, read-only nature, the default-empty-pattern flag, and integration with sibling tools. Context is sufficient for correct invocation, though ordering/details are not mentioned.

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 usefully names the fields returned (name, color, length, current), which helps an agent understand what data is available even though no input parameters exist.

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?

Clearly states verb+resource: 'List the project's patterns' and names the reported fields (name, color, length, current). It also distinguishes itself from siblings pattern_create and pattern_set by explaining its read-only listing role and how the returned pattern numbers are consumed.

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

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

Explicitly says to use the returned pattern numbers with pattern_set, channel_get_steps, and the piano_roll tools, and routes creation to pattern_create. It gives clear context for when to use this tool versus creation/setting tools, but doesn't state when-not to use it or 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 flag destructive/openWorld/non-idempotent, and the description adds substantial non-obvious behavior: the fixed write order (name/color, length, selection), per-write readback on a later tick with individual receipts, the meaning of 'verified', non-atomicity, and that it does not save the project. This is exactly the kind of context annotations cannot convey.

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

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

The purpose is front-loaded in one line, followed by tightly packed clauses covering mode, sequencing, verification, atomicity, the sibling alternative, and persistence. Every sentence carries information with no filler.

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

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

With an output schema present, return-value explanation is not needed, and the description still covers the write-mode requirement, non-atomicity, the verified flag's semantics, and persistence behavior. For a destructive multi-field mutation, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds param-relevant semantics: that only changed fields should be supplied and the ordering in which the changed fields are applied. It does not add further format detail, but it meaningfully frames how the parameters interact.

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

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

The first sentence names specific verbs (rename, recolor, resize, select), the resource (one existing pattern), and the scope (one call), and explicitly distinguishes itself from pattern_create. An agent can tell it apart from sibling tools without opening any schema.

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

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

It states the operational precondition ('Requires write mode'), the editing convention ('Set only the fields to change'), and routes to the alternative ('Use pattern_create for a new empty pattern'). It lacks explicit when-not conditions for other mutating siblings, so it stops just short of a 5.

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

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

Discloses behavior beyond the annotations: opening the score changes FL's focus, it never mutates notes or enables writes, and it requires a prior setup step. It also warns that a selected_only page can be empty yet still carry a next_offset, which is non-obvious and valuable. This reconciles the readOnlyHint=false annotation (the focus change is the side effect).

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

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

Front-loads the core purpose, then layers side effects, prerequisites, and paging guidance in short sentences. No filler; every sentence 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 an output schema present, return values need not be explained. The description covers the side effects, prerequisite, and pagination behavior an agent needs to invoke this correctly, leaving no meaningful 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 the baseline is 3. The description adds genuine meaning beyond the schema by explaining how offset/next_offset paging works and the corner case where selected_only returns an empty page with a valid next_offset.

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

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

States a specific verb (Read) plus the precise resource and scope: notes of one channel in one pattern, and enumerates the fields returned (pitch, timing, expression). This clearly distinguishes it from siblings piano_roll_write_notes and piano_roll_transform_notes.

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

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

Gives a concrete usage context (read before composing around or transforming existing material) and states the prerequisite (piano_roll_setup must be done once). It does not explicitly name the alternative sibling tools or state when not to use it, so it falls short of a 5.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, and the description correctly frames this as a setup write that "Writes no notes." The description adds real context: what prepare actually writes, that confirm arms the process, and that status doesn't touch files. It stops short of covering error/failure paths, so a 4 rather than 5.

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

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

Front-loaded with purpose, then action-by-action behavior in compact prose. Slightly dense in the middle but every sentence contributes.

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 annotations already cover the safety profile and an output schema exists, the description supplies exactly the missing procedural context: prepare writes the script, the user must run it in FL, confirm arms the process, reuse for the session. An agent has everything needed to drive the setup correctly.

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