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

Annotations indicate this is a non-read-only, non-destructive, non-idempotent, closed-world operation. The description adds that it 'triggers' an action and specifies it's for 'mix on/off air', which provides context about the transition effect. However, it doesn't disclose additional behavioral traits like whether it requires specific device states, has rate limits, or what happens on failure. With annotations covering basic safety, the description adds some value but not rich behavioral context.

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

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

The description is appropriately sized with two sentences: one stating the purpose and effect, and another listing parameters. It's front-loaded with the core functionality. However, the Args section is redundant with the schema, slightly reducing efficiency. Every sentence serves a purpose, but there's minor waste in repeating schema 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?

Given the tool's moderate complexity (triggering a transition with one parameter), annotations provide basic safety info, and the schema fully covers inputs. However, there's no output schema, and the description doesn't explain return values or error conditions. For a non-read-only tool that performs an action, more context on outcomes would be helpful. The description is minimally adequate but has gaps in completeness.

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

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

The input schema has 100% description coverage, fully documenting the single parameter 'dsk' with its type, range, and meaning. The description repeats this parameter info verbatim in the Args section, adding no additional semantic context beyond what the schema already provides. According to the rules, when schema coverage is high (>80%), the baseline score is 3 even with no extra param info in 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?

The description clearly states the specific action ('Trigger an auto transition') and the target resource ('for a downstream keyer'), with additional clarification about what the transition does ('mix on/off air'). This distinguishes it from sibling tools like 'atem_auto_transition' (which appears to be for main transitions) and 'atem_set_dsk_on_air' (which likely sets state rather than triggering a transition).

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

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

The description implies usage context through the phrase 'mix on/off air', suggesting this tool is for toggling a downstream keyer's on-air status via an auto transition. However, it doesn't explicitly state when to use this versus alternatives like 'atem_set_dsk_on_air' or 'atem_cut', nor does it mention prerequisites (e.g., needing a configured downstream keyer). The guidance is implied but not explicit.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, so the safety profile is covered; the description adds real value by stating the on-air state is preserved (non-disruptive effect) and that runtime stats come back. It stops short of saying what happens if auto-switch is not currently running, which the idempotentHint only partially implies.

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

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

Two short sentences, front-loaded with the action and its state consequence, then the return payload. No filler or restatement of the title.

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

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

With no parameters and no output schema, the description carries the burden of return information and does so by naming the two stats returned. Only gap is the no-op case when auto-switch is already off.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies.

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

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

The description names a specific verb and resource ('Stop auto-switching mode') and immediately clarifies the resulting state ('current program input stays on air — switching simply stops following the active speaker'), which distinguishes it cleanly from atem_auto_switch_on and atem_cut_to_active_speaker.

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

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

Usage is implied by the semantics of stopping the mode, and the effect statement helps an agent understand the consequence. However, it never names the counterpart tool (atem_auto_switch_on) or points to atem_get_auto_switch_status for checking state before/after, so 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?

The annotations only indicate this is a non-readonly, non-idempotent, non-destructive operation, but the description adds substantial behavioral detail: continuous monitoring, real-time audio detection, hold time, cooldown, and speaker stickiness. It also explains how each mode behaves, which is far beyond the annotation coverage.

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

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

The description is front-loaded with purpose and modes, then behavior, arguments, and examples. It is longer than a minimal definition but proportional to a nine-parameter stateful tool, with only minor redundancy around defaults.

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 stateful auto-switching tool with nine parameters and no output schema, the description covers modes, timing behavior, defaults, and examples well. It does not describe the return value or explicitly say to use atem_auto_switch_off to stop the mode, leaving small gaps.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters, including intervalMs. The description adds useful mode-specific semantics for ssrcBox, hostInput, guestInputs, transition, and examples, though it omits intervalMs from its Args list.

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

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

The description states a specific verb and resource: start auto-switching mode, continuously monitoring audio and switching to the active speaker. It also distinguishes the three operational modes clearly, so an agent can tell this apart from one-shot switching tools like atem_cut_to_active_speaker.

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 usage context through mode descriptions and examples, including which mode to use for full-screen, side-by-side, and host/guest talk-show scenarios. It does not explicitly reference the sibling stop/status tools, so the when-not-to-use boundary is implied rather than stated.

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

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

Annotations already indicate this is a non-readonly, non-destructive, non-idempotent action. The description adds useful context about using 'current transition settings' and the preview-to-program flow, but doesn't disclose potential side effects (e.g., on-air changes), rate limits, or authentication needs. No contradiction with annotations.

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

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

Two sentences: first states purpose clearly, second documents the single parameter. Efficient and front-loaded, though the Args section is somewhat redundant given the schema. Every sentence earns its place.

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

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

For a single-parameter action tool with full schema coverage and annotations covering safety profile, the description is adequate. However, without an output schema, it doesn't explain what happens after triggering (e.g., success confirmation, error conditions). Could benefit from more behavioral 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 description coverage is 100%, so the schema fully documents the 'me' parameter. The description's Args section repeats the schema info without adding meaningful semantics beyond it. Baseline 3 is appropriate when 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 description clearly states the specific action ('trigger an auto transition'), specifies the transition types ('dissolve, wipe, etc.'), and defines the scope ('from preview to program using current transition settings'). It distinguishes from siblings like 'atem_cut' (immediate cut) and 'atem_preview_and_auto' (sets preview then auto transitions).

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

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

The description implies usage when wanting to execute a transition with current settings, but doesn't explicitly state when to use this vs. alternatives like 'atem_cut' (for immediate cuts) or 'atem_set_transition_position' (for manual control). No explicit exclusions or prerequisites are mentioned.

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

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

Annotations indicate this is a non-destructive, idempotent operation with open-world semantics, which the description doesn't contradict. The description adds valuable context beyond annotations: it specifies the default port (9910) and mentions that it returns connection confirmation with model info, which helps the agent understand the tool's behavior and expected outcomes.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by a structured 'Args' and 'Returns' section that efficiently covers key details without redundancy. Every sentence serves a clear purpose, making it highly concise and well-organized for quick 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?

Given the tool's moderate complexity (network connection with two parameters), rich annotations, and no output schema, the description is fairly complete. It covers the purpose, parameters, and return info, though it could benefit from more behavioral context (e.g., error handling, network timeouts) to fully guide the agent in a production environment.

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?

With 100% schema description coverage, the input schema already fully documents both parameters (host and port). The description adds minimal value beyond the schema, only restating the IP address example and default port. This meets the baseline of 3 since the schema handles the heavy lifting, but no additional semantic insights are provided.

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

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

The description clearly states the action ('Connect to') and target resource ('Blackmagic ATEM video switcher on the network'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from its sibling 'atem_disconnect', which handles disconnection, though the distinction is implied by the verb 'Connect'.

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

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

The description implies usage context by specifying it's for connecting to a network device, but provides no explicit guidance on when to use this tool versus alternatives (e.g., prerequisites, timing relative to other operations like 'atem_get_status'). It doesn't mention any exclusions or direct alternatives, leaving usage somewhat open-ended.

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

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

Annotations already cover key behavioral traits (non-readOnly, non-destructive, non-idempotent, non-openWorld). The description adds context about the transition being 'hard' and 'instant', which clarifies the action beyond annotations, but doesn't detail side effects like on-air changes or rate limits.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by a brief parameter note. It's appropriately sized with no wasted words, though the parameter section could be slightly more integrated for optimal flow.

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

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

Given the tool's moderate complexity (a single optional parameter) and lack of output schema, the description is adequate but could benefit from more context on effects (e.g., immediate on-air change) or error conditions, as annotations don't fully cover behavioral nuances.

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

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

Schema description coverage is 100%, with the schema fully documenting the 'me' parameter. The description adds minimal value by noting it's optional with a default, but doesn't provide additional meaning beyond what's in the schema, aligning with the baseline for high coverage.

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

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

The description clearly states the tool's purpose with specific verb ('perform a hard cut transition') and resource ('preview to program'), distinguishing it from siblings like 'atem_auto_transition' or 'atem_set_transition_style' which imply different transition types or configurations.

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

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

The description implies usage for instant switching from preview to program, but provides no explicit guidance on when to use this vs. alternatives like 'atem_auto_transition' or 'atem_set_transition_style', nor does it mention any prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=false, so the mutation profile is known. The description adds useful behavioral context: detection uses real-time Fairlight audio levels, only listed guest inputs are eligible, and the host is excluded by default. It does not disclose what happens when no guest is speaking or whether preview state changes, which limits it below a 5.

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

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

The definition is front-loaded with the core behavior, followed by params and examples, and is easy to scan. The Args section is somewhat redundant with the fully covered schema, but the examples justify their space by mapping natural language to parameter choices.

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 switching mutation with no output schema, the description covers the detection source, default input ranges, host exclusion, transition behavior, and ME bus. It omits edge-case behavior (e.g., silence, no eligible guests) that an agent might want before invoking it, but overall it is sufficient to call correctly.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters with defaults. The description's Args section largely restates the schema, though it adds a small semantic hint that 'only guests in this list are eligible' and reinforces host exclusion from detection.

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 and resource ('cut full-screen to the active speaker') and defines the selection rule (highest audio level from Fairlight VU data). This cleanly distinguishes it from manual switching siblings like atem_cut and atem_set_program without needing to name them.

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

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

The examples show the practical invocation pattern, including how to get a dissolve via transition="auto". However, it never states when NOT to use this (e.g., when no guests are present) or explicitly routes to alternatives such as atem_set_program for manual selection.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds only that the target is a Super Source look; it does not say what happens if the name does not exist (error vs silent no-op), which matters for a destructive operation.

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

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

The core purpose is front-loaded in one short sentence with no padding. The trailing Args block duplicates the schema and is the only wasted text.

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

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

For a one-parameter delete whose annotations already flag destructiveness and idempotency, the description is adequate. It stops short of describing failure behavior on an unknown name, which is the main remaining gap for a destructive tool.

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

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

Schema description coverage is 100% with a single required parameter already documented as 'Name of the saved look to delete'. The description's Args block merely restates it, adding no format, case-sensitivity, or lookup-behavior detail.

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

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

States a specific verb (delete) and resource (a previously saved Super Source look), so the agent knows exactly what is removed. It does not explicitly distinguish itself from the sibling look-management tools (atem_save_look, atem_load_look, atem_list_looks), though the verb makes the distinction obvious.

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

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

No statement of when to use this versus atem_save_look or atem_load_look, and no prerequisites or exclusions. The phrase 'previously saved' implies the look must already exist, but that is inference rather than guidance.

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

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

Annotations provide key behavioral hints (non-readOnly, non-destructive, idempotent), but the description adds valuable context by specifying it disconnects from an existing connection. It doesn't contradict annotations and clarifies the precondition, though it could mention side effects like terminating ongoing operations.

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

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

The description is a single, front-loaded sentence that directly states the tool's function without any redundant or unnecessary information. Every word contributes to understanding, making it highly efficient and well-structured.

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

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

Given the tool's simplicity (0 parameters, no output schema) and rich annotations, the description is mostly complete. It covers the core action and precondition, but could slightly enhance completeness by noting idempotency or effects on sibling tools, though annotations partly address this.

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

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

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, maintaining focus on the tool's purpose. A baseline of 4 is applied since it handles the zero-parameter case effectively.

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

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

The description clearly states the specific action ('Disconnect') and resource ('currently connected ATEM switcher'), distinguishing it from all sibling tools which perform different operations like connecting, controlling, or querying the switcher. It precisely defines what the tool does 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?

The description explicitly indicates when to use this tool: when there is a 'currently connected ATEM switcher' to disconnect from. It implies an alternative (using 'atem_connect' to connect instead) and excludes use when no connection exists, providing clear contextual guidance.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the agent knows this is a non-destructive, non-idempotent write. The description adds the useful downstream detail that markers are exported as a Resolve markers EDL, but omits the failure mode when no EDL session is active and whether the marker is confirmed in an EDL file or only in memory.

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

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

Two compact sentences, front-loaded with the action, and the parenthetical examples add color without bloat. The phrasing 'while EDL logging' is slightly compressed and could be mistaken for an adverbial clause rather than a precondition.

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

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

For a one-parameter, no-output-schema tool with annotations covering safety, the description supplies adequate purpose and export context. The main missing piece is the session prerequisite and the behavior when it is unmet, which matters because this tool only makes sense mid-session.

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?

With a single optional parameter at 100% schema description coverage ('Marker note', default 'Marker'), the schema fully documents the input. The description adds no information about the note field, which is acceptable at this coverage level but is not additive.

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 ('Drop a timeline marker at the current moment') and scopes it to an active EDL logging session, which clearly separates it from the state-management siblings atem_edl_start/stop/status. It stops short of an explicit statement about what 'current moment' means (wall clock vs. last edit point), but an agent can still tell what the tool does.

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

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

The phrase 'while EDL logging' plus the voice-trigger examples ('mark that', 'clip that for social') implies usage during a logging session, which is reasonable guidance. However, it never states that atem_edl_start must have been called first, nor what happens if the tool is invoked outside a session, and it doesn't route to any alternative tool.

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

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

Annotations only say it's a non-readonly, non-idempotent, non-destructive local operation. The description adds substantive context beyond that: it captures switches from any source (hardware panel, Software Control, Claude, auto-switch) and the .edl file is rewritten after every switch so the on-disk copy is always current. It doesn't say whether a second call restarts or conflicts with an existing session.

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 and behavior come first, then triggers, then parameters—a sensible front-loaded order with no filler prose. The Args block is long and partly re-states schema descriptions, which costs a little efficiency but carries defaults the schema omits.

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

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

With no output schema, the description does explain the artifact (filename derived from title, always-current .edl on disk), which is what an agent needs to confirm success. It omits the return payload and the already-running case, leaving minor gaps for a 7-parameter stateful logging 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 baseline is 3, but the description goes well beyond it: tc_source guidance ("use whichever matches the timecode recorded in the camera files"), the drop-frame default rule at 29.97/59.94, the actual output_dir default (~/Movies/ATEM EDLs), and a nested-object example for reel_names. These are decision-relevant details the schema truncates.

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

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

States a specific verb+resource (start logging program switches on an M/E bus to a CMX 3600 EDL for DaVinci Resolve), plus the exact artifact produced. It clearly separates itself from the EDL siblings (atem_edl_stop, atem_edl_status, atem_edl_marker) which handle stopping, querying, and marking.

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 trigger phrases ("start the EDL", "log this show", "start recording the cuts") that map user intent to this tool. It does not state when not to use it—e.g. what happens if logging is already active—nor does it point at atem_edl_stop as the companion call.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds useful detail about the returned status fields, but does not explain behavior when logging is not running or when the device is disconnected, so it adds only modest context beyond annotations.

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

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

A single front-loaded sentence lists the returned information with no wasted words. Every clause contributes to understanding what the status call provides.

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

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

For a simple, zero-parameter, read-only status tool with annotations and no output schema, the description is mostly complete because it names the returned fields. It could be slightly stronger by noting behavior when logging is inactive or the device is not connected, but no essential calling information is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. The baseline score of 4 applies for a no-parameter tool.

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

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

The description states a specific verb ('Show') and resource ('EDL logging'), enumerating exactly what status is returned: running state, timecode, switch/marker counts, and output file. It is clearly distinct in intent from siblings like atem_edl_start, atem_edl_stop, and atem_edl_marker, though it does not explicitly name those alternatives.

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

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

Usage is implied by the status-oriented wording: an agent can infer this is the read path for EDL logging while start/stop/marker are the mutation paths. However, there is no explicit when-to-use guidance, no mention of prerequisites such as an active connection, and no direct routing to alternative tools.

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

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

With annotations declaring readOnlyHint=false and destructiveHint=false, the description usefully adds that the file is finalized and that a markers EDL is produced only when markers were added, which explains conditional side effects. It also discloses the return payload (file paths for Resolve import). Minor gap: no note on behavior when stopping with no active session.

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

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

Two short clauses with zero waste: the action comes first, the conditional markers detail and the return value follow. Nothing to trim and nothing buried.

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

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

For a zero-parameter tool with no output schema, the description covers the action, the side effects, the conditional markers file, and what is returned (file paths). An agent has everything needed to call it correctly.

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

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

Zero parameters, so there is nothing for the description to disambiguate; baseline applies. The absence of a session-id or path argument is worth understanding, but that is a schema fact, not a description 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 ('Stop EDL logging'), plus the concrete outcome of finalizing the .edl file. This is clearly distinguished from atem_edl_start and atem_edl_marker by the 'stop/finalize' framing, though it does not name those siblings explicitly.

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

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

Usage is implied: call this to end an EDL logging session and produce an importable file. There is no explicit statement of prerequisites (e.g. that atem_edl_start must have been called) or what to do if no session is active, and no alternatives are named.

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

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

Annotations cover basic hints (non-readOnly, non-destructive, etc.), but the description adds valuable behavioral context: it's a toggle with state-dependent behavior (fades to black if live, fades back up if already in FTB). This goes beyond annotations by explaining the dual-state operation, though it doesn't mention rate limits or specific permission 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 description is well-structured with a clear purpose statement followed by parameter details. It's appropriately sized (two sentences plus Args), though the Args section could be integrated more seamlessly. Every sentence adds value without redundancy.

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

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

Given the tool's moderate complexity (stateful toggle), annotations provide safety hints, and schema fully covers the single parameter. The description explains the core behavior well, though it lacks output details (no output schema) and doesn't mention error cases or visual feedback. It's mostly complete for a toggle 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 description coverage is 100% with clear documentation of the 'me' parameter. The description's Args section repeats the schema info without adding extra meaning (e.g., why ME matters, typical use cases). Baseline 3 is appropriate since 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 description clearly states the specific action: 'Toggle Fade to Black (FTB)' with precise behavior: 'If currently live, fades to black. If already in FTB, fades back up.' It distinguishes from siblings like 'atem_cut' (instant transition) and 'atem_auto_transition' (auto fade) by specifying toggle behavior.

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

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

The description implies usage context through 'Toggle Fade to Black' and the conditional logic, but doesn't explicitly state when to use this vs. alternatives like 'atem_cut' or 'atem_auto_transition'. No explicit exclusions or prerequisites are provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: it transparently reads from Fairlight or the classic mixer depending on ATEM model, which an agent cannot infer from structured fields. Return shape is only summarized, not detailed, keeping it short of a 5.

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

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

Front-loaded with the core verb and resource, followed by scope and model-dependent behavior. The separate 'Returns:' sentence slightly restates the enumerated fields, but it usefully frames them as a JSON payload, so it earns most of 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 convey return values, and it does at a high level (mixer type, master settings, per-input state). For a zero-parameter read tool with full annotation coverage, this is nearly complete; only the shape of per-input state and master settings is left unspecified.

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

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

The tool takes no parameters, so the baseline is 4. The description instead spends its words on the return payload, which is the relevant semantic surface for a zero-arg getter.

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 ('Get the current audio mixer state') and enumerates what it covers: input levels, mix options, fader positions, master output. Clearly distinguishable from the sibling setters like atem_set_audio_mixer_input and atem_set_audio_master_output.

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

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

The read-only nature and the sibling set imply this is the inspection counterpart to the audio setters, and the Fairlight/classic note hints at when the result differs. However, there is no explicit statement like 'call this before adjusting levels' or any exclusion of alternatives, so usage remains inferred 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds the return payload (running state, monitored inputs, hold time, transition type, current speaker, switch count, runtime), which is genuinely useful since no output schema exists.

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

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

Two short sentences: the purpose first, then a compact enumerated return list. No filler, and the critical action is front-loaded.

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

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

With no output schema, the return-field enumeration does the work an agent needs to decide whether this tool answers its question. Only minor gap is the absence of any note on freshness/liveness of the stats or relation to atem_get_status.

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

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

Zero input parameters, so there is nothing for the description to disambiguate; baseline applies. The description correctly makes no parameter claims.

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: 'Check if auto-switch mode is currently running and get its configuration and stats.' This distinguishes it from general reads like atem_get_status, though it never names that sibling explicitly.

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

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

Usage is implied by the name and description — an agent knows this is the read counterpart to atem_auto_switch_on/off — but there is no explicit guidance on when to call it versus atem_get_status or whether polling is appropriate.

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

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

Annotations already indicate read-only, non-destructive, and idempotent behavior, so the description adds value by specifying the return format ('JSON object mapping each aux output to its current source input'). It does not disclose rate limits or auth needs, but with annotations covering safety, this is sufficient for good transparency.

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 two sentences, front-loaded with the purpose and followed by return details. Every sentence adds essential information without redundancy, making it highly efficient and well-structured.

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

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

Given the tool's simplicity (0 parameters, no output schema) and rich annotations, the description is mostly complete. It covers purpose and return format but could benefit from more explicit usage guidelines or error handling details, though not critical for this low-complexity tool.

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

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

The tool has 0 parameters with 100% schema description coverage, so no parameter documentation is needed. The description does not add param details, but this is appropriate given the lack of inputs, warranting a baseline score of 4 for adequate handling.

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

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

The description clearly states the verb 'Get' and the resource 'current source routing for all auxiliary outputs', specifying the exact scope. It distinguishes from siblings like 'atem_set_aux_source' by focusing on retrieval rather than modification, making the purpose specific and unambiguous.

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

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

The description implies usage for retrieving current routing information, which is clear in context. However, it does not explicitly state when to use this tool versus alternatives like 'atem_get_status' or 'atem_get_audio_state', nor does it mention prerequisites or exclusions, leaving some guidance gaps.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuine value beyond them by stating the return is human-readable in dB, Hz, and ms, which matters since there is no output schema. It does not mention connection prerequisites or error behavior.

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

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

Two sentences plus a one-line arg note; the purpose and return format are front-loaded with no filler. The args block lightly restates the required param but earns its place through the camera-to-number mapping.

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

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

A simple one-param read tool with no output schema; the description covers what is read, the units returned, and how to identify the input. Missing only the shape of the returned state (e.g., number of EQ bands) for full completeness.

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% with a single required integer, so the baseline is 3. The description exceeds that by decoding the parameter ('1=Camera 1, 2=Camera 2, etc.'), giving semantic meaning the bare schema text 'Audio input number' lacks.

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: 'Get the current EQ bands, compressor, limiter, and gate/expander settings' scoped to a Fairlight audio input. This clearly separates it from the set_* Fairlight siblings and from the broader atem_get_audio_state, so an agent can pick it without opening the schema.

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

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

Usage is implied by the read-only 'get current ...' framing (read before you set), but no explicit when-to-use or when-not guidance is given. It never names an alternative such as atem_get_audio_state for general mixer state, leaving routing to inference.

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

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

Annotations cover key behavioral traits (read-only, non-destructive, idempotent, closed-world), so the description's burden is lower. It adds value by specifying the scope ('recording and streaming status'), but does not disclose additional context like rate limits, error conditions, or what 'status' entails beyond the annotations.

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

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

The description is a single, efficient sentence that directly states the tool's purpose without any fluff. It is front-loaded and every word contributes to understanding, making it highly concise and well-structured.

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

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

Given the tool's simplicity (0 parameters, annotations provided, no output schema), the description is adequate but minimal. It lacks details on return values or error handling, which could be helpful for an agent, though annotations reduce the need for extensive explanation.

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?

With 0 parameters and 100% schema description coverage, the baseline is high. The description does not need to explain parameters, and it appropriately focuses on the tool's function without redundant details, earning a near-perfect score for clarity in a parameterless context.

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

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

The description clearly states the action ('Get') and the specific resource ('current recording and streaming status from the ATEM'), making the purpose evident. However, it does not explicitly differentiate from sibling tools like 'atem_get_status' or 'atem_get_audio_state', which might provide overlapping status information, so it falls short of a perfect 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?

The description provides no guidance on when to use this tool versus alternatives. With siblings like 'atem_get_status' and 'atem_start_recording', there is no indication of context, prerequisites, or exclusions, leaving the agent to infer usage based on tool names alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds valuable context by specifying what information is returned (model, firmware, inputs, connection state) and that it returns a JSON object, which isn't covered by annotations. No contradictions with annotations.

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

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

Two sentences that are front-loaded with the core purpose and follow with return details. Every sentence adds value: the first defines the scope, the second specifies the return format and content. No wasted words or redundancy.

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

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

For a read-only, idempotent tool with no parameters and no output schema, the description is mostly complete. It covers what the tool does and what it returns. However, it doesn't mention potential errors (e.g., if not connected) or usage context, leaving minor gaps given the tool's simplicity.

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 has 0 parameters with 100% schema description coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, focusing instead on the return value. Baseline for 0 parameters is 4, as it efficiently handles the lack of inputs.

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

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

The description clearly states the specific action ('Get current ATEM switcher status') and resource ('ATEM switcher'), listing the exact information returned. It distinguishes from siblings like 'atem_get_audio_state' or 'atem_get_transition_state' by specifying it provides overall status including model info, program/preview inputs, and connection state.

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

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

The description implies usage for retrieving current switcher status, but doesn't explicitly state when to use this tool versus alternatives like 'atem_get_audio_state' or 'atem_get_transition_state' for more specific status checks. No guidance on prerequisites (e.g., connection state) or exclusions is provided.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds something annotations cannot: it discloses the returned state composition (4 box states, art properties, border settings), which is valuable because no output schema exists. It stops short of noting freshness/caching behavior or error cases.

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

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

Front-loaded with the core statement, then Args and Returns in a compact structure. The Returns line partially restates the opening sentence, but it earns its place since there is no output schema.

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

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

For a single-optional-parameter read-only getter with no output schema, the description covers purpose, the parameter's default and typical cardinality, and the shape of the returned object. 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% and the schema already documents ssrcId with default 0 and range 0-3. The description adds only a small operational note ("Most ATEMs have only one Super Source"), which explains why the default is usually sufficient but gives no further format or selection guidance.

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

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

States a specific verb and resource ("Get the current Super Source state") and enumerates the contents: box positions/sources, art settings, border settings. That distinguishes it from the sibling setters (atem_set_supersource_box/layout/art/border), though it never names those siblings explicitly.

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

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

Usage is only implied: a 'get' tool whose setter counterparts exist elsewhere in the tool list suggests it is the read side of a read-modify-write flow. There is no explicit when-to-use statement, no mention of taking a snapshot before calling the set_* tools, and no exclusions.

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

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

Annotations already indicate read-only, non-destructive, and idempotent behavior, which the description aligns with by using 'Get'. The description adds valuable context beyond annotations by specifying the return format ('JSON with current transition style, rates per type, and whether a transition is currently in progress') and the default parameter value, enhancing transparency without contradiction.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by a structured 'Args' and 'Returns' section. Every sentence adds specific value without redundancy, making it efficient and well-organized for quick 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?

Given the tool's low complexity (one optional parameter), rich annotations covering safety, and no output schema, the description is largely complete. It explains what the tool does, the parameter, and the return format. A slight gap exists in not detailing potential error cases or system-specific constraints, but it suffices for basic use.

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

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

Schema description coverage is 100%, with the schema fully documenting the 'me' parameter. The description adds minimal value beyond the schema by mentioning the default value (0 for ME1) and implying the parameter's optionality, but does not provide additional semantic details. This meets the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose with specific verbs ('Get current transition settings') and resources ('for a Mix Effect bus'), including what information is retrieved ('style, rates, and in-transition status'). It distinguishes itself from siblings like atem_set_transition_style or atem_set_transition_rate by focusing on retrieval rather than modification.

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

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

The description implies usage when needing to check transition settings, but does not explicitly state when to use this tool versus alternatives like atem_get_status or other get_* tools. It provides clear context by specifying the target (Mix Effect bus) but lacks explicit exclusions or named 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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds useful return-content context — type, sources, on-air status, DVE position/size, key settings — though it says nothing about output shape limits or per-keyer ordering.

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

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

Front-loaded with the purpose and return fields in one sentence. The Args block largely duplicates the schema, but the overall length is appropriate and there is little wasted text.

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

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

For a single-optional-parameter read tool with no output schema, the description is nearly complete: annotations cover safety, and the field list compensates for the absent output schema. Only alternative-tool routing 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% and already documents me with default 0 and the 0=ME1 mapping. The description merely restates the parameter and default, adding no syntax or range detail beyond the schema (which has minimum 0, maximum 3).

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

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

States a specific verb (Get) and resource (upstream keyers on a mix effect bus) and enumerates the state fields returned. It is clearly distinguishable from the many atem_set_usk_* siblings that mutate the same resource.

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

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

Usage is implied by the read-only getter nature and the setters among siblings, but the description never says when to use this versus alternatives like atem_get_transition_state or atem_get_supersource_state, nor any exclusions.

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

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

Annotations already establish mutate-but-idempotent and non-destructive, and the description honors that by disclosing selection logic (Fairlight audio levels), the exact box mapping (2 top-right, 3 bottom-left, 4 bottom-right), and a documented fallback to the first 3 guests when audio data is missing. This is real added context. It omits what happens to any pre-existing Super Source layout or art on that ssrcId, which is the main remaining behavioral gap.

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

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

Behavior and selection rules are front-loaded in two tight paragraphs, then examples, so the important information arrives first. The 'Args:' block is largely redundant against a 100%-covered schema, which costs it a point, but the overall length stays proportionate to a tool with non-obvious selection semantics.

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

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

For a four-optional-parameter mutation with no output schema, the definition covers the combination logic, defaults, box ordering, and the no-audio fallback. What remains unclear is the effect on existing Super Source state for the chosen ssrcId and what the caller should expect back. Adequate, with a small but real gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: it identifies hostInput as the camera occupying the grid's host position, explains that guestInputs is a candidate pool from which the three most active are chosen, and maps audio rank to specific box numbers. The default guest list is written out explicitly, which is more usable than the schema's 'all inputs except host' phrasing.

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

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

The first sentence gives a concrete verb and composite outcome: builds a 2x2 grid from the host camera plus three guests, then cuts Super Source to program. That is enough for an agent to pick this over atem_set_supersource_layout or atem_cut_to_active_speaker. It stops short of a 5 because no sibling is named, so the agent must infer the difference from sibling names alone.

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

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

The two examples ('Go gallery', 'Go gallery with guests on 2, 3, 5') imply the intended invocation context, and the audio-priority plus fallback explanation tells the agent when the result will differ. There is still no explicit when-not-to-use guidance and no named alternative for cases where the caller wants layout without cutting to program. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context: the fields each look reports (name, description, creation date, active box count) and where the data lives on disk. It stops short of describing ordering or behavior on an empty 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?

Three short sentences, front-loaded with the action and scope, then return fields, then storage location. 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?

With zero parameters, full annotation coverage, and no output schema, the description carries the return-shape burden itself and does so by enumerating the reported fields. An agent has everything needed to call it and interpret results.

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

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

The tool takes no parameters, so the baseline is 4 and there is nothing further the description could clarify. The added note about the JSON storage path is a bonus rather than a parameter concern.

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

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

States a specific verb ("List") and resource ("saved Super Source looks"), which is clearly distinguishable from the save/load/delete siblings by verb alone. It doesn't explicitly name or route away from those siblings, 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?

There is no explicit when-to-use guidance or mention of atem_load_look / atem_delete_look as the natural follow-up actions. Usage is only implied by the nature of a list operation over saved looks.

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

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

Annotations already indicate read-only, non-destructive, and idempotent behavior, but the description adds valuable context by specifying the return format ('JSON array of macros with their index, name, and whether they are valid/used'). This clarifies what data is returned, which annotations do not cover. No contradiction with annotations exists.

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

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

The description is two sentences: the first states the purpose, and the second details the return format. Every sentence earns its place by providing essential information without redundancy, making it front-loaded and efficiently structured.

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

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

Given the tool's simplicity (0 parameters, no output schema), the description is complete. It covers the purpose, output details, and behavioral context, which is sufficient for an agent to understand and invoke this tool correctly without needing additional explanation.

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?

With 0 parameters and 100% schema description coverage, the baseline is 4. The description does not need to explain parameters, and it appropriately focuses on the tool's output instead, adding value beyond the empty input schema.

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

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

The description clearly states the verb ('List') and resource ('all defined macros on the ATEM switcher'), making the purpose specific and unambiguous. It distinguishes this tool from siblings like atem_macro_run, atem_macro_stop, and atem_macro_continue by focusing on listing rather than executing or controlling macros.

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

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

The description implies usage when needing to retrieve macro information, but does not explicitly state when to use this tool versus alternatives. It lacks guidance on prerequisites (e.g., whether the switcher must be connected) or exclusions, though the context of listing macros is clear from the purpose.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, closed-world, so the description is free to focus on semantics — and it does: it discloses what fields get overwritten, that source overrides only affect enabled boxes, and that cutToProgram pushes the result live. It does not cover failure behavior for an unknown look name, which is the main remaining gap.

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

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

Purpose and restore-scope are front-loaded, then usage value, then args and examples — a sensible order. The Args block partially restates schema descriptions verbatim (name, ssrcId, cutToProgram), which is mild duplication, but the examples earn their space.

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

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

For a 4-parameter, non-destructive, idempotent tool with full schema coverage and no output schema, the description gives enough to invoke correctly, including the override-only-enabled-boxes nuance. An agent would still be guessing about the response/confirmation and about behavior when the named look does not exist.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds genuine meaning beyond the schema: the box-1-to-4 ordering constraint, that only enabled boxes are affected by 'sources', and a worked example array plus the default for ssrcId and cutToProgram. Only the ssrcId range (0-3) is 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 specific verb and resource ('Load a previously saved Super Source look and apply it to the ATEM') and enumerates exactly what state is restored (box positions, sizes, crops, art, border). This clearly separates it from siblings like atem_save_look, atem_list_looks, and atem_set_supersource_layout.

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 primary use case (re-apply saved geometry) and the reuse pattern ('great for reusing the same layout geometry with different cameras/guests'), plus concrete trigger examples mapped to arguments. It stops short of explicitly naming the paired alternatives (atem_list_looks to discover names, atem_save_look to create them), so a 4 rather than a 5.

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

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

Annotations indicate this is a non-read-only, non-destructive, non-idempotent operation, which the description aligns with by implying a state change (continuing). However, the description adds minimal behavioral context beyond annotations—it doesn't specify effects like whether it resumes from a pause point or requires specific conditions, though with annotations covering safety, this is acceptable 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?

The description is a single, direct sentence with no wasted words, making it highly concise and front-loaded. Every word earns its place by clearly stating the action without redundancy.

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

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

Given the tool's complexity (a state-changing operation with no parameters) and lack of output schema, the description is minimally adequate. It states what the tool does but lacks details on behavior, prerequisites, or output, which could be helpful for an agent, though annotations provide some safety 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?

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description doesn't add param info, which is fine here, but it doesn't compensate for any gaps since there are none—baseline 4 is appropriate for zero parameters.

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

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

The description clearly states the verb ('Continue') and resource ('a paused macro'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'atem_macro_run' or 'atem_macro_stop', which would require more context about what distinguishes continuing from running or stopping a macro.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., that a macro must be paused first) or compare it to siblings like 'atem_macro_run' or 'atem_macro_stop', leaving the agent to infer usage from context alone.

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

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

Annotations indicate this is a non-read-only, non-destructive, non-idempotent, closed-world operation. The description adds that it runs a macro by index, implying it triggers an action sequence, which aligns with annotations. However, it doesn't disclose additional behavioral traits like potential side effects, execution time, or error conditions beyond what annotations provide.

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

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

The description is brief and front-loaded with the core purpose, followed by parameter details. It avoids unnecessary words, though the parameter explanation could be integrated more seamlessly rather than as a separate 'Args' section.

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

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

Given the tool's moderate complexity (executing a macro), lack of output schema, and rich annotations, the description is minimally adequate. It covers what the tool does but lacks details on return values, error handling, or interaction with other tools like 'atem_list_macros', leaving gaps for an agent to infer usage.

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

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

Schema description coverage is 100%, with the schema fully documenting the 'index' parameter's type, range, and 0-based nature. The description repeats this information without adding meaningful context like macro slot mapping or execution consequences, so it meets the baseline for high schema coverage.

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

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

The description clearly states the action ('Run') and resource ('ATEM macro'), specifying it's executed by index number. It distinguishes from siblings like 'atem_macro_continue' and 'atem_macro_stop' by focusing on initiation, but doesn't explicitly differentiate from other macro-related tools beyond the name.

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

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

No guidance is provided on when to use this tool versus alternatives like 'atem_macro_continue' or 'atem_macro_stop', nor does it mention prerequisites such as needing a connected ATEM device or macro availability. The description only states what it does, not when to use it.

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

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

The description adds valuable context beyond annotations: it specifies that the tool stops a 'currently running' macro, which implies it only works when a macro is active. Annotations already indicate it's non-destructive, idempotent, and not read-only, but the description provides operational context that enhances understanding of when the tool is applicable.

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

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

The description is a single, efficient sentence that front-loads the essential information ('Stop the currently running macro'). There is no wasted language, and it directly addresses the tool's purpose without unnecessary elaboration.

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, parameterless tool with annotations covering safety (non-destructive, idempotent) and no output schema, the description is complete enough. It specifies the action and context ('currently running'), though it could slightly enhance completeness by mentioning what happens after stopping (e.g., if the macro can be resumed).

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?

With 0 parameters and 100% schema description coverage, the baseline is 4. The description reinforces that no parameters are needed by focusing on the action ('Stop the currently running macro') without mentioning any inputs, which is appropriate and adds clarity for a parameterless tool.

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

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

The description clearly states the specific action ('Stop') and target resource ('the currently running macro'), distinguishing it from siblings like atem_macro_continue and atem_macro_run. It uses precise language that directly conveys the tool's function 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?

The description explicitly indicates when to use this tool: 'Stop the currently running macro.' This implies it should be used only when a macro is actively running, distinguishing it from alternatives like atem_macro_run (to start) or atem_macro_continue (to resume). The context is clear and specific.

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

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

Annotations indicate this is a non-read-only, non-idempotent, non-destructive operation, which the description aligns with by describing a state-changing action. However, the description adds minimal behavioral context beyond annotations—it doesn't mention potential side effects, timing considerations, or error conditions. With annotations covering basic safety, a 3 is appropriate as the description adds some value but not rich behavioral details.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by a clear analogy. The parameter section is brief and directly relevant. Every sentence earns its place with no wasted words, making it easy to scan and understand quickly.

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

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

For a tool with two parameters, 100% schema coverage, and annotations covering basic behavioral hints, the description is reasonably complete. It explains the combined action and when to use it. However, without an output schema, it doesn't describe return values or potential errors, leaving a minor gap in full 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 description coverage is 100%, with both parameters ('input' and 'me') fully documented in the schema. The description repeats the parameter definitions verbatim from the schema without adding extra meaning or context. Baseline 3 is correct when the schema does the heavy lifting, though the description adds no additional semantic 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 description clearly states the specific action: 'sets a preview input then immediately triggers an auto transition to bring it on air.' It distinguishes from siblings like 'atem_set_preview' (only sets preview) and 'atem_auto_transition' (only triggers auto transition) by combining both operations. The analogy 'Equivalent to selecting a source and pressing AUTO' reinforces the purpose.

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

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

The description explicitly positions this as a 'Convenience tool' and names the equivalent manual action ('selecting a source and pressing AUTO'). This provides clear context for when to use it: when you want to both set preview and trigger an auto transition in one step, avoiding separate calls to sibling tools like 'atem_set_preview' and 'atem_auto_transition'.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description usefully adds that the reset lands on factory defaults (i.e. custom settings are lost and the operation is repeatable), but says nothing about permissions, whether the change is applied live on air, or the response shape. There is mild tension with destructiveHint=false, since user-configured dynamics are discarded, but not an outright contradiction.

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

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

The operative sentence is front-loaded and the Args block is scannable. The parameter list largely mirrors the schema, so it is slightly redundant, but it is short and each line remains readable.

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

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

For a 5-parameter mutation tool with no output schema, the description covers what is reset and to what values, but leaves an important behavior undefined: whether omitting all optional flags performs a full reset or a no-op. That ambiguity is what an agent most needs resolved before calling.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns a notch more by annotating the input number with a concrete mapping (1=Camera 1, 2=Camera 2, etc.) and clarifying that 'expander' covers gate/expander, details the schema does not carry.

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: reset dynamics processors to factory defaults on a Fairlight audio input, and enumerates the three processors covered. This separates it in spirit from atem_set_fairlight_compressor/limiter/gate (set vs. reset) and atem_reset_fairlight_eq, though it never names those siblings explicitly, leaving the agent to infer the distinction from tool names.

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 optional flags imply a partial-vs-full reset pattern, but the description never says when to use this instead of the individual set_* Fairlight tools, nor what happens when all flags are omitted. Guidance is implied rather than stated.

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

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

The annotations already declare that this is a non-read-only, idempotent, non-destructive operation. The description adds useful behavioral detail by specifying that it resets to factory defaults and that omitting band resets all bands.

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

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

The description is short, front-loaded with the action and target, and uses an Args list only for the details an agent needs. Every sentence and parameter note is directly relevant.

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 two-parameter mutation tool with full schema coverage and annotations, the description is mostly complete. The remaining gap is that it does not explain when to choose this reset over the related set/preset EQ tools or note connection prerequisites.

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 meaning beyond the schema by mapping input numbers to cameras (1=Camera 1, etc.). It also reinforces the band range and the omit-for-all behavior.

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: reset the EQ to factory defaults on a Fairlight audio input. This clearly distinguishes it from sibling tools such as atem_set_fairlight_eq and atem_set_fairlight_eq_preset.

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 first sentence implies the tool is for resetting EQ rather than setting EQ values, but it does not explicitly compare it with alternatives like atem_set_fairlight_eq or atem_set_fairlight_eq_preset. It also does not mention prerequisites such as needing an active connection.

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

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

Annotations already declare a non-destructive, idempotent, non-read-only write, and the description adds genuinely new context: the file location (~/.atem-mcp/looks/), JSON format, and persistence across server restarts. The notable gap is overwrite semantics — with idempotentHint=true, an agent needs to know whether reusing an existing name silently replaces a saved look, and the description never says so.

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

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

Front-loaded with the core action, then persistence/location facts, then args and examples. The Args section largely mirrors the schema, but each entry carries extra detail (filename rules, naming examples) and the whole block is short with no filler.

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

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

For a no-output-schema write tool the description covers what state is captured, where it lands, and that it survives restarts. It is short of complete only on the overwrite/collision behavior and on what the agent gets back on success, both of which matter for confirming the save went through.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes beyond it by spelling out filename character constraints (alphanumeric, dashes, underscores) and giving realistic name/description examples that convey naming conventions and intended granularity. ssrcId is only restated from the schema, so the value added is uneven but real.

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: snapshot the current Super Source state (box positions/sources, art, border) and persist it as a named look. That is clearly distinct from the sibling persistence tools (atem_list_looks, atem_load_look, atem_delete_look) and from the atem_set_supersource_* mutators, so an agent can select it without opening the schema.

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

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

Provides concrete invocation examples ("Save this look as podcast4") and implies the workflow via the phrase "can be recalled later," which points at atem_load_look. It does not explicitly name the alternatives or state the when-not case (e.g., when to prefer configuring boxes live via atem_set_supersource_box instead), so it is clear context rather than full routing guidance.

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

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

Annotations already declare idempotent=true, destructiveHint=false and closed-world, so the safety profile is covered. The description adds genuinely useful context that the tool works across both Fairlight and classic mixer modes. It does not say what happens when both optional args are omitted (no-op vs. query) or whether the change takes effect immediately.

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 purpose with the key compatibility detail up front, followed by a compact Args list. The Args section duplicates the schema descriptions, which is mild waste but keeps the definition readable.

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 two-optional-parameter setter with full annotations and full schema coverage, little is required, and no output schema means return values need no explanation. However, the all-optional nature of the call leaves the no-argument behavior undefined, which is the one gap an agent would actually hit.

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

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

Schema coverage is 100% and both parameters are already documented with units and ranges, so the description's Args block mostly restates structured data. It adds the explicit -100 to +10 range and 'fader' terminology, but no guidance on partial updates or interaction between gain and followFadeToBlack.

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 ('Configure the master audio output level'), which distinguishes it from the sibling atem_set_audio_mixer_input and the Fairlight master EQ/dynamics tools. The added note about Fairlight and classic mixers reinforces scope but the description never explicitly contrasts the input-level sibling.

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

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

Usage is implied by the name and the 'works with both' compat note, but there is no explicit when-to-use guidance, no prerequisites, and no named alternative for per-input level changes (atem_set_audio_mixer_input). An agent must infer the boundary itself.

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

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

Annotations already declare non-readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the tool silently switches between two different mixer backends depending on hardware model, and faderGain is ignored on classic mixers. It does not say whether this requires an active connection or what happens on unsupported models, keeping it below 5.

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

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

Front-loaded with a one-line purpose plus the hardware-model caveat, then a compact parameter list. The Args block restates ranges already in the schema, which is mild redundancy, but each entry carries added semantics so nothing is pure waste.

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

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

No output schema exists, and the description covers the things an agent actually needs: required input, the three mixOption states with their on-air meaning, the gain/fader split, and the hardware-dependent backend. Remaining unknowns (connection prerequisite, error behavior) are minor for a setter of this scope.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description genuinely adds meaning: 'afv' is expanded into its on-air consequence ('audio is live only when this input is on program'), and gain is framed as the pre-fader knob versus faderGain as the main channel fader — a distinction the schema's enum and range alone do not convey.

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

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

States a specific verb and resource ('Configure an audio input on the ATEM') and immediately clarifies it operates per-input rather than on the master bus, which is the key axis of confusion against atem_set_audio_master_output. It never names a sibling explicitly, so it stops short of full differentiation.

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

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

The model-dependent routing note (Fairlight on Mini Extreme/Constellation vs classic mixer on Mini/Mini Pro) is useful operational context, but there is no explicit when-to-use or when-not guidance and no pointer to atem_get_audio_state for reading current values before writing. Usage is implied rather than stated.

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

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

The description adds valuable context beyond annotations: it explains the 0-based indexing convention for aux outputs, which is crucial for correct usage. Annotations already indicate this is a non-destructive, idempotent write operation, but the description reinforces the routing behavior without contradiction. No rate limits or auth needs are mentioned, but the annotations cover the essential safety profile.

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

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

The description is perfectly structured: a clear purpose statement first, followed by parameter explanations with important implementation details (0-based indexing), then practical usage examples. Every sentence earns its place with no wasted words, and the information is front-loaded appropriately.

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

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

For a 2-parameter routing tool with good annotations and full schema coverage, the description provides excellent context about what the tool does and when to use it. The only minor gap is the lack of output information (no output schema exists), but for a simple routing operation, the description is nearly complete. The practical examples compensate well for the missing output details.

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

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

With 100% schema description coverage, the schema already fully documents both parameters. The description repeats the aux parameter's 0-based indexing but adds no additional semantic meaning beyond what's in the schema. The baseline of 3 is appropriate when the schema does all the parameter documentation work.

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

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

The description clearly states the specific action ('Route an input source to an auxiliary output') and resource ('auxiliary output'), distinguishing it from siblings like atem_set_preview or atem_set_program which route to different outputs. It uses precise technical language appropriate for the domain.

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

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

The description provides clear context for when to use this tool ('Common uses: sending a clean feed to a recorder, routing a specific camera to a confidence monitor'), giving practical examples. However, it doesn't explicitly state when NOT to use it or mention specific alternatives among the sibling tools (e.g., atem_set_preview for preview bus routing).

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

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

Annotations indicate this is a non-destructive, idempotent mutation tool (readOnlyHint: false, destructiveHint: false, idempotentHint: true). The description adds valuable context by explaining that DSKs 'overlay graphics (logos, lower thirds, etc.) on top of the program output,' which clarifies the tool's effect beyond the annotations. However, it does not mention rate limits, authentication needs, 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?

The description is front-loaded with the core purpose in the first sentence, followed by a brief explanation of DSKs, and then a clear Args section. Every sentence earns its place without redundancy, making it efficient and well-structured for quick understanding.

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

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

Given the tool's moderate complexity (2 parameters, mutation operation) and rich annotations (covering idempotency, destructiveness, etc.), the description is mostly complete. It explains what DSKs do and how to use the tool, but lacks output details (no output schema) and does not address potential side effects or error handling, which could be useful for an agent.

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

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

Schema description coverage is 100%, with both parameters (dsk and onAir) fully documented in the schema. The description repeats this information in the Args section but adds no additional semantic context beyond what the schema provides, such as examples of when to toggle onAir or implications of dsk values. This meets the baseline for high schema coverage.

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

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

The description clearly states the specific action ('Put a downstream keyer on or off air') and resource ('DSKs overlay graphics on top of the program output'), distinguishing it from siblings like atem_set_dsk_sources (which sets sources) and atem_set_usk_on_air (which handles upstream keyers). It provides precise context about what DSKs are used for.

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

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

The description implies usage for controlling DSK on/off states but does not explicitly state when to use this tool versus alternatives like atem_auto_dsk (which may automate DSK operations) or atem_set_dsk_sources (which configures DSK content). No explicit exclusions or prerequisites are mentioned, leaving usage context inferred rather than clearly defined.

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

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

Annotations indicate this is a non-destructive, idempotent write operation. The description adds context by specifying it sets sources for a 'downstream keyer', which clarifies the tool's domain. However, it doesn't mention rate limits, authentication needs, or side effects beyond what annotations cover, missing some behavioral details.

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

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

The description is front-loaded with the core purpose in one clear sentence, followed by a structured parameter list. However, the parameter section duplicates schema information without adding value, slightly reducing efficiency. Overall, it's well-organized but could be more concise by omitting redundant details.

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

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

Given the tool's moderate complexity (3 parameters, no output schema), annotations cover safety and idempotency well. The description provides adequate purpose and parameter overview, but lacks details on error conditions, return values, or integration with sibling tools, leaving some gaps for full agent understanding.

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

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

Schema description coverage is 100%, with all parameters documented in the schema. The description repeats the schema's parameter explanations verbatim ('fillSource (number, optional): Input to use as fill source'), adding no additional meaning or usage context beyond what's already structured.

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

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

The description clearly states the specific action ('Set') and target resources ('fill and/or key sources for a downstream keyer'). It distinguishes from siblings like 'atem_set_dsk_on_air' (which controls on-air state) and 'atem_set_usk_sources' (which is for upstream keyers), providing precise differentiation.

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

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

The description implies usage for configuring downstream keyer sources, but offers no explicit guidance on when to use this vs. alternatives like 'atem_set_usk_sources' or 'atem_set_dsk_on_air'. It lacks context about prerequisites or exclusions, leaving the agent to infer from tool names alone.

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

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

Annotations already declare write, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds unit ranges and an input-to-camera mapping, but for a setter with six optional parameters it does not say whether omitted parameters preserve existing values or reset to defaults — the key behavioral ambiguity here.

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 sentence is front-loaded and one line long, and the arg list is scannable. It is slightly redundant against the schema (ranges and units are duplicated), which costs a point but not readability.

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

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

Mislabeled placeholder — ignore. Actual justification: for a 7-parameter closed-world setter with full schema coverage, annotations, and no output schema, the definition covers purpose, units, and bounds adequately. The remaining gap (partial-update semantics) is minor and does not block correct invocation.

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

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

With 100% schema coverage the baseline is 3, and the schema already enforces min/max bounds that the description repeats. The one genuine addition is the input mapping ('1=Camera 1, 2=Camera 2'), plus the ratio example, which is useful but marginal.

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 ('Configure the compressor on a Fairlight audio input'), and the phrase 'on a Fairlight audio input' implicitly separates it from atem_set_fairlight_master_compressor and the limiter/gate siblings. It never names those siblings explicitly, so differentiation is inferable 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?

There is no explicit when-to-use or when-not-to-use guidance, no mention of prerequisites (e.g. connecting via atem_connect first), and no routing to alternatives like atem_reset_fairlight_dynamics or the master compressor. Usage is only implied by the tool name and the compressor terminology.

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

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

Annotations already declare this is a non-destructive, idempotent, closed-world mutation. The description adds meaningful device-specific behavior: the 6-band layout, default filter types/frequencies, and which bands start disabled. It could go further by noting that changes affect live audio, but it substantially supplements the annotations.

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

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

The description is front-loaded and the band layout is valuable, but the Args section largely repeats schema content that is already fully documented. It is appropriately sized overall but not maximally concise.

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 8 parameters, no output schema, and annotations covering safety/idempotency, the description provides enough context to invoke the tool correctly. It omits explicit sibling routing and live-audio impact notes, but those are secondary gaps.

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

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

Schema description coverage is already 100%, so the baseline is 3. The description adds useful meaning beyond the schema with the default band layout and per-band defaults, though many parameter descriptions (ranges, enum values, input mapping) duplicate what the schema already 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 states a specific verb and resource: setting an EQ band on a Fairlight audio input, with the band range (0-5). It implicitly distinguishes itself from master EQ and preset siblings via 'audio input' and 'band,' but it never names those alternatives explicitly.

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

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

Usage is implied by the tool name and the mention of 6 bands per channel, but there is no explicit guidance on when to use this versus atem_set_fairlight_eq_preset, atem_set_fairlight_master_eq, atem_get_fairlight_eq_state, or atem_reset_fairlight_eq.

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

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

Annotations already declare non-readonly, idempotent, non-destructive, closed-world, so the safety bar is pre-met. The description adds real behavioral context beyond that: all six bands are overwritten in a single atomic operation, and 'flat' returns bands to 0 dB factory defaults, which tells the agent existing per-band settings will be replaced.

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 a scannable preset list, then args. Every line carries usable information (preset semantics are the core value), though the frequency detail for 'vocal' is richer than strictly needed to select 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?

For a two-parameter setter with no output schema and full annotation coverage, the description supplies everything an agent needs: what changes, that all six bands are affected, what each preset targets, and how input indices map. No material gap remains.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: it explains what each enum value does acoustically (HP 80Hz, mud cut 400Hz, etc.) and clarifies that 'input' maps to camera numbering (1=Camera 1). That goes materially beyond the bare enum and 'Audio input number' 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?

Opens with a specific verb+resource ('Apply a predefined EQ preset to a Fairlight audio input') and adds the key scope fact ('Sets all 6 bands at once'), which separates it from the manual per-band sibling. It does not name atem_set_fairlight_eq or atem_reset_fairlight_eq explicitly, so differentiation is implied 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?

The preset catalogue lets an agent infer intent ('flat' resets, 'de_mud' fixes muddy audio), but there is no explicit guidance on when to choose this versus atem_set_fairlight_eq for manual band control or atem_reset_fairlight_eq for a reset. Usage is implied, not prescribed.

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

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

Annotations already cover the safety profile (idempotent, non-destructive, closed-world), so the description's job is to add domain behavior — which it does, explaining that sub-threshold audio is cut or reduced by range/ratio and that gateEnabled switches modes. It stops short of saying what happens on invalid mode/parameter combinations or whether changes take effect live.

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

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

Front-loaded purpose sentence followed by an efficient per-argument list; every line earns its place. Minor redundancy with the schema on units and bounds keeps it from a 5.

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

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

For a 9-parameter mutation tool with no output schema, the description covers the mode semantics and every parameter's meaning and units, which is enough to call it correctly. It lacks any note on side effects relative to other Fairlight dynamics settings or error conditions, a small remaining gap.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns a bump by adding meaning the terse schema lacks — input numbering maps to camera numbers, threshold signposts 'audio below this is reduced', and range is framed as how much reduction occurs. It adds real semantic value beyond 'Threshold in dB' / 'Range in dB'.

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 ('Configure the noise gate or expander on a Fairlight audio input') and immediately defines what gates and expanders do. This distinguishes it cleanly from the sibling dynamics tools (atem_set_fairlight_compressor, atem_set_fairlight_limiter, atem_set_fairlight_eq) which act on different processors for the same input.

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 gate-vs-expander semantics (

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

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

Annotations already declare this is a non-readonly, idempotent, non-destructive, closed-world mutation, and the description does not contradict that. The description adds useful domain context (what a limiter does) and parameter ranges, but does not say whether omitted optional params are left untouched or reset, nor how the change is confirmed.

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 purpose sentences followed by a compact arg list — front-loaded and easy to scan, with no filler prose. Minor redundancy in restating the min/max values the schema already enforces.

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 6-parameter mutation with full annotation coverage and no output schema, the description covers purpose, scope, units, and valid ranges, which is sufficient to call it correctly. The remaining gap is behavioral — no statement about partial-update semantics or how to verify the resulting limiter state.

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 carries baselines and bounds; the description adds meaning beyond it by mapping 'input' to concrete camera numbers (1=Camera 1, 2=Camera 2) and by labeling units and optionality explicitly. It repeats the schema's ranges but in a single scannable block.

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 ('Configure the limiter on a Fairlight audio input') and scopes it to a single input, which distinguishes it from the sibling 'atem_set_fairlight_master_limiter' without naming it explicitly. A short functional gloss ('prevents audio from exceeding the threshold') reinforces intent.

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

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

No guidance on when to use this versus the master limiter, the EQ/compressor/gate siblings, or 'atem_reset_fairlight_dynamics'. Nothing states prerequisites (e.g., that the input exists or that Fairlight processing must be enabled) or what happens when optional parameters are omitted.

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

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

Annotations already declare the write is non-destructive, idempotent, and mutation-only, so the safety profile is covered. The description adds domain context about what the parameter physically does, but says nothing about whether the change is audible immediately on air or requires the input to exist/be selected.

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

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

Two tight sentences front-load purpose and the concept definition, followed by a short args block. The args block largely duplicates the schema, so it is slightly redundant, but it is short and the input mapping carries information the schema lacks.

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 only two required scalar parameters, full schema coverage, and no output schema to explain, the description gives everything an agent needs to call it correctly: the operation, the units, the value range, and the input numbering convention.

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 would be 3, but the description adds real meaning beyond the schema by mapping input numbers to cameras ('1=Camera 1, 2=Camera 2, etc.') and restating the 0-20 dB valid range for gain. The integer type for input is only clarified verbally, which is a small plus.

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

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

States a specific verb (Set) and a narrow resource (makeup gain on a Fairlight audio input), and the second sentence defines what makeup gain is functionally. It is clearly distinct from sibling dynamics tools such as atem_set_fairlight_compressor or atem_set_fairlight_limiter, though it does not name them explicitly.

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

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

The explanation that makeup gain 'compensates for volume lost during compression' implies it is used in conjunction with compressor settings, but there is no explicit when-to-use, ordering, or prerequisite guidance (e.g. whether the input must be a Fairlight input, or whether it should be set after compression).

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

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

Annotations already declare non-destructive, idempotent, non-open-world behavior, so the safety profile is covered. However, the critical behavioral question for an all-optional setter — whether omitted parameters retain their current values or are reset to defaults — is never addressed, and nothing is said about whether this affects audio in real time or requires a specific connection 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 one-line purpose is front-loaded and clear, but the six-line Args block is pure duplication of the input schema and earns no place. Half the description is redundant payload.

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, zero-required-parameter mutation with no output schema, an agent needs merge semantics, defaults, and any prerequisites (e.g., Fairlight audio enabled, connection required). None of that is present, and the annotations only cover the safety profile, leaving the definition materially incomplete for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including ranges; the description's Args block simply restates those same names, units, and bounds verbatim. It adds no semantics beyond the schema (the schema's ratio description is actually richer, giving the 4:1 example), 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 ('Configure the compressor on the Fairlight master output'), and the 'master output' scope implicitly separates it from the per-input atem_set_fairlight_compressor sibling. It stops short of naming that sibling explicitly, so the differentiation is inferable 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?

There is no when-to-use or when-not-to-use guidance, and no mention of the closely related atem_set_fairlight_compressor, atem_reset_fairlight_dynamics, or atem_get_audio_state tools. An agent must guess whether to reach for this or the per-input compressor variant.

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

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

Annotations already declare idempotency, non-destructiveness, and a closed world, so the description needed to add context such as whether omitted optional params leave existing band values untouched, whether a connection is required, or how partial updates are handled. It adds none of that – the body is a restatement of the schema parameter ranges. It does not contradict the annotations (setting EQ values is a non-destructive mutation), but it contributes almost no behavioral disclosure.

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

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

The two opening sentences are well front-loaded and earn their place, but the seven-line Args block repeats parameter names, types, ranges, and enum values that the 100%-covered schema already provides. Roughly half the text is redundant with structured fields.

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 output schema, the definition covers what changes (a master EQ band) but omits whether the call requires a live connection, how partial updates interact with existing band state, and what the result reports. Annotations cover the safety profile, so the remaining gaps are moderate rather than fatal.

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

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

Schema description coverage is 100% and both enums are documented in the schema, so the schema already carries the parameter semantics; the baseline of 3 applies. The description's args block largely duplicates the schema, with the only marginal addition being the '6-band layout' note tying band index 0-5 to an EQ band structure.

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

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

The first sentence states a specific verb and resource ('Set an EQ band on the Fairlight master output'), and the follow-up 'Same 6-band layout as input EQ' implicitly separates it from the sibling atem_set_fairlight_eq that touches input channels. The master-vs-input distinction is real but conveyed indirectly through a reference rather than by naming the sibling 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?

There is no explicit when-to-use guidance, no conditions that route the agent to atem_set_fairlight_eq (input), atem_set_fairlight_eq_preset, or atem_reset_fairlight_eq, and no prerequisite such as requiring an active connection. The agent must infer the usage context from the tool name and the passing mention of input EQ.

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

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

Annotations already declare openWorld=false, idempotent=true, destructive=false, so the safety profile is covered. The description adds essentially nothing beyond that — critically, it does not say whether omitted optional parameters are left unchanged or reset, which is the main behavioral ambiguity for a five-optional-arg setter. It also does not state whether the change is audible immediately or requires an explicit apply.

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

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

The one-sentence purpose line is well front-loaded, but the entire Args block is verbatim duplication of schema content that the agent already receives. The description would be stronger spending those tokens on behavior (partial update semantics, defaults) instead.

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-optional-parameter mutation with no output schema, the definition covers what is changed and the valid ranges. It leaves out the two things an agent would still need: whether calling with a subset of args is a partial update or a full replace, and how to confirm the resulting limiter state.

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

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

Schema description coverage is 100%, and every parameter already carries its unit and numeric bounds in the schema. The description's Args block restates the identical names, units, and ranges without adding meaning such as typical/default values or interaction between attack/hold/release. Baseline 3 applies because the schema does all the work.

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 (configure) and a precisely scoped resource (the limiter on the Fairlight master output). The 'master output' qualifier distinguishes it from the per-input atem_set_fairlight_limiter sibling, though the description never names that sibling to make the distinction explicit.

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

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

There is no statement of when to reach for this tool versus atem_set_fairlight_master_compressor, atem_set_fairlight_limiter (per-input), or atem_reset_fairlight_dynamics. The only guidance is inferable from the tool name and the 'master output' phrase; nothing tells the agent about prerequisites or exclusions.

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

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

Annotations indicate this is a non-destructive, idempotent write operation (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds value by specifying that it sets the 'preview (next) input,' clarifying it affects the preview bus rather than the program output, and references 'atem_set_program' for input ID consistency. It doesn't contradict annotations and provides useful context beyond them, though it could mention side effects like visual feedback on the switcher.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by a brief, structured 'Args' section. Every sentence earns its place by clarifying parameters without redundancy. It's appropriately sized for a simple tool, with zero waste, making it highly efficient and easy to scan.

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

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

Given the tool's moderate complexity (a write operation with two parameters), annotations cover safety and idempotency, and the schema fully describes inputs. The description adds context about the preview bus and input ID consistency. However, without an output schema, it doesn't explain return values (e.g., success confirmation or error details), leaving a minor gap. Overall, it's mostly complete but could benefit from output information.

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