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

With no annotations supplied, the description carries the full burden and does so: it discloses that nothing is sent when pre-checks fail, that the console can answer OK yet change nothing, that ClearSelection is issued with `fixtures`, that a bridge version (0.27.0) is needed for link read-back, and that programmer values are never cleared. These are exactly the side-effect and failure-mode facts an agent cannot infer elsewhere.

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

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

Front-loaded with the action and the target contract, then pre-checks, then read-back. It is dense and technical but nearly every clause carries operational information; the read-back sentence is the only one that takes a second pass to parse (fixtures vs. cells, mismatch definition).

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 six-parameter mutation tool with no annotations and no output schema, the description covers preconditions, targeting, non-obvious failure modes, verification behavior, and destructive scope (never clears programmer). Nothing material 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 coverage is 100%, so baseline is 3, but the description adds cross-parameter semantics the schema does not: the mutual exclusivity of fixtures/use_selection, the implicit ClearSelection-then-select behavior tied to add_to_selection's default, and that a preset applies to any fixture holding its attributes regardless of storage type. That is genuine meaning beyond field-level docs.

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 ('Recall a stored preset into the programmer') plus the console syntax it emits (`At Preset <pool>.<number>`). This clearly separates it from the sibling write-side tools like gma3_store_preset and the generic gma3_command.

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

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

Explicitly states the targeting contract (fixtures OR use_selection: true) and the preconditions that must hold, and explains the failure semantics of an empty target or missing preset. It stops short of naming sibling alternatives (e.g. gma3_preset for inspection, gma3_select for selection) or when not to use it, so it is strong but not fully routable on its own.

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 supplied, the description carries the full burden and does so: it discloses that the call runs one patch session, is isolation-checked, is committed with no undo, and requires exclusive access. It also states what is preserved (FIDs, addresses, cells, groups, preset values) and the minimum bridge version, which is exactly the mutation risk an agent needs before calling.

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

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

Front-loaded with the action, then preconditions, then side effects and return shape — a logical order with no filler sentences. The heavy parenthetical asides make it dense to parse in one pass, so it is efficient rather than elegant.

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 supplies the safety profile, the preconditions, the preserved state, the return payload shape and the version requirement. The only omission is the meaning of `verify`, which is a minor gap against otherwise complete coverage.

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

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

Schema coverage is only 40%, yet the description compensates well: it constrains the target `type` to a layout copy with a matching DMX mode name/channels/footprint, states that `exclusive: true` is mandatory, and explains the `detail` flag's return behavior and the items shape on clean success. The gap is `verify`, which is undocumented in both the schema and the 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 specific verb and resource ('Moves fixtures to another fixture type') and immediately narrows it with the key qualifier that the target must be a layout copy of theirs, or a move back to the original. That distinguishes it clearly from the sibling gma3_layout_cells, which is named as the tool that creates those layout copies.

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 use case ('so several fixtures share one layout') and an explicit precondition for the call to succeed: the target type must have a DMX mode with the same name, channels and footprint, otherwise it is refused. It also states that exclusive: true is required. It stops short of an explicit when-not-to-use case beyond the refusal condition, which keeps it off 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 supplied, the description carries the full behavioral burden and does so unusually well: it warns that the console answers OK to an unknown tag and changes nothing, that ambiguous names are refused, that verify defaults to true with read-back, and that protect sets Kill Instant/Kill Delayed flags. It also discloses batch semantics — items run in order, nothing is retried, an unknown outcome halts the rest, and one line is returned per item.

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 nearly every sentence carries actionable information, but the whole definition is one dense run-on paragraph that mixes purpose, tag resolution, target syntax, protect semantics, version requirements and batch rules. Bullets or sentence breaks would make the same content easier to scan without cutting anything.

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

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

For a 9-parameter tool with no annotations and no output schema, the description covers every parameter, the batch/single duality, per-item outcomes, and the read-back behavior that stands in for a return-value contract. Nothing an agent needs in order 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 coverage is already 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: concrete target formats ('Sequence 950 Thru 952', 'Macro 3.1', 'Sequence 5 Cue 2' landing on Part 0), what data_pool addresses, and the default-inheritance rule for batch items ('the other arguments are defaults for every item'). These are semantics the schema alone would not convey.

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

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

The description opens with a precise verb+resource pair ('Assign a tag to objects, or remove it (off: true)') and even maps it to the console command 'Assign [Off] Tag n At <objects>'. The constraint that the tag 'must exist' implicitly separates it from tag-creating siblings like gma3_store_tag, but no sibling is named explicitly, so differentiation is inferred rather than stated.

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 concrete when-to-use context (target reference syntax with examples, batch form for multiple objects) and an explicit when-not ('Fixtures cannot carry tags'). It stops short of pointing at alternatives such as gma3_store_tag or gma3_configure_tag when a tag does not yet exist, which is the one routing decision an agent would still have to make on its own.

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 pre-flight read-only inspection, the failure-with-previous-assignment outcome, the partial outcome when labelling fails, what verify does and explicitly does NOT verify (config, fader/key functions, playback state), that mutations are serialised, and that a concurrent operator can invalidate the inspection.

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 valuable but delivered as one dense paragraph with heavy parenthetical nesting and several run-on sentences; batch behaviour is introduced twice. A bulleted or sectioned layout would make the preconditions, side effects, and batch rules far easier to scan and would front-load the executor/sequence/page essentials.

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, annotation-free mutation tool with no output schema, the definition covers preconditions (page/sequence must exist), side effects, failure and partial-failure outcomes, verification scope, concurrency risk, and per-item batch semantics with ordering and stop rules — 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 baseline is 3, but the description adds semantics the schema does not: replace gates overwriting, verify defaults true with a stated comparison basis, label renames the underlying object show-wide, and batch items inherit call-level fields while their own fields win, with duplicate targets refused and stop_on_failure skipping previously failed objects.

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 or macro to an executor on an explicit page', including the exact command it emits ('Assign <object> At Page <p>.<e>'). It also distinguishes itself from the sibling gma3_label_executor by warning that labelling here renames the assigned object rather than the 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 guidance: use replace: true when an executor holds another object, the call leaves an already-assigned sequence alone, and the batch form is described as an alternative shape with its own rules. It stops short of naming sibling tools to route to (e.g. gma3_executor_settings, gma3_label_executor) for related tasks.

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 discloses Preview-only operation, separate programmer and selection, ClearAll sent only in Preview, no live output, operator Normal programmer checks, look application order, failure handling that leaves already-stored cues intact, the 2.5.1 readback limitation, exclusive access requirement, playback/observation behavior, and automatic switch-off unless leave_running is true.

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

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

The description is front-loaded with the main action and its sentences mostly carry operational meaning. However, it is a very long, dense single paragraph with nested clauses and repeated technical asides, making it harder to scan than necessary for an already complex tool.

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

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

For a complex 18-parameter tool with no output schema, the description is complete enough to call the tool correctly. It covers build semantics, failure behavior, Preview isolation, verification/observation, timing limits, default behavior, and the shape of the returned result.

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

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

Schema coverage is high at 83%, so the schema already documents most parameters. The description still adds useful meaning: steps versus presets mode, cue-per-step timing, replace semantics that preserve executor assignments, observe behavior and its defaults, observe_max_seconds limits, and compact versus detail result modes.

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

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

The description states a specific verb and resource: build a looping chase into an empty/new sequence, or rebuild one with replace: true. It distinguishes the operation from simple cue storage by explaining that it creates one Time-triggered cue per step, enables Wrap Around, and optionally observes a full cycle.

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 applicability conditions: the target sequence should be empty or new, and replace: true is required to rebuild one that already has cues, otherwise the sequence is refused. It does not explicitly compare against the sibling gma3_store_cues beyond referencing shared parameters, so the alternative-routing guidance is good but not complete.

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 supplied, the description carries the full behavioral burden and does so thoroughly: the effect is built in the console's Preview environment with its own empty programmer and nothing is output, the Normal programmer is fingerprinted before and after and 'is never touched', the stored programmer is verified per fixture/step/layer, and Preview is cleared and exited in every case. It also discloses the exclusive-lock requirement, audition playback/release behavior, and the bridge 0.23.0 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?

The first sentence is well front-loaded, but the remainder is a dense run-on of parentheticals and semicolon chains that is hard to scan, and much of the phase/template detail is duplicated in the schema's own parameter descriptions. For a 19-parameter tool some length is justified, but the structure could be sectioned or trimmed without losing meaning.

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

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

For a 19-parameter tool with deeply nested objects and no output schema, the description covers everything an agent needs: how steps/templates/effects compose, how variants map onto consecutive presets and their naming, what preview and detail return, how verification and cleanup work, and the name-collision policy tied to gma3_store_preset rules. Nothing material about correct invocation is left unstated.

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

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

Schema coverage is 100%, but the description goes well beyond the schema by explaining semantics that the JSON schema cannot: phase distribution edge cases ({from:0,to:360} vs. other ranges, 'spread' being 360 x (n-1)/n), the measure/step-width relationship ('step widths ... should add up to measure x 100'), mirror inversion math (percent 100 - v), and what each variant name produces. It also explains template option sets (dimmer_chase, pan_tilt, circle, comet, etc.) that the schema only lists by 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?

The opening sentence gives a specific verb, resource and outcome: 'Build a repeatable effect from structured steps and store it into Preset <pool>.<number>, reading every step back.' It is clearly distinguishable from siblings like gma3_store_preset (plain storage) or gma3_phaser_release (cleanup) because it names the phaser-construction and preset-store combination.

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 concrete operating conditions: preview returns the plan without sending, exclusive:true is required unless previewing, audition_ms needs an empty Normal programmer, and gma3_phaser_release should be used if a build is interrupted. It does not, however, explicitly contrast this tool with alternatives such as gma3_store_preset or the matricks/recipe tools, leaving the 'which tool for this job' routing partly 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 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?

With no annotations, the description carries the full burden and does much of it: no pre-check and no read-back, return of command-line feedback (OK, Syntax Error, Illegal Command), output-producing commands going to console history instead, $variable expansion only outside quotes with shadowing and silent no-op on a missing variable, and fire-and-forget OSC with no feedback. The remaining gap is that it never states permission/authorization needs or that commands mutate live show state irreversibly (e.g. ClearAll, Store).

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 FALLBACK framing, then examples, then return format, then caveats — a sensible order with no filler sentences. It is dense and long for a two-parameter tool, and the parenthetical SU-15 probe anecdote is more detail than an agent needs to invoke it.

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, yet the description explains exactly what is returned (command-line feedback) and what is not (List/GetGlobalVariable output), covers both transports, and handles the variable-expansion edge cases. For a raw command passthrough with no annotations, nothing essential to 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 100%, so the baseline is 3, but the description adds real meaning: the command string is typed exactly as on the console without Please/Enter, with four worked examples, and $variables expand outside quotes. The enum for 'via' is already documented in the schema, and the description's OSC note adds the fire-and-forget consequence rather than duplicating it.

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

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

States a specific verb and resource ('Execute a grandMA3 command-line command exactly as it would be typed (without Please/Enter)') and immediately frames the tool as a FALLBACK relative to the structured tools that cover patching, looks, presets, groups, phasers, cues, chases and playback. An agent can tell precisely what this does and how it differs from every sibling category.

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 routing rules: use this only when no structured tool covers the action, because structured tools check before acting and read back while a raw command does not. It also names concrete redirections for adjacent needs (gma3_get_object / gma3_list_children for reading data, gma3_variables / gma3_set_variable for variables) and warns that List/GetGlobalVariable output does not come back 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 burden and does so well: it discloses that changes are validated before sending, that the console silently ignores or clamps invalid values yet every written property is read back, that there is no undo but previous holds prior values, and that network/exclusive confirmations are mandatory.

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 packed with useful detail; nearly every clause adds information. However, it is delivered as one long semicolon-chained sentence with nested parentheticals, which makes it dense rather than easily scannable.

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, multi-parameter mutation with nested objects, no annotations, and no output schema, the description supplies prerequisites, universe ranges, clamp/verify behavior, and undo semantics. The remaining holes are the meaning of verify and any statement of what is returned, though 'every written property is read back' partially covers the latter.

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 25%, but the description compensates heavily: it explains entry add/remove/edit-by-number semantics, local_universe..+amount-1 mapping, Art-Net absolute universe ranges (0..32767) versus sACN (1..63999), mode, enabled, sACN priority 0..200, and grant_request's universes/value auto|on|off. The verify parameter is left unexplained in both schema and description, which is the main gap.

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: changes the console's DMX output configuration, covering protocol output state, entry mappings, and grant requests. It is clearly distinguished from read-oriented siblings like gma3_dmx_output and gma3_dmx by framing everything around mutation of configuration entries.

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 conditions for use: network:true is required when the change makes a protocol send DMX onto the network, exclusive:true is required, bridge 0.30.0 is needed, and preview:true shows the plan first. It doesn't explicitly name an alternative tool for simply reading the current config, so it stops short of full when-to-use/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 full burden and does so: writes are validated against the assigned class, locked targets are refused up-front (the console silently ignores writes), unlock applies changes then relocks even after failure, first set failure aborts the rest, read-backs must match, unreadable values are treated as unknown rather than defaulted, and mutations are serialised but not isolated from other clients. Shrink-before-growth ordering and pre-write collision checks are exactly the kind of non-obvious behavior an agent needs.

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

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

The purpose and the primary alternative are front-loaded, and every sentence carries substantive constraints. However, the block is extremely dense and several sentences chain multiple rules with semicolons (lock/preview/verify/failure handling), making it harder to scan than a short bulleted structure would be.

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 22-parameter mutation tool with no output schema, the description covers what an agent must know: preview returns planned from -> to changes, verify defaults true and reads back, playback state is reported as activeBefore/activeAfter, unchanged values are never sent, and refusal conditions (page lock, collisions, footprint expansion, unknown dependencies) are enumerated. Return-value behavior is described even though 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 coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot express: encoder continuous functions vs discrete custom commands are mutually exclusive and conflicting requests fail before reads, custom command text is stored but never executed and requires explicit enabled because the console auto-enables it, and edge whitespace is refused because object reads trim it. This goes meaningfully beyond the per-field 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 opening sentence names a specific verb (Set), the exact resources (key/MA-key/fader/encoder functions, custom command triplets, Width/Height, Fix), the target (Sequence or Macro executor at Page <p>.<e>) and the mechanism (writing properties). It also distinguishes itself from 'Assign <function> At' in the same breath, so an agent can select it without ambiguity.

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

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

Explicitly routes the agent elsewhere: sequence-level settings (Wrap Around, priority) belong to gma3_configure_sequence, and the difference from 'Assign <function> At' is spelled out. It also states what this tool will never do (send Go/On/Off/Toggle/Flash, touch selection, programmer or fader levels), which is a clear when-not-to-use boundary.

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 supplied, the description carries the full burden and does so: it discloses that 'Store MAtricks' copies the programmer's selection MAtricks, that each value is a separate set whose reply is read back, that the console silently ignores rejected values, that the first failure aborts the rest, and that locked or duplicate-named objects are refused before anything is sent. These are exactly the operational hazards 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-loaded with the core operation and property list, then layered with create/overwrite semantics and failure behavior — no filler sentences. It is, however, one very dense block of long clauses (parentheticals, em-dashes) that is harder to scan than it needs to be.

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 nested mutation tool with no annotations and no output schema, the description covers the gaps that matter: mutation scope, overwrite semantics, error/refusal conditions, verification read-back, and how to actually apply the result. Nothing an agent needs to call it safely appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains that wings distributions run from outer edges (from) toward the centre (to) and gives a worked example (wings 2 with delay {from: <outer>, to: 0}), plus units for fade/delay (seconds), phase (degrees) and speed (BPM), and the null/0 = None convention. The verify parameter's read-back comparison is only implied rather than stated.

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

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

The description opens with a specific verb+resource ("Set MAtricks <n> per axis") and enumerates the properties it writes, so the operation is unambiguous. It also discloses the create-vs-update dual nature up front. It does not, however, name the sibling read tool (gma3_matricks) or otherwise explicitly distinguish itself from it, so 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?

Strong contextual guidance: create:true for missing objects, reset_unspecified:true for full overwrite of an existing one, preview:true to dry-run, and on_name_taken to control collision handling. It also clarifies that it does not touch the programmer and must be applied via 'Recall MAtricks <n>', which tells the agent this is a configuration not an application step. Lacks explicit routing to a sibling tool.

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

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

With no annotations supplied, the description carries the full burden and does so: lines are UDP, changes are validated first, every write is read back, a port change on a receiving line re-binds input with ~0.4 s of downtime, there is no undo but previous holds prior values, and bridge 0.33.0 is required. It also discloses the security consequence of network: true (the console listens on every interface, so reachable parties can run commands), which is exactly the kind of beyond-schema behavior 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?

It is front-loaded with the core action and every clause (downtime, undo, version requirement, security gate) earns its place. The middle section is a dense run-on that could be split into bullets, but nothing is redundant filler.

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

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

For an 8-parameter mutation tool with a nested line array, no annotations, and no output schema, the description covers safety, reversibility, downtime, prerequisites, and a testing sibling. It omits return-value expectations and leaves verify and the enable_input/enable_output switches unexplained, so it is strong but not fully complete.

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

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

Schema coverage is only 25%, so the description must compensate, and it largely does: it enumerates the per-line fields (name, port, prefix, destination_ip, receive, receive_command, send, send_command, echo_input, echo_output, note) and explains the semantics and prerequisites of network, preview, and exclusive. Gaps remain for verify, enable_input/enable_output, and how the line number field addresses an existing line versus add/remove.

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

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

The description opens with a specific verb-and-resource statement: switch OSC input/output, set the preferred IP, and add/edit/remove OSC lines. It even enumerates the line fields, so an agent knows exactly the resource being mutated and can distinguish it from read-only siblings like gma3_osc.

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 concrete operational guidance: requires exclusive: true, preview: true shows the plan, test with gma3_test_osc_input, and network: true is required in two named situations. What it lacks is an explicit statement of when to use this versus gma3_osc (presumably the inspection counterpart), so routing between those two 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 burden and does so thoroughly: it states the tool never sends playback keywords, does not touch selection/programmer/fader levels, refuses locked targets unless unlock is set (with relock attempted even on failure), warns when other executors share the sequence since settings apply to every referencing executor, and describes serialisation without isolation from other operators. Failure semantics (first failed write stops remaining changes, unknown values refuse the call rather than defaulting) are unusually well disclosed for a mutation tool.

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

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

The purpose and the safety constraints are front-loaded, and most sentences carry real information, but the property enumeration is a long run-on list and the block of failure/verify/preview semantics is dense with no structural breaks. It is information-rich but overstuffed for a single paragraph, hurting 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 32-parameter mutation tool with no annotations and no output schema, the description covers what an agent needs: what each group of settings does, that changes are read back and compared, what preview returns (from -> to), what the batch result shape looks like (one line per sequence, detail for full steps), and how failures and locks are handled. Nothing critical to correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: wrap_around is explained as only looping a chase when a trigger sits on the first cue, kill_protect/swap_protect are clarified as protection from Kill/Swap playback actions rather than editing, and rate_master is explained as cue timing running at BPM/60 with 60 BPM as 1:1, plus the rule that masters are linked by unique name. These are semantics the schema does not convey.

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

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

The description opens with a specific verb+resource ('Set a sequence's playback settings by writing its properties') and immediately delineates the boundary against siblings by naming gma3_set_cue_trigger and gma3_set_cue_timing for cue-level work. An agent can tell this is the sequence-property writer, not the cue editor or executor config tool.

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

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

It gives clear conditions for preview (read-only plan), verify (default true), unlock (required for locked targets), and batch form via 'sequences', and it redirects cue triggers/timing to the correct sibling tools. It does not, however, position itself against gma3_set_property or gma3_configure_executor, so an agent must infer those 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?

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?

With no annotations, the description carries the full burden and does so: it discloses pre-send validation ('values outside these lists are refused before anything is sent'), a hard bridge version requirement (0.36.0), read-back behavior, and a destructive side effect ('Kill Instant turns the other tagged sequences off when one starts'). Batch execution semantics are spelled out in detail: in-order, no retries, unknown outcome halts the remainder, one result line per item.

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 front-loaded with the settable fields, then the semantics, then the batch contract, so structure is sound and every clause carries information. It is dense to the point of being cramped, with stacked parentheticals like '(live, onPC 2.5.1)' and '(the manual: otherwise it works once they have been started)' that slow parsing.

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 mutation tool with no annotations and no output schema, the description covers side effects, validation, ordering, failure behavior and the shape of the return value (one line per item, detail for steps). It leaves stop_on_failure undescribed and its claim that 'an unknown outcome stops the rest' sits uneasily beside the schema's stop_on_failure default of false, leaving the agent to reconcile the two.

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: forward_commands is explained concretely ('whether Go+ Tag n / Off Tag n reach the tagged objects'), appearance null clears, and the default-vs-override rule that an item's own fields win over the batch-level arguments. stop_on_failure and verify are only implicitly touched ('read each one back').

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

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

The description opens with a specific verb plus resource and enumerates exactly what gets set: type, forward commands, pool action, appearance and note, followed by read-back. An agent can distinguish this from gma3_store_tag or gma3_delete_tag on the verb alone, though no sibling is named explicitly.

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

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

It gives a concrete condition for the single-object form versus the batch form ('give the list instead of the single object's fields') and states that the type must be set before the sequences run. It does not explicitly route the agent to gma3_store_tag for creation or state when this tool is the wrong 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, the description carries the whole burden and does it well: the plugin re-reads every 0.5 s, values are saved with the show, null clears a key, resync sequences must already exist, and reported problems after the change are returned. It also discloses a hard rejection case and a bridge-version prerequisite, which an agent could not learn 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?

It is a single dense sentence-chained paragraph with zero filler, and the action verb plus read-back behavior are front-loaded. Readability suffers from the parenthetical stacking (bdstark/gma3-beat-sync; BeatSync.*, read every 0.5 s), but nothing is redundant.

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

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

For a 13-parameter, zero-required, no-output-schema mutation tool with no annotations, the description covers defaults (presumably null = unchanged/clear), side effects, prerequisites, error behavior, and every parameter's domain. An agent has enough to invoke it correctly without opening the schema.

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

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

Schema coverage is only 8% across 13 parameters, and the description compensates thoroughly: numeric ranges (master 1-16, quantum 1-64, lead_ms 0-200), the meaning of start_stop and resync formats, the actions array shape with slot/every/phase/command plus clear:true, and the null-clears-a-key convention. This adds real meaning beyond the bare JSON types.

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

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

Opens with a specific verb and resource: 'Set or clear the tempo-sync plugin's configuration ... then read it back', naming the plugin, its backing store (BeatSync.* console variables) and the read-back. It does not explicitly name the sibling gma3_tempo_sync_status, so an agent must infer that the status tool is the pure-read alternative.

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: works whether or not the plugin runs, requires bridge 0.31.0, and explicitly excludes a tempting field ('Interfaces (multicast) is a network setting and is refused'). It stops short of stating when to prefer gma3_tempo_sync_status over this tool for read-only inspection.

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?

Without annotations the description carries the full burden, and it does disclose meaningful behavior: the 20-sequence cap, the playback state machine (active, currentCue {no, name} while playing, lastCue after Off) and a bridge version requirement. It does not state pagination behavior for limit/offset or any read-only/permission expectations.

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 tightly packed sentence with no filler, front-loaded with the verb and resource. The trailing parenthetical of domain jargon (TrigType, TrigTime, bridge 0.32.0) makes it dense but each element 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?

There is no output schema, so describing the returned cue fields and playback shape is essential and the description does exactly that. The remaining gap is pagination semantics for the limit/offset parameters on a tool that can span up to 20 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 coverage is 67%, and the description adds real meaning beyond it by giving the mutual exclusivity and maximum cardinality for 'sequences' ('up to 20') and by tying 'sequence' to a single read. It says nothing about limit, offset, fields or data_pool, which are left to the schema.

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

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

States a concrete verb and resource ('List the cues of one sequence ... or several') and enumerates the returned fields (cue number, name, trigger, command, playback state), so an agent can distinguish it from gma3_cue_contents or gma3_store_cue 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 implies read usage and clarifies that 'sequences' is used 'instead of sequence', which is useful parameter-level routing, but it never names alternatives such as gma3_cue_contents or says when a caller should prefer one over the other.

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

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

No annotations are supplied, so the description carries the full burden and does so: pre-existence check with refusal before sending, read-back verification with matched/mismatched/unavailable outcomes, no change to selection or programmer, never retried, and an explicit caveat that the mutation lock does not isolate from other console 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 core action and command, then layered with constraints and return semantics; nearly every sentence is load-bearing. It is dense and telegraphic, with a few clauses that read as run-ons rather than flowing prose.

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 supplies the missing behavioral and return-shape vocabulary (verification statuses) plus concurrency caveats. An agent has what it needs to call it safely and interpret the result.

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

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

Schema description coverage is 100%, so the schema already documents cue, verify, sequence, data_pool, and use_selected_sequence. The description reinforces the single-cue-number rule but adds no format or resolution detail beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete exactly one explicit cue') and even gives the exact console command issued. It implicitly distinguishes itself from sibling tools like gma3_store_cue and gma3_edit_cues by insisting on a single explicit cue and rejecting ranges.

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 when-to-use constraints: one explicit cue only, ranges (Thru, +) rejected, and the operation is refused if the cue does not exist. It does not name a sibling alternative for range deletions, but the usage envelope is unambiguous.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses the reverse-lookup reporting (removedFrom before delete), post-delete re-reads (stillCarries), the empty-slot read-back, and a hard bridge version prerequisite (0.36.0). Batch behavior is unusually well specified — ordered execution, no retries, an unknown outcome halting the remainder. Missing only side-effect framing such as whether the delete is undoable or what authority is required.

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 scope, then layered single-form, prerequisite, and batch rules in a logical order. It is a single dense paragraph with some run-on clause chaining that could be split, but no sentence is padding.

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

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

For a five-parameter mutation tool with no annotations and no output schema, this covers verification, per-item reporting, failure propagation and a version gate — nearly everything an agent needs. The remaining gap is the absence of any statement about permissions or irreversibility, which matters for a destructive operation.

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; the description still adds real meaning by explaining the collision rule behind the `tag` parameter and the inheritance model for `tags` (item fields win over the shared defaults). The `detail` semantics are restated in prose ("detail: true for every step"), which slightly duplicates the schema but reinforces the per-item output shape.

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

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

Opens with a specific verb and resource ("Delete a tag") and pins the identifier form: number or exact name, with ambiguity refused. That is enough for an agent to separate it from gma3_store_tag, gma3_assign_tag and gma3_configure_tag 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 a clear rule for choosing the batch form over the single form ("give the list instead of the single object's fields") and explains how per-item and default arguments interact. It stops short of naming sibling tools or stating when tag deletion is preferable to reconfiguring/ungrouping, so usage context is clear but not fully 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?

With no annotations supplied, the description carries the full burden and delivers: read is read-only, press requires exclusive: true, the guard fields must match what read returned ("" when untitled), and the dialog is re-read afterwards returning closed, replaced, or still open. It goes further than most by warning that what a button does has NO UNDO and that the console's last command does not name the button, so the effect must be checked on the object.

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?

Nearly every clause carries distinct operational information, and the when-to-use condition is front-loaded. It is a dense block of semicolon-joined fragments rather than a structured list, which costs some scannability for a tool with two modes and four optional guard parameters.

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 enumerating what read returns (class, title, message, buttons with text and enabled, or open: false) and the three post-press states. For a five-parameter, annotation-free tool with irreversible button presses, that covers everything an agent needs to call it safely.

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 80%, so most parameters are already documented; the description still adds the purpose behind them — expect_title/expect_text exist as a safety comparison against the live dialog, and button must match the exact text read listed and be enabled. It adds a little more with the collapsed-whitespace comparison rule, though it does not restate the action enum values beyond the read/press behaviour split.

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

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

The description states a specific verb and resource — read the top modal or press one of its buttons — and scopes it precisely as the fallback 'for a dialog no structured tool answers, e.g. a macro's Lua Confirm()'. It also names the sibling that reports the trigger condition (gma3_run_macro) and the siblings that handle their own dialogs, so an agent can separate it from every other tool in the list.

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

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

It gives both directions: use it only for dialogs nothing structured covers, and skip it for gma3_save_show and gma3_patch_move which answer their own dialogs. It also prescribes the operating order — read the message first, then press — and states that a mismatched dialog is never answered.

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 supplied, the description carries the full burden and does so thoroughly: read-only with no effect on selection/programmer/playback, the granted:false/no-values limitation, outputState rationale, the bounded patched mapping and the 16-bit split into two 8-bit addresses. This is exactly the behavioral context an agent needs before calling.

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 and constraints, then parameter notes; every sentence is substantive. It is dense and slightly repetitive around the nonzero_only spelling alias, which keeps it from a perfect 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?

For an 8-parameter, annotation-free, no-output-schema read tool, the description covers return semantics (values, granted, limitations, outputState) and all behavioral caveats. 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 100%, so a 3 is the baseline, but the description adds real meaning: unit is framed as explicit with conversion semantics, the from..to vs from+count exclusivity is stated along with the default that neither reads the single address, and the nonzero_only/nonzeroOnly alias is explained. It does not add anything about patched failure modes beyond 'stated in limitations', so not 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?

Opens with a specific verb+resource: 'Raw DMX output for an explicit universe and channel range'. It further distinguishes itself from nearby tools by naming gma3_dmx_output for the whole picture and by explicitly separating DMX output levels from programmer values (gma3_programmer).

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 usage context: works with gma3_lua disabled, requires plugin >= 0.3.0, and defers to gma3_dmx_output for broader state. It does not spell out explicit when-not conditions (e.g. when to prefer gma3_fixture_output), so it stops just short of a 5.

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

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

With no annotations, the description carries the full burden and does substantial work: it declares itself read-only and, more usefully, explains the diagnostic states returned (idle, not granted with no output and unreadable values, granted but unsent, sent as which universes). It also discloses a version prerequisite ('Needs bridge 0.30.0'). It does not state what happens if the bridge is older, nor anything about size/limits of the response.

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 key constraint and the usage rule are front-loaded, but the middle is a single sprawling sentence dense with stacked parentheticals that is hard to parse at a glance. Since there is no output schema, enumerating return contents earns its place, but the packing is inefficient.

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

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

For a one-optional-parameter read tool with no output schema, the description does the necessary work of describing what comes back and how each universe is classified, plus the bridge version gate. It stops short of covering failure behavior when the prerequisite is unmet or the response is large.

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 optional parameter is already documented as 'Universes to include besides the ones in use.' The phrase 'plus any asked for' in the description mirrors that schema text without adding format, range, or interaction details, so the baseline of 3 applies.

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

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

The description opens with 'Read-only' and names the specific resource: every universe in use, with patch, grant, ports, merge mode, and Art-Net/sACN entries. It does not explicitly differentiate itself from gma3_configure_dmx_output (the write-side sibling), and the field enumeration is dense enough to partly obscure the core purpose, but a verb+resource is clearly present.

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

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

Gives an explicit selection rule: 'Use it when gma3_fixture_output or gma3_dmx return no values,' naming two alternatives by name. It lacks an explicit when-not-to-use statement and never mentions the configure counterpart, so it falls short of full routing guidance.

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

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

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 most of it well: it discloses the Time-trigger wipe-to-0 side effect, the Note-based save/restore mechanism, per-property Set() ordering, abort-on-first-failure with per-cue reporting, read-back, and that stored values and the programmer are untouched. Remaining gaps are the return payload beyond wipedTrigTimes and any permission or rate considerations.

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?

Every sentence carries real information, but it is delivered as one dense semicolon-chained paragraph mixing purpose, side effects, selection rules, failure behavior and return behavior. Front-loading is good; scannability is not, and a reader has to re-parse clauses to find the selection rule.

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 19-parameter mutation tool with no annotations and no output schema, the definition covers the risky behaviors, the naming contract, and the destructive Time-wipe consequence, which is the critical part. It is not fully complete: verify, data_pool and sequence semantics are undocumented and the response shape is only partially described.

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 63% schema coverage the description meaningfully compensates, explaining the mutually exclusive cue selectors, that names are positional and one per cue, that trigger accepts go/time/follow/sound/bpm with time implications, and that command vs commands differ in cardinality. It leaves verify, sequence and data_pool unexplained, but the added semantics clearly exceed the schema alone.

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

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

The description opens with a specific verb and resource: 'Edit existing cues of a sequence in one call', and enumerates exactly which properties (trigger, timing, name, command) can be changed in bulk. It is clear what the tool does, but it never names the single-cue siblings gma3_set_cue_timing, gma3_set_cue_trigger or gma3_store_cue, so the agent must infer the boundary itself.

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?

Strong in-tool guidance: the agent is told to select cues with exactly one of cues, from/to or all, and that calls are refused when the sequence or a listed cue is missing or the name count mismatches. The keep_times/restore_times pairing is explained as a when-to-use contract. What is missing is routing guidance between this bulk editor and the single-cue siblings.

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

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

With no annotations provided, the description thoroughly discloses mutation and failure behavior: stale identities, locks, and read-only properties are refused; removals target confirmed GUIDs; writes require read-back; and uncertain writes stop the plan. It also covers preview non-mutation, post-edit verification limits, serialization without cross-client isolation, and the absence of macro, sequence, or layout-element execution.

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

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

The description is front-loaded and nearly every sentence supplies a useful constraint, prerequisite, or boundary. However, it is a very dense single paragraph, and the command-level implementation details make it harder to scan than a short overview followed by grouped operation and safety notes.

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 nested batch-mutation tool with no annotations or output schema, the description supplies unusually complete invocation context: prerequisites, per-operation behavior, validation, side effects, verification, concurrency limitations, and explicit non-goals. An agent has enough information to construct edits safely and understand what success does and does not prove.

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?

Despite 0% schema description coverage, the description explains nearly all consequential inputs, including geometry units and ranges, identity provenance, supported object classes, replacement semantics, appearance-pool addressing, text formatting constraints, visibility values, and preview behavior. It adds operational meaning rather than merely restating field names or types.

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

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

The opening sentence precisely defines the operation and scope: applying up to 100 element edits within one existing layout and data pool. It then distinguishes add, update, and remove behavior and explicitly excludes clearing or rebuilding the layout and configuring Layout Viewer 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?

It gives concrete prerequisites for each operation, including required geometry for additions and current element numbers and GUIDs from gma3_layouts for updates and removals. It also explains when replace_object is necessary, how to use preview safely, and which tasks are outside the tool's scope.

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 supplied, the description carries the full burden and does so: it discloses the locked/running-macro refusal, reference checking unless raw, the upward-only move workaround, mandatory read-back with order/content comparison, and the batch failure model (stop on first failure, no retries, skip items on already-failed objects). These are behaviors no schema field could convey.

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

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

Action semantics are correctly front-loaded, but the batch behavior is stated twice in overlapping sentences ('the edits run in order...' then 'give the list instead of the single object's fields...'), and the parenthetical chaining makes it dense and hard to scan for a 20-parameter tool.

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

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

For a complex 20-parameter, mutation-heavy tool with no annotations and no output schema, the description covers ordering, failure semantics, verification, and action-specific requirements. Gaps remain around verify, preview, and macro's defaulting behavior, plus what a successful result actually contains beyond 'one line per item'.

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?

Coverage is 40% across 20 parameters, and the description compensates well for the key ones: line bounds, to as move destination, raw bypassing reference checks, detail controlling per-item verbosity, and each action's applicable fields. It leaves macro, verify, and preview unexplained in both schema and description, which keeps it short of 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?

The description names the resource (a macro line) and enumerates the four concrete operations (insert, set, move, remove) with their operand rules, and the title states the crucial scope: 'never runs it'. An agent can distinguish this from gma3_run_macro and gma3_store_macro without opening the schema.

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

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

It gives per-action conditions (insert needs command, line range 1..count+1; set accepts specific fields; move is sent as upward moves only) and explains when to use the batch edits form versus the single object form, including that top-level arguments become defaults. It stops short of naming an explicit alternative for execution, though 'never runs the macro' plus the gma3_run_macro sibling makes the exclusion inferable.

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 supplied, the description discloses reference validation, full line readback, automatic MergeLowPriority re-cooking, output disappearance after removal, before-and-after coverage reporting, and deferred background cooking after group or preset changes. It also explains that a newly disabled line never cooks and that preview returns planned commands, making both destructive and deferred effects unusually visible before invocation.

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 and compact action syntax are front-loaded, and essentially every sentence conveys operational information rather than repeating structured fields. However, the long single paragraph and dense brace-and-semicolon notation reduce scannability; short action and behavior sections would be easier to use.

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 mutation tool with nested targets, no annotations, and no output schema, it covers preconditions, per-action invocation, validation, verification results, automatic and deferred side effects, exclusions, alternatives, and preview behavior. The few remaining addressing details are reasonably recoverable from the schema, so an agent has enough context to select and invoke it correctly.

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

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

Beyond the 64%-covered schema, it maps parameters to each action, explains the otherwise undocumented enabled and preview behavior, and clarifies values formatting, null clearing, and the practical rejection of numeric preset values. The shorthand set {line, ...fields} and the lack of explicit examples for alternative nested target forms leave small gaps, but the description substantially compensates for the schema.

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

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

The opening sentence precisely identifies the operation, resource, scope, and precondition: editing one standard recipe line of an existing preset or cue part. It then distinguishes all four actions and later excludes phaser lines, filters, and per-line MAtricks columns, clearly separating this tool from its recipe-related siblings.

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

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

Explicit exclusions route bulk cue editing and per-line column work to gma3_store_recipe_cues, while immediate verified cooking is routed to gma3_cook_recipes. Action-specific requirements, the existing-target precondition, and the distinction between automatic background cooking and immediate cooking provide concrete selection 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 supplied, the description carries the full burden and does so unusually well: it discloses refusals (missing targets, locks), that preview:true sends nothing, that selection/programmer/faders/trigger playback are untouched and stored custom commands are not executed, that mutations are serialised only within this server while other clients can change references, that uncertain commands are never retried, and that returned functions are observations rather than verification of a saved profile. It also explains the verification approach (read-back of identity, unchanged assigned object, expected dimensions) and why saving profiles is unsupported.

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 sentence and every subsequent sentence conveys a distinct safety or planning fact. It is dense to the point of being hard to parse in one pass, and the closing note about Store Page At Configuration is an aside that could be trimmed, but the content is not 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 an 8-parameter, mutation-capable tool with no annotations and no output schema, the description covers mode selection, planning, locking, side effects, serialisation and verification scope. The remaining gap is that it never describes the shape of a successful response or what a plan result looks like, which matters since 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 only 13%, so the description must compensate, and it largely does: it ties page/executor to the Assign syntax, configuration to <n>, apply to committing a recast, preview to sending nothing, data_pool to the pool scan, and executors to the exact {data_pool,page,executor} match requirement. It adds the constraint (must match the fresh affected list) that the schema cannot express, though it does not clarify units/ranges for page, executor or data_pool beyond what the schema has.

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 two concrete operations on a specific resource: load an existing Configuration onto an explicit page/executor, or recast its functions across all referencing executors, and gives the underlying command syntax (Assign Configuration <n> At Page <p>.<e> / Recast Configuration <n>). That is specific verb+resource, though 'recast' is domain jargon and the description never distinguishes this tool from nearby siblings such as gma3_assign_to_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?

It gives clear conditions for each mode: load for a single explicit page/executor, recast for all referencing executors, with recast defaulting to a read-only plan that requires apply:true plus an executors list matching the fresh affected list. It also states prerequisites for failure cases (missing/unreadable targets and page/executor locks are refused, so unlock first). It stops short of naming an alternative sibling tool when this one is the wrong 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 supplied, the description carries the full burden and does reasonably well: it discloses the exact returned fields and the state machine for sequences (assigned.currentCue {no, name} while playing, assigned.lastCue after Off) plus a bridge version dependency. It does not state read-only-ness explicitly, pagination behavior, or cost/latency of polling live console 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?

Two sentences, front-loaded with the operation and its returned fields, followed by the numbering reference an agent needs for the range parameters. The second sentence is heavily compressed and ends with a vague 'etc.', but nothing is truly redundant.

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

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

For a three-parameter, no-output-schema read tool with no annotations, the description supplies what an agent needs: returned fields, playback-state semantics, and the numbering scheme for the range. Minor ambiguity remains between 'current executor page' scoping and the default 101-315 range, and no guidance is given on the volume or format of the result.

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

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

Schema coverage is 100% and all three parameters document their defaults, so the schema already does the heavy lifting. The description adds real meaning for from/to by explaining the executor numbering layout (101-115 top row, 201-215 faders, 301-315 etc.), which helps an agent choose a sensible range, but only_assigned is not elaborated beyond the schema text.

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

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

The description opens with a specific verb and resource ('List executors on the current executor page') and enumerates the returned fields (assigned object, key/fader functions, master fader level, playback state). It does not explicitly differentiate itself from overlapping siblings such as gma3_executor_configuration, gma3_executor_settings or gma3_get_fader, 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?

There is no explicit when-to-use or when-not-to-use statement and no named alternative, despite several sibling tools that also surface executor state. An agent must infer that this is the read/inspection path while gma3_executor_configuration and gma3_configure_executor are the mutation paths.

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 the operation is side-effect free, explains cross-data-pool behavior (sequence read by reported address; dataPool: other, ref: null), defines failure semantics (unreadable values become null and are listed in 'unreadable'), and warns that sequence settings are shared by every referencing executor. Missing only operational context such as whether the console must be connected or how large the references scan can be.

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 safety statement is front-loaded, but the body is a single sprawling sentence built from semicolon-separated clauses and a trailing parenthetical field list ending in an ellipsis. The elision ('...') leaves the enumeration open-ended and the density makes it hard to scan. It conveys a lot, but the structure works against comprehension.

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 thoroughly: object assignment, function mappings, locks, sequence playback fields, ownership of protection settings, and referencing executors. Combined with explicit null/unreadable semantics, an agent has enough to interpret results correctly; only the 'references' parameter behavior is left unaddressed.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema, establishing a baseline of 3. The description adds some meaning, clarifying that the sequence is looked up via the address the executor reports and that settings apply to all referencing executors, but it never mentions the 'references' toggle that controls the pool-wide scan.

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

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

The description names a concrete resource (a specific page.executor address) and enumerates what is inspected: the assigned object, key/MA-key/fader/encoder functions, Fix and Lock, page lock, and for sequence executors the allowed function choices plus the sequence's playback settings. That is far more specific than the title alone. It stops short of naming the sibling write tools (gma3_configure_executor, gma3_executor_configuration, gma3_configure_sequence), so differentiation is implied only by 'Read-only'.

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?

'Read-only' and 'Sends no command and changes nothing' imply this is the inspection counterpart to the configure tools, which is real usage signal. However, no sibling is named and there is no explicit when-to-use versus gma3_executors, gma3_executor_configuration, or gma3_configure_sequence. Usage must be inferred from the read-only framing.

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 supplied, the description carries the full disclosure burden and does it well: read-only guarantee ("never changes selection, programmer or playback"), the data source semantics (output levels, not programmer values), degradation behavior on ungranted universes with outputState explaining each, the 8-bit/16-bit/24-bit combining rule, and pagination. Very little about calling this tool correctly is left unstated.

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

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

Content is front-loaded with the return shape, then limitations, then the alternative tool, which is the right order for a read tool. The single long paragraph with stacked parentheticals (bit-depth explanation, universes caveat) is dense and could be broken up, but nearly every sentence carries information an agent needs.

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 result shape itself — and it does, field by field, including raw value scaling, derived percent, physical conversion labels, and the active channel set. Limitations, prerequisites, and the degraded-universe path are all covered, so nothing critical is missing for a tool of this complexity.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description only restates `nonzero_only` as an explicit filter defaulting to false and mentions pagination generically — consistent with, but not additive to, the schema. 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?

The opening clause names a specific verb and resource ("Current DMX output of one fixture or subfixture per RT channel") and enumerates the returned fields. It explicitly separates itself from gma3_dmx_output ("has the whole picture") and distinguishes DMX output levels from programmer values, so an agent can tell the siblings apart 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?

It gives clear context: works with gma3_lua disabled, requires plugin >= 0.3.0, and points to gma3_dmx_output when the whole universe picture is needed. It also states what is not available (per-attribute cooked output) and that ungranted universes return null plus a limitation. It stops short of an explicit "use this instead of X when Y" rule for every sibling, but the routing context is strong.

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 a good job: it declares the read-only nature, explains axis convention (X stage left, Y upstage, Z up), the console's degree renormalization with a concrete example (0/180/0 reads 180/0/180), and the exact quaternion form. The remaining gap is scope defaults — it never says what is returned when neither fids nor fixtures is supplied.

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 'Read-only.' qualifier, then dense but every sentence supplies interpretation-critical detail (axes, renormalization, quaternion, units). The middle sentence is long and packs three ideas, but nothing is padding.

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

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

There is no output schema, so the description must carry return-value meaning — it covers position, rotation, quaternion and mesh mirroring, which is the important part. It is still silent on the default/all-fixtures case and the response container, so a small but real gap remains for a zero-required-parameter read.

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 fids, fixtures and unit are already fully documented in the schema, which sets the baseline at 3. The description only reinforces that positions follow the requested unit while rotations stay in degrees; it adds no detail on the fids-vs-fixtures exclusivity or the 256-fixture cap 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?

The description names a specific verb ('Read') and a specific resource ('Position, rotation and mesh mirroring of fixtures in the 3D stage'), so the agent knows this is a 3D-geometry read. It does not, however, distinguish itself from adjacent siblings such as gma3_fixtures, gma3_fixture_attributes or gma3_place_fixtures, leaving the agent to infer the boundary.

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

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

Usage is only implied: 'Read-only' hints that this is the query counterpart to a positioning/mutation tool like gma3_place_fixtures, but no alternative is named and no condition for choosing this tool over gma3_fixtures is stated. An agent can guess it is used to inspect existing 3D placement, but must infer it.

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

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

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, the description carries the load and does add non-obvious behavior: property values come back 'as display text' rather than raw values, and children are opt-in. It also discloses the bridge version (0.36.0) and the exact TAGS return shape {tag, name, protect}. It omits error behavior for invalid refs and any cost/size caveats when reading large subtrees.

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 paragraph that leads with what is returned and follows with use cases, with no filler sentences. The trailing TAGS parenthetical is dense but earns its place by explaining an otherwise surprising 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?

For a 7-parameter reader with no annotations and no output schema, the description does the important work of enumerating the returned fields and the shape of the TAGS payload. Remaining gaps are pagination semantics for child_limit/child_offset/child_fields and what happens on an unresolvable ref.

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 71%, so baseline is 3. The description maps the three boolean flags to their effects (properties as display text, optional schema, optional children listing), but says nothing about child_limit, child_offset or child_fields — and the schema itself leaves child_limit and child_offset undescribed, so that gap is unfilled on both sides.

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

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

The description opens with a specific verb+resource ('Read an object from the show data') and enumerates the return payload (name, class, address, properties as display text, optional schema and children). It partially differentiates from siblings by naming gma3_tags for tag listings, but does not distinguish itself from near-overlapping readers like gma3_sequences, gma3_cues 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?

'Use this to inspect sequences, cues, executors, fixtures, presets, groups, macros, pages, settings, etc.' gives a clear use context but no exclusions or routing rules. An agent still has to guess whether gma3_get_object or the domain-specific siblings (gma3_cues, gma3_sequences, gma3_list_children, gma3_dump) is the right call.

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

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

With no annotations, the description carries the full burden and does so: it discloses that output changes live, the crossfade is asynchronous and completion is unverified, nonexistent cues are rejected before anything is sent, selection/programmer are untouched, and verification requires bridge 0.32.0. It even scopes the mutation lock's guarantee honestly by noting it does not isolate 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?

The critical fact ('PLAYBACK MUTATION') is front-loaded and the sentences are information-dense. The clause 'Goto is a playback mutation' is a redundant restatement of the opening label, a small waste in an otherwise tight definition.

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 six-parameter mutation with no annotations and no output schema, the description covers refusal conditions, async timing, verification method, and concurrency caveats well. It stops short of characterizing the returned payload beyond the verification status, which is the one remaining gap for an output-schema-less 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 100%, so the schema already documents all six parameters, but the description adds value by tying them to console syntax ('Goto Sequence n Cue c [Fade s]'), clarifying the fade override intent, and explaining that the current cue is read back a frame later for verification. The verify and sequence-resolution semantics are largely echoed from the schema, which keeps it from 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?

The description names a specific verb and resource ('sends `Goto Sequence n Cue c [Fade s]`, which jumps the sequence to that cue and changes live output'), so the agent knows exactly what console action results. It is clearly separable from siblings such as gma3_store_cue or gma3_set_cue_timing because it emphasizes this is playback, not editing.

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 context for use is explicit: it is a playback mutation that changes live output, and it refuses with nothing sent when the cue does not exist. It also rules out adjacent behavior ('Does not change the selection or the programmer'), though it never names an alternative sibling (e.g. gma3_playback or gma3_command) or states when to prefer those.

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

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

With no annotations, the description carries the full burden and does so thoroughly: [busy] refusals across every client while a key is held or an interaction is open, no retry/replay with uncertain dispatches reported as unknown, and the candid statement that a release is 'dispatched', never 'confirmed', with no UI-effect claim. Prerequisites (operator must enable input=keyboard) and scope limits (not display-scoped) are spelled out.

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, but the body is one dense wall of parentheticals, internal references (KB-29, bridge 0.37.0) and nested clauses that slow parsing. Almost every sentence carries real information, so the problem is structure and density rather than filler.

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

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

For an 8-parameter mutation tool with no annotations and no output schema, the description covers prerequisites, concurrency/busy behaviour, result interpretation and failure semantics. An agent has enough to call it correctly and to explain an outcome without further documentation.

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

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

Schema coverage is already 88%, yet the description still adds meaning beyond it: keys is pressed in order and released newest first (chord tap vs hold), exclusive is the intended long-press that blocks all other input, executor pairs with EXEC, and interaction must be passed while the server has one open. These are semantic constraints the schema alone does not convey.

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

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

Opens with a specific verb set (press, release or tap) and a concrete resource (logical MA hardkey), enumerating the supported keys and the backend used. An agent knows exactly what the tool does, though it never contrasts this with sibling gma3_keyboard or gma3_type, so the boundary with those tools must be inferred.

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 guidance: tap vs press vs keys-chord, exclusive for long-press, press requires an interaction id from gma3_input_interaction acquire, and input is OFF until the operator runs the input=keyboard plugin. Missing explicit routing advice for when to choose gma3_keyboard or gma3_type instead, which is the main 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 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?

With no annotations, the description carries the full burden and does a fair job: it discloses the two data sources (versioned indexed corpus when GMA3_DOCS_URL is set, otherwise the installed manual), the general return shape, and the important safety fact that source examples are never executed. It stops short of covering no-match behavior or error conditions.

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

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

Three sentences, each doing work: purpose first, then accepted input forms, then runtime/return behavior. Dense but readable, with no filler or repetition.

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

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

For a two-parameter read-only lookup with no output schema and no annotations, the description covers purpose, input forms, data source selection, return nature, and a safety guarantee. The main gap is 'max_chars' and what happens when no topic matches.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the required 'topic' parameter well by giving both keyword and topic-phrase examples, but it says nothing about 'max_chars' (presumably a truncation limit), leaving one of two parameters entirely undocumented.

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

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

The description opens with a specific verb+resource combination ('Look up a topic in the grandMA3 user manual') and scopes it to the manual shipped with onPC. It is clearly distinguishable from the operational siblings, though it does not explicitly distinguish itself from adjacent knowledge tools like gma3_lua_api or gma3_command.

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

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

Usage is only implied: the examples of what to pass ('Go', 'Store', 'osc', 'cue timing') suggest consulting the manual for command syntax or terminology. There is no explicit when-to-use or when-not-to-use statement, and no routing away from gma3_lua_api or gma3_command, 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?

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 supplied, the description carries the full burden and does so: it discloses the exact command sent, the blast radius of the mutation (renames the object in its pool and on every other executor it is assigned to), preconditions checked before sending, that selection and programmer are untouched and no playback keyword is emitted, exactly what verify reads back, 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 action and its real meaning, and every sentence carries information (side effects, preconditions, verify scope, concurrency). The middle sentences are dense run-ons with nested parentheses, so it is efficient rather than elegant.

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