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

No annotations are provided, so the description carries the full burden, and it does: read-only pre-inspection, replace/fail semantics with the previous assignment returned, the partial-failure state when labelling fails, the fact that labelling RENAMES the sequence everywhere, and the serialisation caveat about other clients changing the executor between check and write. This is a mutation with complete 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?

Long and dense, but front-loaded with the primary command syntax and action before the branching rules, and every sentence carries non-obvious console semantics. Slightly bloated in the verify/security coda, but justified by the complexity.

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

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

No output schema exists, and the description compensates by describing what comes back (previous assignment on failure, alreadyAssigned:true, partial outcome) and precisely what verify does and does not check. Nothing an agent needs to call this correctly or interpret the result 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 baseline is 3, but the description adds real meaning on top of the schema: replace:true fails-with-previous-assignment otherwise, label renames the assigned object/sequence rather than the executor, and verify's scope (object name+class, plus displayed name when labelled). That goes beyond the schema's field-level text.

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

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

States a specific verb and resource ('Assign a sequence to an executor on an explicit page') and even gives the underlying manual syntax. An agent can immediately tell this apart from siblings like gma3_label_executor or gma3_configure_executor.

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 rich conditional context: when replace is needed, when the call fails (executor holds a different object), when it no-ops (alreadyAssigned), and what it deliberately does not do (no Go/On/Off, no fixture selection change). It never explicitly names a sibling alternative, however, even though gma3_label_executor overlaps with the label behavior described here.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it explains the console Preview environment, that nothing is output, that the Normal programmer is fingerprinted and never touched, per-fixture/step/layer validation, storage rules, step-by-step verification, clearing Preview in every case, exclusive requirement, and bridge version dependency.

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

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

It front-loads the purpose and every sentence is information-dense for a 14-parameter nested tool, but the single unbroken paragraph is difficult to scan. Headings or bullets would improve structure, so it is not a 5 despite containing no obvious waste.

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

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

With no output schema and no annotations, the description still covers side effects, state isolation, storage behavior, verification, preview output, exclusive locking, interruption recovery, and version requirements. It is complete enough for an agent to call the tool correctly.

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

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

Schema coverage is 100%, but the description adds substantial semantics beyond the schema: phase direction when from > to, repeat groups/wings/blocks along X, speed_master 1-16, template option shapes that the schema leaves as additionalProperties, audition release behavior, and the meaning of verify/existing. This is meaningfully richer than the structured fields alone.

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

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

The first sentence states a specific verb ('Build') and resource ('phaser'), plus the target preset and read-back behavior. It distinguishes structured steps from templates and is clearly separate from siblings like gma3_store_preset and gma3_phaser_release.

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

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

The description gives concrete usage conditions: preview true returns the plan, exclusive true is required unless previewing, audition_ms requires an empty Normal programmer, and interrupted builds are recovered with gma3_phaser_release. It does not explicitly state when not to use this tool or name alternative effect-building tools, so it falls short of a 5.

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

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

With no annotations, the description carries the full burden and does so thoroughly: exact readback comparison of every event, pre-send validation of sequences/cues, refusal of playing or locked shows, same-time events executed in storage order, and an explicit 'never sends Go, Record or anything that plays'. The bridge 0.25.0 requirement is also disclosed.

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

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

Sized appropriately for a complex nested-payload tool: nearly every clause carries load-bearing detail (rounding, ordering, pair checking, refusals). It is a single dense paragraph rather than a front-loaded structure, which makes scanning harder, but there is little genuine 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 9-parameter, nested-object, no-output-schema, no-annotation tool, this is unusually complete — it covers validation, failure modes, post-condition verification, and side-effect limits. It is missing semantics for the required top-level timecode, plus name, preview, and the top-level fps, which matter given the 0% schema coverage.

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

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

Schema description coverage is 0% across 9 parameters and nested objects, and the description compensates for most of it: mode, tracks.at formats (seconds, H:MM:SS.sss, H:MM:SS:FF with fps, {frames,fps}, 1/16777216 s rounding), the action enum's semantics including the gotcha that goto needs a cue and the press/release pair checking with allow_unpaired, and every settings field. Gaps remain for top-level timecode, name, fps, preview, and verify (the readback sentence only implies verify).

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 (build a timecode show) plus the scope (timed cue events), and the title's 'never plays or records' cleanly separates it from transport/playback siblings such as gma3_timecode_transport. An agent can tell what this does and what it deliberately does not do 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 three modes are given operational meaning (create refuses an existing show, replace removes its track groups but keeps the show, append adds a track group), which is real when-to-use guidance. It also states the precondition that sequences and cues are checked before anything is sent and that a playing or locked show is refused. It never names the sibling tool to use instead when you actually want playback, so it stops short of explicit alternatives.

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

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

With no annotations, the description carries the full load and does so well: it explains the exact effect on selection and programmer values for each mode, notes verification behavior (Selection.CountTotalSelected == 0), mentions that programmer values cannot be read back for 'active', and discloses serialization against other mutations. It stops short of covering error conditions or permission requirements.

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

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

The description is front-loaded with the core action and then efficiently details each mode. It is dense but avoids fluff; a bulleted format might improve readability, but the current one-paragraph structure is compact and information-rich.

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

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

For a single-parameter tool with no annotations and no output schema, the description is complete: it covers mode semantics, effects, verification, read-back limitations, and concurrency. An agent has everything needed to invoke it correctly without requiring additional context.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial meaning by describing the concrete consequences of each enum value (deselects fixtures, deactivates values, discards every programmer value) beyond the schema's brief mapping. This extra detail on effects makes it more useful than the schema alone.

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

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

The description states a specific verb (clear) and resource (programmer selection/values), and precisely distinguishes the three mode behaviors (selection, active, all) with exact command names. It does not explicitly differentiate from sibling tools like gma3_hardkeys_release_all or gma3_programmer, so it falls short of a 5.

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

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

The mode descriptions imply when to use each variant (e.g., keep values vs discard all), but there is no explicit guidance on when to choose this tool over sibling tools or any exclusions. Usage is therefore implied rather than stated.

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

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

No annotations are provided, so the description carries the full burden and does so: it discloses the return values (OK, Syntax Error, Illegal Command), the fact that output-producing commands write to console history instead, and that OSC transport yields no feedback. It also explains the retry semantics of the 'auto' transport (no resend after bridge acceptance).

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 examples, return values, and caveats in a logical order; each sentence carries information. It is dense but not padded, though it could be slightly tighter in the transport sentences.

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

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

For a two-parameter command-execution tool with no output schema and no annotations, the description covers everything an agent needs: invocation format, return signals, output-routing caveats, transport behavior, and the correct alternatives for reading data. Nothing material 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 the schema already documents both parameters, including the detailed 'via' enum and its fallback behavior. The description earns credit above baseline by supplying concrete command-syntax examples ('Fixture 1 Thru 10 At 50', 'Store Cue 2 /Merge /NoConfirmation') that clarify the expected format of the 'command' string beyond the schema's single example.

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 ('Execute a grandMA3 command-line command exactly as it would be typed') and immediately distinguishes its scope from siblings by noting that output commands like List print to console history rather than here, routing the agent to gma3_get_object / gma3_list_children. An agent can tell it apart from the ~60 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?

Explicit when-to-use (raw command-line syntax) and when-not (data reads should use gma3_get_object / gma3_list_children), plus a clear transport caveat that 'osc' is fire-and-forget with no feedback. Alternatives and selection conditions are named, not implied.

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

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

With no annotations, the description carries the full behavioral burden and does so richly: it never sends playback keywords, does not touch selection/programmer/fader levels, reads playback state before/after, refuses locked targets unless unlock:true (with re-lock semantics), and details the single 'set'-with-read-back write model, unknown-value handling and verify default true. This is unusually complete 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?

Purpose is front-loaded in the first clause, and essentially every sentence conveys a distinct behavioral fact. The prose is dense and clause-heavy, which costs some readability, but there is little wasted text.

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

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

For a 15-parameter mutation tool with no annotations and no output schema, the description covers prerequisites (executor must hold a sequence), validation, refusal conditions, write/verify semantics, lock interplay and even the read-back state it returns (playback.activeBefore/activeAfter, from -> to plan). 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 real meaning beyond the schema: functions are validated against the sequence lists, keys Flash/Temp/Swap/Black/Time are key-only, lock:false explicitly unlocks, and unlock restores locks afterwards. That said, most per-parameter value detail already lives in the schema.

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

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

States a precise verb and resource: setting KeyPress, MAKeyPress, fader, encoder and Fix functions of the sequence executor at Page <p>.<e> by writing its properties. It also distinguishes itself from nearby siblings by naming gma3_configure_sequence and contrasting with 'Assign <function> At'. An agent can tell what this tool does versus gma3_assign_to_executor and gma3_executor_settings.

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 sequence-level settings (Wrap Around, priority) to gma3_configure_sequence and confines executor settings here, notes the executor must hold a sequence, and documents the key-only function restriction. It also states the conditions governing lock/unlock, preview and verify.

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

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

With no annotations, the description carries the full burden and delivers: each set's reply must read back the requested value, the console silently ignores rejected values, the first failure stops the rest, a locked MAtricks is refused, and it does not touch the selection or programmer. This is unusually rich 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 purpose is front-loaded and every sentence carries operational content. It is dense and could be broken into clearer segments, but little is wasted.

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

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

For a 9-parameter nested config tool with no annotations and no output schema, the description covers creation, reset, verification, preview, failure/abort behavior, and the locked case. Nothing an agent needs to invoke it correctly appears to be missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: the wings distribution edge semantics (outer-to-centre) and a worked 'wings 2 with delay {from: <outer>, to: 0}' example for centre-out delay.

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: 'Set MAtricks <n> per axis (x, y, z)' and the title clarifies create-or-update. An agent immediately knows this configures a MAtricks object's axis parameters. However, it does not differentiate itself from the sibling gma3_matricks, leaving some ambiguity about which to pick.

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

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

Gives concrete operating context: create: true makes a missing object, reset_unspecified: true resets an existing one, otherwise only given settings change, preview: true reports planned changes, and 'apply it with Recall MAtricks <n>'. Clear usage context, though no explicit when-not or sibling comparison.

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

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

With no annotations, the description carries the full burden and does so richly: locked targets are refused before sending unless unlock:true (with re-lock attempted even on failure), preview performs only reads, verify reads back changed properties, a set reply without a value is an unknown step, and the first failure stops remaining changes. It also states explicitly that no playback keyword is sent and that configuration alone does not start playback, which is essential behavioural reassurance.

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

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

The action is front-loaded in the first sentence and the dense behavioural caveats follow, which suits a 28-parameter mutation tool. It is nonetheless very long and contains some restatement (e.g. two clauses about not touching selection/programmer/faders and not starting playback), so it is not maximally tight.

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 28-parameter mutation tool with no annotations and no output schema, the description covers the safety profile, locking, verification, preview, read-back semantics, sharing warnings, and concurrency limits. An agent has everything needed to call it correctly and to predict failure modes.

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

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

Schema coverage is 100%, so the baseline is 3, and the description exceeds it by adding meaning the schema lacks: wrap_around requires a first-cue trigger, kill_protect/swap_protect guard against Kill/Swap actions (not editing), rate_master semantics (fades/delays/trigger times at effective BPM/60, 1:1 at 60 BPM), speed_master follows phasers, masters linked by name with unnamed masters refused. Several boolean flags (auto_fix, tracking, soft_ltp, etc.) are only echoed from the schema, so it is not a full 5.

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

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

The opening sentence states a specific verb and resource ('Set a sequence's playback settings by writing its properties') and enumerates the properties, so an agent knows exactly what is mutated. It distinguishes itself from siblings by routing cue triggers/timing to gma3_set_cue_trigger / gma3_set_cue_timing and by scoping settings to the sequence rather than an executor.

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

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

It gives clear context for when to use it (settings belong to the sequence and apply to every executor referencing it) and names the alternative tools for cue triggers and timing. What is missing is an explicit when-not-to-use versus gma3_configure_executor / gma3_set_property, which an agent must infer.

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

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

With no annotations, the description carries the full behavioral burden and does so richly: it discloses the exact command sequence sent and its order, the locked-master refusal, that every linked sequence follows the change, that master 16 tracks sound input and may move again, and what verify/preview actually do. This is exactly the mutation-and-side-effect detail an agent needs.

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

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

A single dense paragraph that front-loads purpose and the settings before behavior. Every clause carries real information, but the run-on form makes it harder to scan than it could be with brief structuring.

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

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

For an 8-parameter mutation tool with no annotations and no output schema, the description covers parameters, side effects, command order, failure mode, and the verify/preview readback path. 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 only 13%, so the description must compensate and does: master is bounded to 1-16, tempo is explained as the EFFECTIVE tempo under the final scale with 0 stopping the master and a 225x-scale cap, speed_scale lists legal values, learn_mode explains each tap/scale interaction, and verify/preview semantics are given. It adds meaning well beyond the bare schema.

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

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

Opens with a specific verb+resource+scope: 'Sets one speed master (1-16)', then enumerates the three settings it controls (tempo, speed_scale, learn_mode). Distinguishes itself from siblings like gma3_speed_masters and gma3_speed_master_action by naming exactly what it configures rather than merely reading or acting on masters.

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

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

Gives operational context (verify defaults to true, preview sends nothing, refuses a locked master) that implies when to use it, but never explicitly names an alternative sibling or states 'use this instead of X when Y'. Usage is inferable but not routed.

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

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

No annotations provided, so the description carries full burden. It discloses mutation semantics (what is replaced/deleted vs preserved per mode), the refusal behavior for merge/overwrite, the background re-cook with merge low priority, and bridge version requirement. This is substantive beyond the schema.

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

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

Extremely long, dense run-on sentences with no paragraphing. Front-loads purpose but the detailed coverage/verification discussion could be trimmed or restructured; it reads as a spec dump rather than a tool description.

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 5 params, nested target, no output schema, and a complex domain, the description covers mode semantics, verification, refusal behavior, background behavior, and prerequisites. It's arguably over-complete if anything.

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 40%, and nested target object is only partly documented. Description compensates by explaining mode meanings, verify (verify, default true), preview, and replace_uncooked semantics — going beyond the schema's enum list and default note.

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 (cook) and resource (recipes of preset/cue/sequence) plus the four modes. Clearly distinguishable from siblings like gma3_edit_recipe or gma3_recipes.

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

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

Explains mode selection semantics (merge_low_priority vs merge vs overwrite vs remove) and explains preview/verify flow, giving clear when-to-use guidance. Doesn't explicitly name alternatives but the mode descriptions function as decision 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?

With no annotations, the description carries the full burden and does so richly: declares read-only behavior ('never changes selection, programmer or playback'), notes it works with gma3_lua disabled and requires plugin >= 0.3.0, and discloses concrete limitations (storedValues always null, trackedValues 'not_reconstructed', fixtures filter scope).

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 and then adds dense but useful detail; nearly every clause (supported mode, limitations, param scope) earns its place. The single long paragraph is slightly heavy to parse, keeping it from a 5, but it is not padded.

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

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

There is no output schema, so the description is responsible for return-value coverage, and it enumerates the returned property/part/recipe fields in detail. Combined with the mode and limitation disclosures, an agent has everything needed to invoke and interpret results 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 genuine meaning: expand_presets:true adds referenced preset data keyed by preset address (GetPresetData), and the fixtures filter is scoped to expanded preset data only. It clarifies cross-parameter interaction rather than restating 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 ('Read what a cue stores') plus scope ('without playing it back or loading it'), which cleanly distinguishes it from playback siblings like gma3_goto_cue and gma3_playback. The enumeration of returned fields (properties, per-part timing, recipes) leaves no ambiguity about what the tool does.

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

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

Explicitly frames the use case as inspection-without-playback and states 'Never sends Goto, Load or any playback command,' which routes the agent away from the playback tools. It doesn't name specific sibling alternatives, but the read-only inspection context and the supported-mode/not-available constraints give clear usage boundaries.

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

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

No annotations are provided, so the description carries the full behavioral burden. It implies a read but never states that it is non-mutating, says nothing about pagination behavior despite limit/offset existing, and does not describe what happens when the sequence is unknown or the property list is invalid.

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

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

One front-loaded sentence with no wasted words; the resource and the returned properties are stated immediately. It is efficient rather than padded, though the single sentence leaves no room for the routing or pagination details an agent would want.

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

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

With no annotations, no output schema, and an undocumented half of the parameter set, this description is too thin for a 4-parameter tool. An agent still cannot tell whether results are paged, how many cues come back per call, or how the tool relates to gma3_cue_contents and gma3_sequences.

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 50%: 'sequence' (number or name) and 'fields' (with its default list) are documented, while 'limit' and 'offset' are bare. The description's mention of cue number, name, trigger and timing roughly mirrors the default fields set, adding mild value, but it never explains the pagination parameters the schema leaves undocumented.

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

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

States a specific verb and resource ('List the cues of a sequence') and names the properties returned (cue number, name, trigger, timing), so the agent knows exactly what this returns. It does not, however, distinguish itself from nearby siblings such as gma3_sequences (lists sequences) or gma3_cue_contents (cue detail), so the agent must infer the boundary.

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

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

There is no when-to-use guidance, no prerequisite (e.g. sequence must exist), and no named alternative for retrieving cue data. The agent is left to infer that this is the browse-level tool versus gma3_cue_contents or gma3_get_object.

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

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

With no annotations, the description carries the full burden and delivers: the existence pre-check that refuses with nothing sent, the post-mutation verification outcomes (matched/mismatched/unavailable), no change to selection or programmer, never retried, and an honest caveat that the mutation lock only orders this server's own mutations and does not isolate it from other operators or clients.

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 operation and rejected forms, then behavior and caveats. Every sentence is substantive, though the paragraph is dense enough that a couple of clauses (verification result taxonomy, lock caveat) could be tightened.

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

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

A mutation tool with no annotations, no output schema, and four parameters: the description covers preconditions, refusal semantics, verification return states, side-effect scope, retry policy, and concurrency caveat. Nothing an agent needs to invoke it safely 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 cue, verify, sequence, and use_selected_sequence are already documented in the schema, making the baseline 3. The description reinforces the single-cue constraint and verification behavior but adds little parameter-level detail beyond what the schema provides.

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

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

States a specific verb (delete) and resource (one explicit cue), plus the exact console command form `Delete Sequence n Cue c /NoConfirmation`. It is clearly distinguishable from siblings like gma3_store_cue or gma3_goto_cue, and the 'exactly one' / 'ranges rejected' scoping pins down the operation.

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

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

Explicitly defines the when-not condition: ranges (Thru, +) are rejected, so bulk deletes must go elsewhere. It also states the precondition that the cue must exist or the tool refuses. It stops short of naming a sibling alternative for ranged deletion, so it falls just below full routing guidance.

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

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

With no annotations, the description carries the full burden and delivers: read-only guarantee (never changes selection, programmer or playback), the granted:false behavior for ungranted universes returning no values rather than zeros, the bounded nature of patched mapping with limitations when skipped, and the two-address representation of 16-bit attributes.

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

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

Dense but front-loaded: the what/range opens the description before edge behaviors. Nearly every sentence carries a distinct fact, though the density makes it slightly heavy for a read 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?

No output schema or annotations exist, so the description must carry the return-shape burden, and it does: granted flag, limitations on ungranted/patched, unit conversion, and 16-bit address splitting. An agent has enough to call and interpret 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 baseline is 3, but the description adds meaning beyond the schema: percent is 'as the console converts it', patched maps addresses through the RT channels and is bounded/stated in limitations when skipped, and nonzero_only is characterized as an explicit filter. These are genuine semantic additions on top of the schema text.

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

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

States a specific verb+resource: raw DMX output for an explicit universe and channel range, with 1..512 channels and 1..1024 universes. It explicitly distinguishes itself from sibling tools by noting the source is 'dmx output' — output levels, NOT programmer values — routing the agent away from gma3_programmer and similar tools.

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

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

Gives clear conditions: works with gma3_lua disabled, reads output levels not programmer values, and unqualified universes return no values. It establishes when this tool applies but never names a specific alternative sibling (e.g. gma3_fixture_output or gma3_programmer) as the contrasting choice.

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

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

No annotations are provided, so the description carries the burden; it discloses that the output is raw, verbose, and includes the full property/child tree, which is meaningful for a tool with no output schema. It stops short of stating read-only nature explicitly or any size/truncation behavior on large objects.

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

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

One sentence, front-loaded with the primary effect, followed by the comparison clause. Every fragment earns its place with zero 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 single-parameter read tool with no output schema, the description covers what is returned (class, path, properties, children) and flags verbosity, which is enough to call correctly. Only minor gaps remain around read-only confirmation and behavior on very large objects.

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 there is a single parameter whose accepted reference syntaxes are fully enumerated in the schema. The description adds no syntax, format, or resolution details beyond that, 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 (return) and resource (raw grandMA3 Dump() text for an object) and enumerates exactly what the text contains: class, path, every property and child. It also names the sibling that produces structured data, so an agent can distinguish gma3_dump from gma3_get_object 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?

"Verbose; prefer gma3_get_object for structured data" explicitly names the alternative and the condition that selects it. The implicit converse rule (use this when you need the raw dump text) is directly derivable, leaving nothing to infer.

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

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

With no annotations, the description carries the full burden and does so: it discloses the refusal condition (locked or running macro), the reference-validation behavior and its raw:true escape hatch, the read-back verification of order and content, and the non-obvious 'move is sent as upward moves only because a downward Move lands one place short' quirk. These are exactly the side-effect and failure-mode details an agent cannot infer from the schema.

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

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

The text is front-loaded with the action list and then layers constraints, verification, and the sibling cross-reference with essentially no filler. The telegraphic fragments ('set (any of command, wait, ...)') and the pointer to 'accept_console_form as in gma3_store_macro' force the reader to consult another tool, which slightly hurts standalone readability.

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 16-parameter mutation tool with no output schema, the description covers action semantics, preconditions, verification, and edge cases well enough to call it correctly. It stops short of explaining the verify/preview switches and what the read-back verification returns to the caller, which are the remaining gaps.

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

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

Schema description coverage is only 6% across 16 parameters, so the description must compensate, and it largely does: it maps command/wait/enabled/add_to_cmdline/execute/name/note to the set action, defines line bounds for insert, and explains to for move plus raw and accept_console_form. It leaves verify, preview, and the macro parameter itself unexplained, so a few parameters remain undocumented in both places.

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

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

The description names the exact resource (one macro line) and enumerates the four operations (insert, set, move, remove), so the agent knows precisely what the tool mutates. It also explicitly separates itself from gma3_run_macro and gma3_store_macro ('Never runs the macro', 'accept_console_form as in gma3_store_macro'), so it is distinguishable from siblings 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?

Usage is spelled out per action: insert requires a command and a line in 1..count+1, set takes a listed field set, move takes line -> to, remove deletes. It also gives the precondition that a locked or running macro is refused, which tells the agent when the call will fail. It does not, however, state when to prefer this over gma3_store_macro for whole-macro edits, so the routing guidance is incomplete.

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

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

With no annotations, the description carries the full burden and does: references are checked first, the result reads every line back, the console re-cooks an edited line itself (MergeLowPriority), a removed line's output disappears, and coverage is reported before/after (autoCooked). enabled:false preventing an initial cook is a non-obvious side-effect detail.

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

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

Front-loads the purpose, then organizes the body by action (add/set/move/remove) so each clause earns its place. It is dense and long-winded in places, but content-rich rather than 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 an 11-parameter, nested-object, no-annotation tool with no output schema, the description covers mutation side effects, verification/return behavior, prerequisites, and scope limits. An agent has what it needs 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?

At 64% schema coverage the description adds real meaning beyond the schema: it maps which fields belong to which action, explains values:null clears values, enabled:false switches a new line off before cooking, and preview returns planned commands. It leaves 'name' and the general 'target' object largely unexplained, so it is not fully compensating.

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

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

States a specific verb set (add/set/move/remove) and an exact resource: 'one standard recipe line of a preset or cue part'. It also names the sibling boundary (gma3_cook_recipes) and the scope exclusions (phaser lines, filters, timing), so an agent can distinguish it 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 target must exist' is an explicit prerequisite, and it routes the agent to gma3_cook_recipes when immediate cooking with Merge/Overwrite/Remove is wanted. 'Phaser lines, filters and timing columns are not edited by this release' is an explicit when-not, and preview:true is offered as the dry-run path.

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

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

No annotations are provided, so the description carries the full burden. It mentions the returned fields but doesn't disclose whether it's read-only (implied by 'List', but not stated), whether it can error, or what happens when no page is active. The executor-numbering range is a useful scope hint but falls short of 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?

Two sentences, front-loaded with the purpose, followed by a compact numbering reference. Efficient, though the numbering block could arguably belong in the schema and slightly lengthens an otherwise tight listing.

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 3 optional params, full schema coverage, and no output schema, the description covers the essentials for a listing tool. However, absence of annotations means behavior (read-only nature, error cases, relationship to sibling listing tools) is unstated, leaving meaningful gaps for an agent deciding whether to call it.

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

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

Schema coverage is 100%, so the schema already documents to/from/only_assigned with defaults. The description's executor-numbering map (101-115 top row, 201-215 faders, 301-315) adds context for what range values mean, which is genuinely useful beyond the schema's plain numeric min/max. Still, it doesn't explain the only_assigned parameter, so baseline 3 is appropriate.

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

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

States a clear verb+resource ('List executors') and details the scope ('on the current executor page') plus the fields returned (assigned object, key/fader functions, master fader level). It doesn't explicitly name a sibling it differs from, but the specificity of 'current executor page' distinguishes it from something like gma3_objects or gma3_list_children.

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

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

No explicit when-to-use or when-not-to-use guidance. The description implies it's for inspecting the executor page but doesn't tell an agent how it relates to gma3_objects, gma3_executor_settings, or other sibling listing tools. The executor-numbering context is useful but doesn't constitute usage guidance.

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

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

With no annotations provided, the description carries the full burden and delivers: it declares read-only ('Sends no command and changes nothing'), explains null handling for unreadable values and their aggregation in an 'unreadable' list, and discloses the cross-data-pool behavior (reported as dataPool: other, ref: null). It also notes that sequence settings apply to all executors referencing that sequence, which is important non-obvious context.

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

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

The critical read-only guarantee is front-loaded, and the subsequent clauses enumerate return contents in a dense but information-bearing way. The single long run-on sentence is efficient but would scan better broken into a couple of statements.

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

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

For a complex inspection tool with no output schema and no annotations, the description does substantial work: it enumerates the returned fields, explains the null/unreadable convention, and covers the cross-pool and shared-sequence cases. What it lacks is any guidance on the tool's relationship to sibling read/configure tools.

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

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

Schema description coverage is 100%, so the schema already documents page, executor, and references, establishing a baseline of 3. The description reinforces the page.executor addressing notation and clarifies why the references scan matters (sequence settings are shared), but adds no format or syntax detail 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 (inspect/read) and resource (an executor plus its sequence's playback settings), and enumerates exactly what fields are returned. It does not explicitly differentiate itself from siblings like gma3_executors or gma3_configure_executor, leaving the agent to infer that this one is the read path versus the configure path.

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

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

The description never states when to use this tool versus the many adjacent siblings (gma3_executors, gma3_configure_executor, gma3_configure_sequence, gma3_playback). The read-only framing implies a read path but gives no conditions, prerequisites, or exclusions to guide selection.

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

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

With no annotations the description carries the full burden and does so thoroughly: it changes no console state (selection, command line, programmer, playback, focus), reads items sequentially rather than as an atomic snapshot, flags lastCommand/maState as shared observations rather than request confirmation, distinguishes sequenceActive from executor button state, and warns Freeze is always unavailable. It also documents per-item fields (available, value, scope, source, observedAt, epoch) and that null means unavailable while false is a real observed value.

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

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

Information-dense and front-loaded with the readable items, but delivered as one long multi-clause paragraph with heavy parenthetical asides, which hurts scanability for an agent. Little is outright redundant, but the packing is dense enough that structure suffers.

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

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

For a 5-parameter, enum-heavy tool with no output schema, the description compensates by explaining the shape of returned items and their semantics (available/value/scope/source/observedAt/epoch, null vs false). Combined with the acquisition and interaction caveats, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantic value: it clarifies that executor/fader/sequenceActive readers are parameterised and sourced from executors/sequences, that fader_tokens defaults to ['FaderMaster'], and that previewBar defaults to display 1. It also documents the meaning of the returned value semantics, which the schema cannot.

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

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

Names a specific verb and resource (read-only console feedback state) and enumerates the exact readable quantities (command-line text, last command, Blind/Highlight/Solo, Preview, shortcuts, MA state, page, executor/fader/sequence activity). An agent can tell this is a state-reader apart from write-oriented siblings like gma3_command or gma3_set_fader 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 deployment context — works with gma3_lua disabled, with console input disabled, and while another client holds an input interaction, and it acquires nothing. However it never says when to prefer it over siblings such as gma3_status or gma3_hardkeys_status, and the no-argument default behavior ('every parameterless reader is read') is stated but not framed as guidance.

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

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

With no annotations, the description carries the full burden and does so: it declares read-only behavior ('never changes selection, programmer or playback'), the lua-disabled/structured-bridge mode and plugin version floor, that fixture resolution goes through the console rather than assumed patch index, the meaning of `source` values, and that null fields are explicitly unavailable rather than inferred.

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 returned-field inventory, then falls into shorter, higher-value sentences on resolution, source, nulls and pagination. The opening sentence is a dense run-on with nested parentheticals, but with no output schema the enumeration of return fields earns its place.

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

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

No output schema exists, so the description must cover returns and it does: field inventory, `subfixtures[]` shape, `source` provenance, null semantics and pagination. Combined with the environment constraints (lua disabled, plugin >= 0.3.0) and the read-only guarantee, nothing critical for correct invocation is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning: the accepted fixture formats (numeric ID, '501.3' subfixture, 'Fixture 501.3' command reference), one-and-only-one (sub)fixture constraint, and the semantics of channel sets as named ranges like gobo slots.

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 ('List the attributes of one fixture or subfixture') with an explicit scope (attributes, not current values). It enumerates the returned fields and is clearly distinguishable from gma3_fixture_output and gma3_patch_list, which the description itself references.

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

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

States the positive case (inspect one fixture/subfixture's attributes, e.g. 'Fixture 501.3'), the exclusion ('Not available: current values'), and names the alternatives to use instead (gma3_programmer / gma3_fixture_output). An agent is told both when to pick this tool and when not to.

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

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

With no annotations, the description carries the full behavioral burden and does: it declares read-only semantics ("never changes selection, programmer or playback"), the dependency requirement (plugin >= 0.3.0, works with lua disabled), and concrete failure/limitation behavior (null value plus limitation on ungranted universes; no per-attribute cooked output).

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 payload is front-loaded into the first sentence (what is returned) before constraints and caveats, and most sentences carry information that is not in any structured field. It is dense and long, bordering on a run-on in the opening line, but not wasteful.

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

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

There is no output schema, so the description must explain return values — and it does in detail (channel name, attribute, universe.address, raw value with bits/unit, derived percent, linear conversion, active channel set). Combined with the limitations and read-only statement, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so all four parameters are already documented, and the description mostly restates them (nonzero_only default false, pagination, fixture accepts subfixture references). It adds little 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?

The title and opening sentence state a specific verb (inspect) and resource (a fixture's/subfixture's DMX output) and enumerate exactly what is returned per RT channel. It is clear what the tool does, but it never names a sibling (e.g. gma3_dmx or gma3_fixtures) to contrast against, so sibling differentiation is only implicit.

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

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

It gives strong context cues: works with gma3_lua disabled, read-only, and explicit exclusion of programmer values ("Source is 'dmx output': these are output levels, NOT programmer values"). However it never states alternatives or when another tool should be used instead, so no explicit 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?

Without annotations, the description carries the full behavioral burden. It helpfully discloses that results are paginated and mentions the filter parameter, but it does not clarify permissions, rate limits, or whether the call is read-only (though 'List' strongly implies it). For a simple read-only listing this is adequate but not rich.

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

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

Two tightly written sentences with zero waste. The core purpose is front-loaded, followed immediately by the pagination and filter guidance.

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

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

The description tells what fields are returned and that paging exists, which partially substitutes for a missing output schema. But the offset parameter has no description in the schema or the description, leaving pagination semantics incomplete for an agent trying to page through results.

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

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

Schema coverage is 75%, so the schema already documents three of four parameters including defaults for fields and filter. The description restates the default field set and adds a filter example, but adds no semantics for offset, so it only marginally exceeds 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?

The description states a specific verb (List) and resource (fixtures in the patch) and enumerates the returned fields, making the tool's function clear. It does not explicitly distinguish itself from the similar sibling gma3_patch_list, so it falls short of the top score.

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

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

It gives a concrete example for the filter parameter ('Fixture 1 Thru 50') and notes pagination, which implies usage context. However, it never says when to use this tool versus gma3_patch_list or other fixture/patch siblings, leaving the agent to infer the choice.

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

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

With no annotations provided, the description carries the behavioral burden. 'Read' implies a non-mutating operation and it mentions returning display text, but it does not disclose permissions, side effects, or whether it alters playback state.

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

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

The definition is a single front-loaded sentence with no filler. It states the action and return content efficiently.

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

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

For a simple read-only getter with full schema coverage and no output schema, the description is largely sufficient: it states what is read and that display text is returned. It leaves some gaps around return structure and permissions, but those are minor for this tool's complexity.

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

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

Schema description coverage is 100%, so the schema already fully documents 'ref' and 'tokens'. The description adds only that the object is a playback object, which is already implied by the tool name and title.

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

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

The description uses a specific verb ('Read') and resource ('fader values and display text') and scopes the operation to a playback object. It implicitly distinguishes itself from the sibling gma3_set_fader by being a read operation, but it does not explicitly name or contrast with alternatives.

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

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

The description states what the tool does but gives no explicit when-to-use guidance, prerequisites, or alternatives. It does not say when to prefer this over gma3_get_object, gma3_playback, or gma3_set_fader.

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

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

With no annotations provided, the description carries the full burden, and it does disclose meaningful behaviour: the returned content set (name, class, address, properties), that property values come back "as display text" (i.e. formatted strings, not typed values), and that schema/children are opt-in. It stops short of error handling for bad refs or pagination semantics for large child listings.

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

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

Two dense sentences: the return contents are front-loaded, the optional extras follow, and the usage sentence closes with concrete object-type examples. No filler and no repetition of the tool title.

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

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

For a 7-parameter, no-output-schema, no-annotation tool, describing the return contents largely compensates for the absent output schema. The remaining gap is the child-* pagination parameters and any statement of read-only safety, which nothing else in the definition covers.

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 71%, so the schema already documents ref, schema, children, properties and child_fields. The description reinforces the schema/children/properties toggles and adds the "display text" nuance, but says nothing about child_limit, child_offset or child_fields, leaving the pagination behaviour of children listings undefined in both places.

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

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

The description gives a specific verb (Read) and resource (an object from the show data) and enumerates the returned fields: name, class, address, all properties, optional schema and children. It is clearly not the same as a mutator, but it never distinguishes itself from overlapping siblings such as gma3_objects, gma3_dump, gma3_list_children, gma3_sequences or gma3_cues, so an agent must guess which generic reader to pick.

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

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

"Use this to inspect sequences, cues, executors, fixtures, presets, groups, macros, pages, settings, etc." gives a concrete context of use across object domains. However, it offers no when-not guidance and no routing to the alternatives that clearly overlap (gma3_list_children for children, gma3_fixtures for fixtures, gma3_pool for pools).

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

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

With no annotations provided, the description carries the full burden and delivers: it identifies the operation as a playback mutation with live-output impact, explains that success only means command acceptance, discloses asynchronous crossfade completion that is not verified, states the refusal condition, clarifies selection/programmer are untouched, records verification as not_requested, and limits the mutation lock's scope against other operators or clients.

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 operation type and command form, and each sentence contributes a distinct fact (mutation semantics, async caveat, refusal, non-effects, verification status, lock scope). It is dense but readable; minor redundancy appears in 'PLAYBACK MUTATION' followed by 'Goto is a playback mutation.'

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

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

For a mutation tool with no annotations and no output schema, the description provides everything an agent needs to invoke it safely: command shape, required parameter mapping, failure condition, concurrency limitations, and the distinction between command acceptance and crossfade completion. Return values need not be explained because no output schema exists.

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

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

Schema description coverage is 100%, so the schema already explains each parameter thoroughly. The description adds the command template ('Goto Sequence n Cue c [Fade s]') which maps three parameters to their positions, but provides no extra semantics (defaults, edge cases, or interactions) beyond what the schema already documents.

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

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

The description states a specific verb-resource pair ('sends Goto Sequence n Cue c', 'jumps the sequence to that cue and changes live output') and distinguishes the tool's side-effect profile from programmer/selection tools ('Does not change the selection or the programmer'). It does not explicitly name an alternative sibling such as gma3_playback or gma3_command, so it falls short of full differentiation.

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

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

The description explains what the tool does and when it refuses ('Refuses (nothing sent) when the cue does not exist'), but never states when an agent should choose this over siblings like gma3_playback, gma3_command, or gma3_select. Usage is only implied by the effect, with no explicit exclusions or alternatives.

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

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

With no annotations present, the description carries the full burden and does so thoroughly: it discloses the [busy] refusal while any key is held, the input=OFF gating, that releases are 'dispatched' never 'confirmed', that nothing is retried/replayed, and that uncertain dispatch is reported as unknown. This is unusually rich, honest behavioral disclosure for a mutation-like tool.

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

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

Front-loaded with the core verb and packed with relevant signal, but it is a single dense paragraph with no structural breaks, making it harder to scan. Every clause roughly earns its place for a genuinely complex tool, so 4.

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

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

For a complex, 8-parameter tool with no output schema and no annotations, the description is complete: it covers routing, preconditions, concurrency/refusal semantics, verification limits, and result interpretation. Nothing an agent needs to call it correctly appears missing.

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

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

Schema description coverage is 88%, so the schema already documents key, keys, action, display, hold_ms, executor, exclusive and interaction. The description largely restates this (hold_ms default/max, keys 2-4, interaction required for press), adding little syntax or meaning 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?

Names a specific verb set (press/release/tap) and resource (logical MA hardkeys via the bridge keyboard backend), listing the exact keys and the routing mechanism. An agent can tell broadly what it does. It does not, however, explicitly distinguish itself from sibling tools like gma3_keyboard or gma3_type, so it falls short of a 5.

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

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

Provides strong operational context: press REQUIRES an interaction id from gma3_input_interaction, exclusive:true is the intended long-press, and input is off until the operator enables input=keyboard. It explains when refusals occur and preconditions, but names no alternative sibling for comparison, so 4 rather than 5.

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

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

With no annotations, the description carries the full burden and delivers: release ordering (newest first), that stored press tuples are never re-resolved, that the keyboard backend only 'dispatches' with no per-key readback, that unresolved releases are reported as unknown and persist until they succeed, and exactly whose keys are affected. These are non-obvious behavioral traits an agent could not infer from the schema.

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

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

The core action and its scope are front-loaded, and nearly every clause adds operational information. It is a single dense run-on sentence with strained phrasing ('with recover: true also re-attempt the releases that stayed unresolved') and a slightly redundant closing scope sentence, so readability suffers even though little is truly 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?

No output schema and no annotations, so the description must cover behavior and results, and it does: it explains what a successful dispatch looks like, how unresolved releases surface, and that records persist. The only loose end is what the call actually returns (list of keys, counts), which an agent calling this would likely want.

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

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

Schema coverage is 100%, so the schema already documents the single 'recover' boolean and the baseline is 3. The description goes beyond it by explaining the concrete failure conditions recover addresses (a remapped or disabled shortcut, a release that raised) and the persistence semantics of unresolved records.

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 with scope: 'Release every key held by this server's bridge session'. The qualifier 'this server's bridge session' and the closing scope sentence ('another client's or a physical operator's keys are not') distinguish it cleanly from siblings like gma3_hardkeys_status or gma3_keyboard.

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 conditional context: 'Works while input is disabled: this is the recovery path', which tells the agent when this tool is the right choice. It also names the operator-side recovery command. It does not, however, explicitly contrast with the sibling status/release tools by name, so the routing guidance is contextual rather than exhaustive.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it does so well: it declares read-only semantics, that it functions while input is disabled, that it releases nothing, and it explains the backend distinction (keyboard = real keys, fake = nothing reaches the console). It also clarifies that ownership records are recovery responsibility, not physical key state. It does not cover auth or failure behavior, but the disclosure is unusually rich for a status tool.

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

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

It is front-loaded with 'Read-only', which is good, but the payload is delivered as one very long run-on sentence enumerating roughly a dozen field groups, followed by a dense semantics sentence. Every item is arguably informative for a status tool with no output schema, but the structure is heavy and would benefit from breaking the enumeration into a shorter list.

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

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

There is no output schema, so the description must describe the return payload, and it does so comprehensively: ownership record fields (owner, logical key, PC tuple, state, lease/deadline, dispatch outcomes, MASTATE readback, cleanup failures), interactions, sequence, capacity, and busy descriptor. For a read-only tool with zero parameters this is close to complete; only return format/ordering details are absent.

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

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

The tool takes zero parameters, so the baseline is 4; there is no parameter syntax for the description to add or omit.

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

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

The description states a specific read operation ('Read-only') and enumerates exactly what the status covers: input enablement, backend, ownership records, interactions, sequence, capacity, busy descriptor. An agent can tell it is a diagnostic read rather than a mutation. It does not explicitly distinguish itself from siblings like gma3_status or gma3_feedback, which keeps it from a 5.

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

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

Usage is implied rather than stated: 'Works while input is disabled; releases nothing' signals this is a safe diagnostic read and implicitly contrasts with gma3_hardkeys_release_all. However, it never says when to call this versus gma3_status, gma3_input_interaction, or gma3_feedback, so the routing guidance 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?

No annotations are provided, so the description carries the full burden. It usefully discloses the return shape (page text, or a list of matching pages), which is real behavioral value, but says nothing about what max_chars does, whether results are truncated, or any index/caching constraints. Adequate for a low-risk read, with gaps.

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: purpose first, then input format with inline examples, then return behavior. No filler, nothing buried.

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

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

For a read-only manual lookup with no output schema and no annotations, the description covers purpose, input phrasing, and result format. The only real omission is the semantics of max_chars and any hint about result volume or pagination.

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

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

Schema description coverage is 0%, so the description must compensate. It compensates well for 'topic' by giving seven concrete keyword examples and three phrase examples, clarifying the expected granularity, but never explains the 'max_chars' parameter at all, leaving half the parameters undocumented anywhere.

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 (look up), resource (grandMA3 user manual shipped with onPC), and output form. It is unmistakably distinct from the dozens of operational siblings like gma3_command or gma3_objects, which act on the console rather than explain it.

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

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

Tells the agent exactly what to pass (a command keyword such as 'Go'/'Store'/'Lua', or a topic phrase such as 'cue timing') and implies a fallback flow when it returns a list of matching pages to choose from. No explicit when-not-to-use or alternative tool is named, but no sibling offers manual lookup either.

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?

Lease defaults/max are also in the schema, but the description adds the behavioral payload: bridge refuses all writes with [busy], reads stay available, renew moves the deadline without pressing, end releases keys newest-first/aborts the sequence/reports unresolved, and interactions are never resumed. Effectively complete disclosure-bearing text for an unannotated tool.

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

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

Dense and front-loaded with the acquire-lifecycle model, then the deadline and end semantics. Nearly every clause carries information, though the single long paragraph is heavier than ideal for scanning.

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

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

With no annotations or output schema, the description is still sufficient: lease, busy-blocking, prerequisites, and failure modes are all covered. Nothing an agent needs to acquire/renew/end 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 75%, so the schema documents most parameters. The description adds the consequence of lease_ms expiry (keys released) and ties interaction to renew/end across calls, going beyond the schema's terse field notes.

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 specific verbs (acquire/renew/end) and resource (a leased input interaction) and explicitly names the sibling tools that consume the returned id (gma3_hardkey/gma3_keyboard, gma3_type, gma3_input_sequence). An agent can distinguish it from those siblings 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?

Explains the exact coordination model: acquire when you need console key input across several calls, end as soon as the interaction is done, renew when you need more time. It also states prerequisites (input must be enabled) and the edge case (end works while input is disabled), leaving little to inference.

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

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

With no annotations, the description carries the full burden and does so well: it discloses pre-dispatch validation of EVERY step (one invalid step means nothing dispatched), sequential servicing with context rechecks, failure propagation (later steps skipped, held keys released newest-first, nothing replayed), the succeeded/failed/unknown/skipped status taxonomy, the caveat that 'completed' does not mean a UI effect was verified, the [busy] lock on all clients during the run, and the requirement that input be enabled via the bridge plugin. That is unusually thorough behavioral context.

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

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

Front-loaded with the core verb+scope, which is good, but the paragraph is long and dense, packing validation, lifecycle, statuses, locking, and setup requirements into one run-on block. Key facts (16-step cap, ~30 s budget) compete with edge-case semantics; a bulleted split of lifecycle vs. step kinds vs. preconditions would have earned a higher score.

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

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

No output schema exists, so the description must explain returns; it does so via the status taxonomy (succeeded/failed/unknown/skipped) and failure semantics, which is sufficient. Remaining gaps are minor: no explicit guidance on label or lease_ms semantics, and the interaction parameter's role is described but not contrasted against gma3_input_interaction's own lifecycle.

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 50%, and the description mostly mirrors what the schema already documents (step cap, time budget, interaction ownership) without adding syntax or defaults for the under-documented parameters like lease_ms, label, or the per-step modifier flags. It does add the operational nuance that a sequence owns an interaction if none is passed, but the 50% coverage gap is not fully compensated.

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

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

The description states a specific verb+resource: 'Run an ordered, bounded sequence of console input' with the exact step types (taps, presses, releases, combinations, text, waits) and limits (16 steps, ~30 s). It distinguishes itself from most siblings by describing the sequence-level orchestration, though it never names or routes to the most obvious alternatives like gma3_hardkey, gma3_type, or gma3_keyboard. A single 'use this instead of individual input calls when...' sentence would have earned a 5.

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

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

Usage context is implied rather than stated: the description explains what the sequence does and mentions the interaction parameter, but never says when to prefer this tool over calling gma3_hardkey/gma3_keyboard/gma3_type individually, nor when not to use it. For a tool with three obvious input-sibling alternatives, that is a clear gap.

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

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

With no annotations, the description carries the full burden and succeeds: it discloses that keys are real, input is OFF until the operator loads the plugin, commands are [busy] while a key is held, the UI effect is unverified, and nothing is retried or replayed. It also specifies lifecycle semantics (tap returns after release attempted, press requires an interaction id, release uses the stored press tuple).

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+resource, and nearly every sentence conveys operationally useful constraints rather than filler. It is a dense run-on paragraph with a few formatting artifacts (double spaces inside the quoted plugin invocation), which costs a point but not the underlying value.

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

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

For a 10-parameter, non-idempotent input tool with no output schema and no annotations, the description covers gating, ownership, busy state, verification expectations and action semantics. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is already 90%, so the baseline is 3, but the description adds real procedural meaning the schema does not: the action-dependent requirements (press needs an interaction id; release reuses the stored press tuple), and that modifiers are passed on both the press and the release rather than as separate key presses. Only the hold_ms/display/exclusive details remain schema-only.

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 specific verbs (press, release, tap) on a specific resource (raw PC key via Enums.KeyboardCodes) and explains the mechanism (console Keyboard() emulation). It explicitly distinguishes itself from gma3_hardkey, so an agent can route between them without opening a schema.

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

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

Explicitly says to prefer gma3_hardkey for MA keys, warns that behavior depends on user profile, shortcut enablement and focused UI element, and enumerates prerequisites (input OFF until the operator runs the plugin, ownership/busy rules). When-to-use and when-to-use-something-else are both 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?

With no annotations, the description carries the full burden and does so well: it discloses the exact command sent, the broadcast side effect (renames the object everywhere it appears, including other executors), failure-before-send semantics, no selection/programmer impact, verify's precise read-back scope, and that mutations are serialised but not isolated from other clients.

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

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

Front-loaded with the core action and the critical renaming caveat, and every sentence conveys operational meaning. It is dense and runs long for a four-parameter tool, but little is expendable.

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

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

For a mutation tool with no annotations and no output schema, the description covers what an agent needs: command semantics, side effects, failure conditions, verify behavior, and concurrency caveats. Nothing material 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 value the schema does not: it explains what verify actually reads back (executor's displayed name, assigned object, and the assigned object's own Name), reinforcement that page/executor must exist, and the broadcast consequence of the label parameter's effect.

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

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

States a specific verb and resource ('Label the object assigned to the executor at Page <p>.<e>') and immediately clarifies the surprising semantics — that on grandMA3 2.5.1 this RENAMES THE ASSIGNED SEQUENCE, not the executor. That distinction separates it from siblings like gma3_executor_settings and gma3_assign_to_executor.

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 preconditions and exclusions: fails before sending anything when the page does not exist or the executor is empty, and does not change selection/programmer or send a playback keyword. It does not, however, name an alternative tool for renaming the underlying object directly, so routing is implied rather than explicit.

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

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

With no annotations at all, the description carries the full disclosure burden, and it does disclose the per-child return shape (name, class, address, index, optional property values) plus that results are paginated. It does not state that the operation is read-only, note any permission/auth requirements, or explain behavior on an invalid ref, so the coverage is good but not complete.

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

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

One well-formed sentence front-loads the core behavior and scope, with the parenthetical examples earning their place by disambiguating 'children'. The trailing "Paginated." is terse but informative, and there is no filler.

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

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

There is no output schema, so describing the returned child fields in the description is the right call, and pagination is called out. What is missing is minor: how to discover valid refs and what happens on an unrecognized ref, which an agent might need for a listing tool whose sole required parameter is a free-form reference string.

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 75%, so the schema already documents most parameters, including the rich ref syntax and the limit default. The description adds only a light gloss on 'fields' ("optional property values per child") and nothing on ref, limit or offset beyond what the schema says, so it lands at the high-coverage 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 ("List the children of an object") and immediately anchors the abstract term with concrete examples (cues of a sequence, items of a pool, executors of a page), which is genuinely clarifying. It implicitly distinguishes itself from single-object readers like gma3_get_object, but never names or contrasts a sibling explicitly.

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

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

The examples imply the situation in which the tool applies, so usage is inferable. However there is no explicit when-to-use vs alternatives guidance (e.g. when to prefer this over gma3_get_object, gma3_objects, gma3_dump, or gma3_cues), and no stated preconditions 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?

No annotations are provided, so the description carries the full behavioral burden — and it discloses a great deal: the capability is off by default with exact enable commands, the default budget (5 s / 20 M instructions), abort-on-exceed behavior, that the console hook is preserved by default so the budget is NOT enforced for non-yielding loops, and that luahook=replace enforces hard quotas. The serialisation with other mutations is also stated. Minor gap: it does not describe the result JSON shape beyond handle 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?

Information-dense and front-loaded with the purpose, followed by handle format, examples, enabling procedure, budget semantics, and serialisation. Every sentence earns its place, but it is a single very long block with a bare API-function list that could be tightened or structured for scannability.

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

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

For a complex, high-risk tool with no output schema and no annotations, the description covers execution model, safety profile, budget limits, enablement, error conditions, concurrency, and return format. An agent has everything needed to invoke it correctly or choose an alternative.

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 about the code parameter (compiled first as 'return <code>' then as a statement block) and supplies concrete examples like 'SelectedSequence().name'. The timeout_ms description ties into the budget semantics, reinforcing coverage.

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

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

States a specific verb (Evaluate) and resource (Lua 5.4 code) with the exact engine (grandMA3 Lua engine) and a clearly stated return (JSON). It explicitly differentiates from siblings by naming gma3_get_object, gma3_list_children, and gma3_objects as preferred for bulk reads, so an agent can distinguish it 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 explicit when-to-use (arbitrary Lua evaluation) and when-not-to-use ('prefer the structured tools ... for bulk reads', naming three alternatives), plus routing to gma3_lua_api for signatures. It also states the critical precondition that the capability is OFF by default and how the operator enables it, and points to gma3_status for the policy.

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

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

No annotations are provided, so the description carries the full disclosure burden. 'Search the live ... descriptor' implies a read-only lookup and it discloses the return shape (name, arguments, returns), but it never explicitly confirms there are no side effects or that results reflect the running system.

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

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

Two tightly written sentences with no filler; the resource and scope are front-loaded, and the enumeration hint follows naturally. Every clause earns its place.

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

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

With no output schema and no annotations, the description still conveys what is searched and what comes back (names, arguments, returns), which is enough for an agent to call it correctly. It stops short of naming the sibling it complements or confirming read-only behavior.

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

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

Schema coverage is 50% — the query parameter is documented in-schema, but the kind enum is not. The description compensates by explaining the two categories ('object-free functions' vs 'object methods') and the empty-query listing behavior, covering the meaning of both parameters even if it never spells out the 'all' enum value.

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 ('grandMA3 Lua API descriptor') and even specifies the fields searched (function name, arguments, return values) plus the two function categories. It does not explicitly distinguish itself from the sibling gma3_lua (which presumably executes Lua), so sibling differentiation is left to inference.

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 one concrete operational hint ('Leave query empty to list everything'), which tells the agent how to enumerate rather than search. It never states when to reach for this tool versus gma3_lua or gma3_help, so usage is only implied.

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

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

With no annotations, the description carries the full burden, and it does so well: it declares 'Read-only', documents the null-when-idle running line, the null-name default, and the effect of check_references. It stops short of 5 only because topics like pagination semantics beyond the default and error behavior are not addressed.

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 key constraint ('Read-only') and then cleanly segmented by mode and flag. It is dense with parenthetical enumerations, but each enumerated field (wait semantics, add_to_cmdline, etc.) earns its place for a tool with no output 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?

There is no output schema, so the description must describe return values, and it does so comprehensively for both modes plus the reference-checking extension. With no annotations and 0% schema coverage, this is complete enough for an agent to call it correctly.

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

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

Schema coverage is 0%, so the description must compensate, and it does: it maps macro (pool vs single), offset/limit (default 100), and check_references (lists referred objects and existence) to their meaning. Meaning is added for every parameter, though format details like whether offset/limit are numbers/count are left implicit.

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

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

States a specific verb and resource: reading the macro pool or a single macro, opening with 'Read-only' to signal the operation class. An agent can immediately distinguish it from write/execute siblings like gma3_run_macro, gma3_store_macro, and gma3_edit_macro_line.

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 'Without macro: ... With macro: ...' structure clearly explains the two invocation modes and their distinct outputs, giving solid context on how to call it. It does not explicitly name sibling alternatives or exclusions (e.g. gma3_run_macro), so it stops short of full when-not guidance.

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

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

With no annotations, the description carries the burden and does so credibly: it declares the operation is read-only, sends no command, defines the {from, to} distribution format, and explains that null means None. It also discloses that non-default settings are listed. Missing only auth/permission or scope caveats, which are minor for a read.

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 read-only qualifier and resource are front-loaded in the first two words, and the dense field list earns its space by telling the agent exactly what comes back. It is lengthy but not padded; a slightly lighter field enumeration would read more cleanly.

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

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

No output schema or annotations exist, so the description must convey return shape, which it largely does by enumerating fields, defining the distribution format, and specifying null semantics. A read-only single-param tool is well covered, though permission prerequisites are unstated.

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

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

Schema coverage is 100% and the single required parameter is already documented as 'MAtricks pool number'. The description's 'MAtricks <n>' restates this without adding format, range, or default detail, so it earns the baseline 3 with no extra value.

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 precise verb ('Read') and resource ('MAtricks object'), then enumerates the exact settings returned (wings, blocks, groups, width, shift, shuffle, fade/delay, phase, speed distributions). An agent can distinguish this inspection tool from gma3_configure_matricks and the command-sending siblings without opening the schema.

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

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

The 'Read-only' and 'Sends no command' framing implies this is for inspection rather than mutation, which is useful context. However, it never names the write alternative (gma3_configure_matricks) or says when to prefer this over gma3_get_object/gma3_dump; usage 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?

No annotations are provided, so the description carries the full burden. It discloses the core transformation (range → list) and that property values are optional, but says nothing about pagination defaults, error behavior on unparseable ranges, or read-only nature, leaving meaningful behavioral gaps.

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: purpose first, then a compact examples list. Front-loaded and waste-free, though the example list is long enough to verge on padding for an agent that only needs one representative sample.

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

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

For a 4-param, no-annotation, no-output-schema tool, the description adequately covers purpose and the critical ref syntax. It is slightly thin on return shape details and pagination semantics, but nothing essential for a correct call 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 75% and the 'ref' description ('Command-line object range') is opaque on its own; the six syntax examples add genuine meaning by showing the exact range grammar the parameter accepts. It does not clarify limit/fields/offset beyond the schema, so a 5 is not warranted.

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 (resolve) and resource (command-line object range → list of objects), and the examples make the operation concrete. It does not explicitly differentiate itself from siblings like gma3_get_object or gma3_list_children, so it stops short of a 5.

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

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

The examples strongly imply when this tool applies (you have a range expression like 'Fixture 1 Thru 20'), but there is no explicit when-to-use/when-not guidance or named alternative among the many siblings. Usage is implied rather than stated.

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

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

With no annotations, the description carries the full burden and largely succeeds: it declares read-only behavior, the 1-8 sequence scope, sampling duration/interval bounds and defaults, that it starts nothing, and an explicit limitation ('phaser output is not observable over the bridge'). The one unstated trait is that sampling for `seconds` makes this a blocking/long-running call rather than an instant read.

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 read-only guarantee and the core sampling behavior, and each subsequent clause (rate formula, chase prediction, phaser caveat) adds real information. It is dense and somewhat long, but there is no filler sentence.

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

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

With no output schema and no annotations, the description still specifies what is reported (observed vs configured step interval, rate source, predicted step interval for Time-triggered chases) and its boundaries. An agent has everything needed to invoke it correctly and interpret results.

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

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

Schema coverage is 0%, so the description must compensate, and it does: it documents all three parameters with meaning and bounds — `sequences` (1-8 running sequences), `seconds` (1-30, default 6), and `interval_ms` (default 40). This is exactly the value-add a schema-less param set needs.

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 ('Samples the current cue of 1-8 running sequences') and gives the measurement's purpose in the title/description combo. It is clearly distinguishable from siblings like gma3_get_object or gma3_sequences, which retrieve state rather than observing tempo over time.

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?

Includes an explicit precondition: 'It starts nothing: run the sequences first.' This rules out a common misuse. However, it does not name an alternative tool for measuring phaser/speed-master output or point to related tools, so it stops short of full routing guidance.

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

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

With no annotations, the description fully carries the behavioral burden: read-only pre-checks, patch edit copy workflow, isolation check, exclusive use requirement, no undo, ~10s duration, failure handling with copyLeftOpen, bridge version, and verify readback. This is comprehensive for a mutation tool.

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

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

Front-loads the core action and then details preconditions, workflow, and failure behavior in a single dense paragraph. Long but largely justified by the tool's complexity; minor repetition (exclusive requirement appears twice) slightly reduces efficiency.

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

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

Given the high complexity, absent annotations, and no output schema, the description covers purpose, usage conditions, behavioral workflow, failure modes, timing, and version dependency. Nothing critical for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds inter-parameter semantics beyond individual schema entries: address vs findFreeFrom alternative, unpatched when neither is given, consecutive FID block, and what verify reads back. This meaningfully supplements 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 'Add' and resource 'fixtures to the patch', with scope including one fixture type, one DMX mode, consecutive FIDs, and address/findFreeFrom/unpatched modes. It clearly distinguishes itself from patch modification or removal siblings by focusing on adding new fixtures.

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

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

Explains conditions for address vs findFreeFrom vs unpatched, the exclusive requirement, and pre-checks. However, it does not explicitly name alternative sibling tools like gma3_patch_set or gma3_patch_remove for modifying or removing existing fixtures, leaving that routing to inference.

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

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

With no annotations, the description carries the burden and does so reasonably: it opens with 'Read-only' (the key safety signal) and discloses pagination defaults/limits plus the non-obvious rule that fixtures lacking a numeric FID are dropped when a range is supplied. It does not cover error behavior or unsorted-result caveats, but the essential traits are present.

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

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

Dense and front-loaded: read-only status first, then contents, then filtering/pagination. The returned-field enumeration is long but earns its place given there is no output schema. No filler sentences.

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

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

For a list tool with no output schema and no annotations, the description enumerates the returned fields and documents the filtering and pagination contract, leaving little ambiguity. It could note ordering guarantees or behavior on empty results, but coverage is strong.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the fromFid/toFid semantics as a range filter and the special-case that non-numeric-FID fixtures are omitted when a range is given. Limit's default/max is repeated from the schema, which adds nothing.

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 (lists) and resource (the show's fixtures from the live patch), and specifies scope details (every stage, sub-fixtures included, patch order) that separate it from generic listing siblings like gma3_fixtures or gma3_objects.

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

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

It gives the filtering (fromFid/toFid) and pagination mechanics, which imply usage, but never states when to reach for this rather than gma3_fixtures, gma3_patch_types, or gma3_dump, nor any prerequisites. Usage is implied, not directed.

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

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

With no annotations, the description carries the full burden and does so exceptionally: nothing is sent on pre-check failure, the patch-session lifecycle (copy, isolation check, commit, read back), the NO UNDO warning, the best-effort nature of the isolation check, the copyLeftOpen:true failure mode, the ~10 s runtime, and the bridge 0.19.0 requirement are all disclosed. This is exactly the behavioral context an agent needs before a destructive, irreversible operation.

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

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

Front-loaded with the core action and refusal condition before the operational detail. The text is dense and some sentences are run-ons (the session-lifecycle sentence in particular), but the length is justified by an irreversible operation with a mandatory flag and an operator-resolution failure mode.

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 3-parameter destructive tool with no output schema: it describes the return signal (copyLeftOpen: true), the verification behavior, prerequisites (exclusive, bridge version), and operator remediation steps. 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 genuine meaning beyond the schema: it explains that 'exclusive' is mandatory and why ('confirms nobody else uses the console'), and that 'verify' reads the FIDs back and checks they are gone. It adds value over the structured fields rather than repeating them.

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

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

States a specific verb and resource ('Delete fixtures by FID from the patch') plus the cascade scope ('with everything that refers to them, e.g. their values in cues and groups'). It is clearly distinguishable from siblings like gma3_patch_add and gma3_patch_set without opening any schema.

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

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

Gives clear context: fixtures with sub-fixtures are refused, exclusive:true is required, and the pre-check condition (every FID exists, no sub-fixtures) tells the agent exactly when the call will be refused. It does not explicitly name alternative tools for related patch tasks, so it falls short of the full when/when-not/alternatives bar.

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

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

With no annotations, the description carries the full burden and does so thoroughly: pre-checks run before anything is sent, all changes roll back on any problem, a committed change has NO UNDO, the exclusive isolation check is best-effort not a guarantee, and failure leaves copyLeftOpen:true for operator resolution. This is exceptional disclosure of safety, atomicity, and failure behavior.

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

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

The core action is front-loaded well, but the description is dense and run-on, with repetition (exclusive:true requirement is stated twice, session steps restated across several sentences) that clouds scanability. Much content earns its place, but tightening would help.

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 high-stakes, no-undo mutation with no output schema, the description supplies everything needed: verification behavior, ~10s duration, rollback guarantees, copyLeftOpen return signal, bridge version, and operator recovery steps. Nothing an agent needs to call it safely 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 baseline is 3, but the description adds genuine meaning beyond the schema: addresses are applied together so fixtures can swap or move across their current range, and verify reads each edited fixture back. It also reinforces why exclusive must be true rather than merely restating the field.

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 specific verbs and resource: 'Change existing fixtures' with per-edit new address, unpatch, and/or new name. The title and first sentence make clear this edits already-patched fixtures, distinguishing it from gma3_patch_add and gma3_patch_remove 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?

Gives rich operating context: requires exclusive:true, needs bridge 0.19.0, takes ~10s, and describes the exact session flow. It does not explicitly name sibling alternatives (patch_add/remove) or state exclusions by name, leaving some routing to inference.

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

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

No annotations are present, so the description carries the full burden; it opens with 'Read-only' and discloses a real limitation (only the show's own types are listed; library import unsupported). It does not describe pagination or result size, but for a simple read that is a minor gap.

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

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

Front-loads the 'Read-only' safety signal and then packs purpose, return fields, usage routing, and limitation into three tight sentences. The field enumeration is dense but earns its place by describing an otherwise undocumented return shape.

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

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

With no output schema, the description valuably enumerates the returned fields (number, name, manufacturer, short name, source, DMX footprint, breaks, channels per break) and notes the library-import limitation. Only minor gaps remain, such as result size or sorting behavior.

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

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

Schema description coverage is 100% and the single 'search' parameter is fully documented in the schema, so the baseline is 3. The description adds no additional semantics about the filter beyond what the schema states.

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

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

States a specific verb and resource ('lists the fixture types imported into the show') and enumerates the returned fields, clearly distinguishing it from siblings like gma3_patch_list and gma3_patch_add.

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 downstream consumer ('Use the type and mode numbers or names with gma3_patch_add'), which gives clear selection context. It does not state when to prefer this over gma3_patch_list, but the routing guidance is concrete.

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

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

With no annotations present, the description carries the burden and does well: it discloses that Preview is cleared and exited, that clear_normal triggers a ClearAll on the Normal programmer (destroying a running effect there), and that the result reports environment plus leftovers. It omits any permission/auth or error-mode notes, keeping it 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?

Three dense sentences, front-loaded with the relationship to gma3_build_phaser before the mechanics. Jargon (ClearAll, Normal programmer) is domain-appropriate and nothing is filler, though it reads a little run-on.

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

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

For a 2-param mutation tool with no annotations and no output schema, the description covers the trigger, both parameters' effects, and the return ('reports the environment and what is left'). What an agent needs to call it correctly is essentially 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 the baseline is 3, but the description adds genuine cross-parameter semantics the schema only hints at ('Required with clear_normal'): the exclusive+clear_normal pairing and that it performs a ClearAll that stops an effect. That dependency explanation is real added value.

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

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

Names a specific verb+resource (release/stop the phaser build) and explicitly anchors itself as 'the stop/release path for gma3_build_phaser,' so an agent can pair it with that sibling rather than guessing. It also states the exact state it acts on (Preview environment from an interrupted build).

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 trigger condition: use it when the console is stuck in Preview after an interrupted build, and explains the additional clear_normal + exclusive combination. It does not, however, name an alternative for clearing programmers (e.g. gma3_clear_programmer, a live sibling), so the when-not-to-use side 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?

With no annotations, the description carries the full behavioral burden. It discloses the command equivalences that let an agent predict effects of actions like go/off/load, which is real behavioral context, but it never states that this drives live output, whether changes are reversible, or any permission requirements. Useful but incomplete for a live-control mutation tool.

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

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

Front-loaded purpose sentence, then command equivalence, then target formats in a compact two-sentence block with no filler. Slightly dense with example lists, but every element earns its place.

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

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

No annotations and no output schema, so the description should do more than it does. It covers purpose, action-to-command mapping, and target syntax, but omits live-impact/side-effect disclosure and any note on error behavior for a 3-parameter live playback tool.

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

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

Schema coverage is 67% (baseline 3), and the description meaningfully extends it: the command examples map onto enum values (go, off, load) and the target list ('Page 2.201', 'Master 3.1', 'Macro 5') goes well beyond the schema's single 'Sequence 1' example. The fade parameter is left to the schema, keeping it just below a 5.

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

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

States a specific verb (trigger) and resource (playback function on a sequence or executor), and grounds it with concrete command equivalents like 'Go+ Sequence 1' and 'Off Executor 201'. It does not explicitly differentiate itself from overlapping siblings such as gma3_command, gma3_goto_cue, or gma3_run_macro, so it stops short of a 5.

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

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

The equivalent-command examples imply when the tool applies (transport-style playback control), but there is no explicit when-to-use/when-not guidance and no routing to alternatives like gma3_command or gma3_goto_cue. Usage must be inferred from the examples rather than stated.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it states only that objects are listed. It never says the operation is read-only, nor does it explain pagination even though the schema exposes limit/offset, nor the shape or size of the result.

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

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

The core purpose is front-loaded in the first clause, but the trailing enumeration of roughly two dozen pool names is a dense wall of text that is hard to scan. Every item is arguably informative, yet the run-on single sentence costs readability.

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

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

With no annotations and no output schema, the description supplies the pool-name vocabulary an agent needs to invoke the tool, which is real value. It nonetheless omits pagination behavior and return-value expectations for a tool whose schema clearly supports paging.

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 only 25% — 'pool' is documented, while limit, fields, and offset are bare. The description's enumeration of valid pool names meaningfully reinforces the 'pool' parameter, but it adds nothing for the three undocumented pagination/projection parameters.

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

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

States a specific verb ('List') and resource ('the objects of a pool') and enumerates the pool names it accepts, which lets an agent recognize it against sibling list-style tools. It does not fully disambiguate from gma3_objects or gma3_list_children beyond the one preset-pool note, so it falls short of a clean 5.

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

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

The parenthetical gives a genuine routing rule: preset pools listed via this tool vs. a single pool via gma3_list_children ('Preset 4' style ref). However there is no general when-to-use guidance versus gma3_objects, gma3_get_object, or gma3_dump, and no prerequisites stated.

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

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

With no annotations, the description carries the full burden and does so well: it declares read-only, states the 'Needs bridge 0.22.0' requirement, documents the defaults assumed for absent layers (width/trans 100, accel/decel 0, 60 BPM, phase 0), and explains that embedded sources are followed recursively with validity flags. It adds genuine behavioral context about missing data and dependency resolution rather than restating the schema.

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

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

The content is front-loaded with 'Read-only.' and the version requirement is helpfully placed at the end, but the bulk is one very long run-on sentence enumerating return fields. It is dense and hard to parse, so size and readability suffer even though little is strictly redundant.

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

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

There is no output schema, so the description must explain what is returned — and it does cover both modes and the recursive dependency inspection thoroughly. Given the complexity of the return structure, the coverage is strong, though the cramped prose slightly limits how completely an agent can absorb it.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes further by explaining what each parameter actually retrieves: 'preset' returns per-fixture/attribute stored modes, values, steps, phaser layers, fade/delay and dependencies, while 'pool' returns the pool's default mode, input filter and store preferences. This semantic mapping of parameter-to-output exceeds the bare schema descriptions.

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

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

The title and description state a specific verb+resource (read a preset's stored content/references, or a pool's storage defaults) and lay out two distinct modes keyed by parameter. An agent can tell this is a read of preset/pool storage rather than a store or listing. It stops short of explicitly naming which sibling to use when, so it earns a solid 4 rather than 5.

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

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

The description implies usage via the 'preset:' vs 'pool:' parameter modes and the 'Read-only' framing, but never states when to reach for this tool over alternatives such as gma3_pool, gma3_get_object, or gma3_cue_contents. There are no exclusions or prerequisites beyond the bridge version. Adequate but leaves routing to inference.

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

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

With no annotations, the description carries the full burden and does so well: read-only guarantee ('never changes selection, programmer or playback'), plugin version prerequisite, coverage semantics ('when not complete the programmer is NOT claimed empty'), value:0 with present:true vs absent-row semantics, and phaser step handling. This is unusually rich 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 text is dense but front-loaded: purpose, scope, read-only status, then the critical 'rows are programmer content' warning, followed by edge-case semantics. Nearly every sentence earns its place, though the volume is heavy for a single description.

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

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

There is no output schema, so the description must explain return shape, and it does: row fields, value/valueRaw units, present/absent semantics, phaser steps[], and coverage.complete. An agent has everything needed to interpret results correctly.

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

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

Schema coverage is 100% and every parameter (scope, limit, offset, fixtures, max_channels) is already documented in the schema, so the baseline of 3 applies. The description reiterates scope semantics and mentions pagination but adds little syntax or format detail 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 ('Structured view of active programmer values per UI channel') and distinguishes itself from siblings by explicitly saying rows are programmer content, not output values, pointing to gma3_fixture_output/gma3_dmx. An agent can identify the tool without opening the schema.

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

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

Explains the three scope options and their meaning, and routes output-value queries to gma3_fixture_output/gma3_dmx. It clearly establishes the context in which this tool is correct, though it doesn't state explicit exclusions beyond the output-value distinction.

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

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

No annotations are provided, so the description carries the full burden, and it does so well: it declares read-only behavior, the default part value, a bridge version prerequisite ('Needs bridge 0.24.0'), and reports problem states (missing/empty group, missing preset, disabled) plus coverage caveats. It stops short of permission or rate-limit notes, so a 4 rather than 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 key fact ('Read-only') and the target spec before the long return-value enumeration. It is dense and reads as one long sentence, but nearly every clause carries distinct information, so it is appropriately sized for the complexity.

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

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

There is no output schema, so the description must explain returns, and it does: recipe lines, selections, values, MAtricks, filter, Enabled, cooking state, problems, and per-fixture coverage. That covers the nested-return complexity well, though some fields (e.g. MAtricks, SelectionMode shapes) remain undefined.

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 genuinely adds meaning: the preset format ('N.M'), the mutually exclusive preset vs sequence/cue/part shapes, and the part default of 0. The schema only says 'Preset or cue part,' so this is real added value.

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 ('recipe lines of a preset or cue part'), and the target forms are spelled out explicitly. An agent can tell this is a read of recipe data rather than a cook (gma3_cook_recipes) or edit (gma3_edit_recipe) 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 gives the target forms and the default (part 0) but never states when to prefer this tool over siblings like gma3_cue_contents, gma3_edit_recipe, or gma3_cook_recipes. Usage is implied by the target specification rather than declared, and no exclusions are offered.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the dispatched-vs-observed split, that a failing line does not stop a macro, and that prompt lines require operator input. It omits permission/auth requirements and concurrency 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?

Front-loaded with 'EXECUTES:' and fits the essential semantics into one dense block with no filler. It is somewhat run-on with several clauses chained by dashes and parentheticals, but every clause carries information.

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

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

No output schema exists, and the description does describe the return shape (dispatched vs observed, plus the finished/paused_at_go/running/idle states). Combined with zero annotations, the only meaningful gap is the undocumented interval_ms and any error/permission behavior.

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

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

Schema coverage is 0%, so the description must compensate. It documents 'macro' (N), the 'go'/'off' enum, and observe_seconds (default 3, max 60), but leaves interval_ms completely unexplained, leaving one of four parameters undocumented in both schema and description.

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

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

States a precise verb and resource ('EXECUTES: action go sends Go+ Macro N ... off sends Off Macro N') and even disambiguates the two modes. An agent can tell this apart from gma3_store_macro / gma3_edit_macro_line purely from the verb semantics.

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

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

Explains what 'go' means contextually ('starts it, or continues it after a Go wait'), which implies when each action applies, but never states when to reach for this tool instead of alternatives like gma3_command or gma3_macros. Usage is inferable, not explicit.

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

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

With no annotations, the description carries the full burden and does so richly: mutation semantics (add vs replace based on active values), clear_first deterministic option, non-destructive to programmer values, verification of Selection.CountTotalSelected, listing of first 50 members, and serialization scope. This is exactly the behavioral context an agent needs.

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

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

Front-loads the core action and then layers behavioral details in a logical order. It is dense but every sentence adds value; slightly long for a two-parameter tool, though justified by the complexity of the selection semantics.

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

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

Complete for a mutation tool with no annotations and no output schema. It covers side effects, determinism, verification, and serialization limits, leaving no significant gaps for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents both parameters including examples and defaults. The description adds context about clear_first's effect (deterministic result) but no syntax beyond what the schema provides; baseline 3 is appropriate 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 and resource ('Select fixtures ... in the programmer') and immediately grounds it with concrete examples of selection expressions. An agent can distinguish this from siblings like gma3_clear_programmer or gma3_selection_grid 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 describes when the tool adds to vs. replaces the selection, and names clear_first as the deterministic alternative with its precondition. It also delineates behavior vs. siblings by noting it does not clear programmer values.

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