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

The annotations already declare destructiveHint=true and openWorldHint=true. The description adds valuable detail: it creates virtual devices, moves the pointer, and captures output—concrete side effects beyond the annotation. It also explains why these behaviors are unpredictable ('depends on how libinput classified the virtual device'), which aligns with openWorldHint. This goes beyond what annotations alone convey.

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

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

The description is concise and well-structured. It opens with the core purpose, immediately explains what the tool does, then provides the rationale and usage timing. Every sentence earns its place—no fluff or repetition. It is front-loaded with the most critical information and stays focused.

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

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

The description covers the tool's purpose, mechanism, side effects, and when to run it. It also acknowledges an output summary (absolute vs relative fallback). However, it omits any explanation of the dry_run parameter, which is a key input that affects behavior. Given the presence of an output schema, return format doesn't need detailing, but the parameter gap leaves the description incomplete.

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 only parameter, dry_run, is entirely undocumented in the description. The schema gives its name, type, default, and requirement status but provides no semantic meaning. The description mentions 'non-dry-run' indirectly but never explains what dry_run does, when to set it to true, or what the difference is. With 0% schema description coverage, this is a significant gap—the description fails to compensate.

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 specific purpose: to verify that input injection reaches the compositor. It describes the concrete steps (creating virtual devices, moving pointer to three points, capturing) and the distinctive outcome (determining whether absolute positioning or relative fallback is needed). This distinguishes it from the many sibling tools, even without naming them.

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

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

The description gives a clear usage context: 'Run this once per machine before trusting a real (non-dry-run) Playbook.' It explains that this is a one-time calibration step and that the result cannot be known without trying, which implies this is the tool to use for that purpose. It doesn't explicitly mention alternatives or when not to use it, but the guidance is strong.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's job is to add behavioral context. It does so by specifying 'return it to you directly' and explicitly noting it does not use the local vision model—information not in annotations. No contradictions exist.

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 tightly written: a clear one-sentence purpose, a brief usage block, and a one-line parameter definition. No fluff or redundancy. The key purpose is front-loaded, and every sentence contributes value.

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

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

For a simple screenshot tool, the description covers usage, region format, and direct return. However, the `max_width` parameter remains unexplained; an agent might not know how to set it or its effect on output. Given that the tool has no output schema, a bit more detail on max_width would make it fully complete.

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

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

The description explains the `region` parameter fully: it is [x, y, width, height] in desktop pixels and can be omitted for the whole desktop. However, `max_width` is not described at all; the schema only shows it is an integer with default 1280. Since schema description coverage is 0%, the description should compensate for both parameters, but it only covers one.

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 'Take a screenshot and return it to you directly' uses a specific verb and resource, and clearly states the result. It also distinguishes itself from the vision-model-based sibling by saying 'This does not involve the local vision model,' which makes its purpose 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?

It provides concrete use cases: 'before writing a Playbook, to pick coordinates for probes and click regions, or to work out why a run went wrong.' This tells the agent exactly when to invoke it. It does not explicitly mention alternatives or when not to use it, but the context is clear enough to guide selection.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description doesn't need to restate safety. It adds valuable behavioral detail: it computes implicit journal information, returns specific edits ordered blocker-first, and distinguishes between a burst that never ran vs. ran but did nothing. This goes well beyond the annotation, providing non-obvious nuances.

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 a crisp summary, then explains the key distinction and ends with an actionable workflow. Every sentence earns its place; there is no fluff or redundancy. Structure is clear and scannable.

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

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

Given that an output schema exists (the description doesn't need to detail return structure) and annotations cover safety, the description covers the essential context: the diagnostic purpose, the key distinction between two root causes, and the iterative workflow. The only minor gap is the run_id parameter semantics, which slightly detracts from completeness for an otherwise simple 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 0%, so the description carries the full burden for the single parameter run_id. It never mentions run_id, its format, how to obtain it, or whether it's required (though the schema marks it optional). The name 'run_id' is self-explanatory by convention, but the description provides no explicit guidance, and with only one parameter to cover, this is a noticeable 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?

The description opens with a specific verb and resource: 'Explain why a run behaved as it did, and what to change.' It then contrasts itself with reading the journal, making its purpose distinct from voltage_journal. No ambiguity about what the tool does.

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

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

It explicitly instructs to call this instead of reading the journal by hand, giving clear when-to-use context. It also provides a workflow (apply highest-severity finding, re-run, diagnose again). However, it doesn't name alternative siblings like voltage_doctor or voltage_observe, or describe conditions where those might be more appropriate, so it stops short of complete 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?

The annotations already declare readOnlyHint=true and openWorldHint=false, establishing a safe, closed-world read operation. The description adds valuable context beyond safety: it lists the specific components checked (session type, input-device permissions, capture backends, screen geometry, GPU memory vs model profile, both model backends) and states that it returns fix commands. This informs the agent about the scope of the check and the nature of the response, which is more than annotations provide. No contradiction found.

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 three sentences, tightly packed with information. The first sentence gives the core purpose, the second enumerates the checks and the fix-command behavior, and the third provides usage timing. Every sentence earns its place, and the most important information (purpose and when to use) is front-loaded. There is no fluff 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 no-argument diagnostic tool, the description is comprehensive. It clearly states what is checked, the response characteristic (returns fix commands), and when to call it. An output schema exists (though not shown), so the description doesn't need to detail return formats. Given the complexity of the checks and the existence of a schema, nothing essential is missing for the agent to use the tool correctly.

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

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

The tool has zero parameters and the schema shows none. The description implicitly confirms this by stating 'Call this before the first run on a machine' with no mention of inputs. Since there are no parameters to explain, the description effectively communicates that it requires no configuration. This is a perfect fit for the no-parameter case, and the baseline of 4 is exceeded because the description makes the absence of parameters obvious.

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: 'Check that everything needed for a run is present and working.' It specifies a concrete action (check) and a distinct resource (run prerequisites). It differentiates from siblings like voltage_status and voltage_diagnose by enumerating the exact checklist items (session type, permissions, capture backends, geometry, GPU memory, model backends). This makes it unambiguous which tool to select for pre-flight validation.

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

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

The description gives explicit timing guidance: 'Call this before the first run on a machine.' While it doesn't mention alternatives or when not to use it, the instruction is clear and actionable. It implies this is a single-use setup check, not a repeated monitoring tool. The guidance is sufficient for the agent to decide when to invoke it, though lacking explicit 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 destructiveHint: true, readOnlyHint: false, and openWorldHint: true. The description adds critical behavioral context: it defaults to dry_run ('pass dry_run=false to actually inject') and notes the safety policy. It also explains that this is a manual override path. These details go beyond the annotations and inform the agent about side effects and prerequisites.

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

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

The description is well-structured and efficient: it leads with the core action, then gives usage scenarios, then provides a syntax example and necessary caveats. Every sentence earns its place, and the dry_run warning is front-loaded within the critical context. No fluff 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?

Given the tool's complexity (custom syntax, safety policy, dry_run default) and that an output schema exists, the description covers the essential aspects: purpose, when to use, how to construct the burst (via example and reference), and the dry_run behavior. The only gap is a full in-place explanation of the syntax and label, but the reference to voltage_reference and the presence of an output schema mitigate this. Overall, it is nearly complete for an agent to call it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It provides a concrete syntax example (`m:640,360;c:l;w:120;t:"hello";k:enter`) and explains the dry_run parameter clearly. However, burst syntax is not fully documented (only a pointer to voltage_reference) and the label parameter is not explained beyond its default. This is partial compensation—helpful but not exhaustive.

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 ('Execute one input burst yourself') and the resource (burst), and immediately differentiates from siblings by emphasizing 'bypassing the local models entirely' and 'moments that need your judgement rather than the actuator's'. It also names the exact use case (opening applications, clicking confirmed targets, typing exact text) and points to voltage_reference for full syntax, making the purpose unmistakable.

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 states when to use this tool ('For moments that need your judgement rather than the actuator's', 'the fastest way to sanity-check that input injection works at all'), implies alternatives by referencing voltage_reference for syntax, and reminds that 'the safety policy still applies'. This gives an agent clear decision-making guidance without ambiguity.

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

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

Annotations already mark readOnlyHint=true, and the description aligns with that by saying 'Read'. It adds value by explaining the behavioral semantics of the journal contents and the meaning of 'only_refused', which goes beyond the raw annotation. No contradiction 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 focused sentences with the core purpose front-loaded and the filter tip as a concise, well-formatted follow-up. No filler or repetition, and the code-styled parameter reference is efficient.

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

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

An output schema exists, so return format is covered. However, the description fails to explain the run_id parameter, which is central to selecting a run, and gives no mention of limit. The tool is simple with all optional params, but the missing parameter descriptions leave a gap in usability.

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

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

Schema description coverage is 0%, so the description must compensate. It explains only_refused in detail, but completely omits run_id and limit. run_id is critical for identifying which run to read, and limit is a common but still undocumented control. The description is inadequate for a zero-coverage schema.

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

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

The description states a specific verb ('Read') and resource ('a run's cycle-by-cycle record'), and lists the exact contents: what was seen, decided, refused, executed. This clearly distinguishes it from siblings like voltage_observe or voltage_diagnose by framing it as a chronological journal rather than a live observation or diagnostic.

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 explicit context for using the 'only_refused' filter and explains the fastest way to see policy/actuator disagreement. While it doesn't mention sibling tools for comparison, the usage hint is concrete and actionable, and the description clearly implies this tool is for inspecting historical decisions.

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 a mutating, potentially destructive action (readOnlyHint=false, destructiveHint=true); the description does not contradict these and adds that notes are stored against a target. It does not describe side effects or permissions, but given annotation coverage it provides acceptable additional 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 efficiently structured: it opens with the core purpose, gives clear good/bad examples, and ends with a concise classification of kind values. Every sentence adds value, and the format is well-balanced for the tool's complexity.

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

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

For a tool that records notes, the description covers the purpose, content quality, and kind taxonomy, which is sufficient for basic use. Gaps remain around `playbook` and exact behavior (e.g., confirmation, persistence), but the presence of an output schema and annotations mitigates these. Overall it is fairly complete.

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

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

With 0% schema description coverage, the description compensates by explaining the meaning of `kind` (label, timing, policy, burst, observation) and prescribing the format for `note` via good/bad examples. It leaves `target` and `playbook` undefined, but `target` is self-evident and `playbook` remains ambiguous, so coverage is partial but effective.

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 records reusable facts against a target, with concrete good/bad examples that make the purpose unmistakable. It does not explicitly differentiate from sibling tools like voltage_lessons, but the 'carrying to the next run' phrasing is specific enough to convey its unique role.

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 strong guidance on what to record (concrete facts, not narration) and explains the kind grouping, but it never mentions alternative tools or conditions under which to avoid this tool. Usage context is implied rather than explicit, and no exclusions or comparisons are given.

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

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

Annotations declare readOnlyHint=true and the description aligns with that (no mutation implied). The description adds valuable behavioral context: lessons persist across sessions, are keyed by target, and include specific types of information (labels, HUD probes, timing). This goes beyond the annotation by describing persistence and content, which is useful for setting expectations about what the tool returns.

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

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

The description is concise and front-loaded with the purpose. It uses bold for emphasis ('before writing a Playbook') and keeps each sentence purposeful. There is no filler or redundant explanation. The structure guides the reader from what the tool does, to when to use it, to how to filter results.

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

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

The tool has an output schema (as indicated by the context), so return values are documented elsewhere. The description provides sufficient context for an agent to decide when to call it: it explains the purpose, when it is appropriate (before writing a Playbook for a previously driven target), and how to control scope with the target parameter. No critical information is missing, given the read-only annotation and output schema.

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

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

The input schema has 0% description coverage, so the description must compensate. It clearly explains the `target` parameter (keyed by target, omit to see everything) and gives examples of valid values. However, it does not mention the `limit` parameter at all, leaving its semantics to inference from the default value of 30. This is a partial compensation but not complete for both 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 opens with a specific verb and resource: 'Recall what previous runs learned about driving something.' It then gives concrete examples of lesson content (labels, HUD probes, timing), which makes the tool's purpose unambiguous and distinct from any other sibling. The behavior is clearly scoped to recalling learned lessons, not a general-purpose query.

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

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

It explicitly instructs when to use the tool: 'Call this **before writing a Playbook** for a target you have driven before.' It also explains the benefit (start from previous discoveries rather than rediscovering) and provides parameter guidance: 'Omit `target` to see everything recorded so far.' This gives an agent clear, actionable context for choosing this tool over alternatives like voltage_learn.

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 convey read-only and closed-world hints. The description adds valuable behavioral context: it clarifies that 'watch' is a closed vocabulary, that the tool runs a single pass, and that missing elements imply guards never fire. This goes beyond the annotations and provides actionable insight into the tool's behavior.

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

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

The description is concise, with two short paragraphs that are front-loaded with the core purpose. Every sentence adds distinct value—stating the action, vocabulary constraint, and practical implication. There is no fluff 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?

The description captures the tool's primary purpose and a key behavioral consequence, and an output schema exists so return values are already documented. However, it does not explain non-required parameters (region, read_text, max_elements), which are likely needed for correct invocation. This gap reduces completeness, though the core use case is well covered.

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

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

Schema description coverage is 0%, so the description must compensate. It explains 'watch' as the closed vocabulary, which is essential, but it omits any explanation for 'region', 'read_text', and 'max_elements'. With only one parameter addressed, the description fails to adequately clarify the remaining parameters, leaving the agent with insufficient 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?

The description clearly states a specific verb and resource: 'Run one vision pass and return grounded elements in screen coordinates.' It also explains a distinct use case—checking if the vision model can find elements before committing to a Playbook. While it doesn't explicitly contrast with sibling tools, the purpose is 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 provides explicit context for when to use the tool: 'Use this to check that the vision model can actually find what a state depends on before committing to it in a Playbook.' This is a clear directive without naming alternatives, but it effectively guides the agent on ideal usage scenarios.

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

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

Annotations already flag destructiveHint=true, so the mutation nature is disclosed. The description adds the specific behavior that held input is retained, which goes beyond the annotations and gives the agent useful context about the pause/resume semantics. 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 with zero filler. The core action is front-loaded ('Pause or resume a run') and the clarifying detail about held input follows immediately. Every word 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?

Given the existence of an output schema and simple optional parameters, the description is far from complete. It lacks usage guidance, parameter semantics, and any mention of prerequisites or side effects beyond the held-input note. The agent would need to guess how to set 'resume' or when to pass 'run_id'.

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

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

Schema description coverage is 0% — neither 'resume' nor 'run_id' is explained in the schema. The description does not mention any parameters at all, so the agent has no idea that 'resume' likely indicates whether to resume or pause, or how 'run_id' selects the run. With two parameters and zero coverage, the description must compensate but fails completely.

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 clear action (pause or resume), a specific resource (a run), and adds a key nuance (held input is not released). It distinguishes implicitly from voltage_stop but does not name sibling alternatives, 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?

No explicit guidance on when to use this tool versus alternatives like voltage_stop or voltage_run. The note about held input hints at a use case but does not state conditions or exclusions, leaving the agent to infer when pause 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 declare readOnlyHint=true, so the description need not restate safety. It adds value by explaining the content structure and the purpose of each section, which helps the agent understand what the tool actually returns. However, it does not disclose any potential caveats (e.g., response size, format specifics), though those may be covered by the output schema. The added context justifies a score slightly above baseline.

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 efficiently organized: a one-line purpose, then a bulleted list of sections with clear labels and explanations. It front-loads the main instruction and uses formatting to allow fast scanning. No sentence is redundant; each adds useful detail about content or usage.

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

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

For a reference tool, the description covers all essential information: what it returns, when to call it, what each section contains, and even contextual reading order. The read-only behavior is covered by annotations, and the output format is presumably defined by the output schema (present signal). Nothing necessary for an agent to select and invoke this tool is missing.

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

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

Schema description coverage is 0%, so the description must explain the 'section' parameter. It does so comprehensively by listing each enum value and its meaning, and even offers reading-order guidance (e.g., 'Read this second', 'Read this if...'). This fully compensates for the schema gap, making the parameter self-documenting.

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 ('Return') and a resource ('everything needed to author and iterate on a run'), then enumerates the sections returned. It clearly distinguishes itself from sibling tools (e.g., voltage_execute_burst, voltage_validate_playbook) by being a reference/documentation tool, not an execution or validation 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?

The description explicitly says 'Call this before your first Playbook,' giving a clear when-to-use directive. It also provides conditional reading order (e.g., 'Read this if bursts are coming out one action at a time') and labels like 'the learning loop,' which help an agent decide which section to request. This is strong, situation-specific 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 mark destructiveHint and openWorldHint, and the description complements these by explaining concrete behaviors: immediate return with run_id, polling requirement, dry_run overriding policy, and the specific conditions that terminate a run. It adds value beyond annotations without contradicting them.

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

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

The description is efficiently structured: the core action and return contract are front-loaded, followed by parameter guidance and termination behavior. Every sentence adds functional value, and no redundant or filler content is present.

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

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

The description covers the essential lifecycle: starting, monitoring, adjusting, and stopping. It explains dry-run semantics and stopping triggers. However, it does not describe the structure of the `playbook` object or the meaning of `keep_frames`, which may be important for correct invocation. The presence of an output schema and related tools (voltage_validate_playbook) partially mitigates 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?

Schema coverage is 0%, so the description must explain parameters. It does explain dry_run (including override semantics and default behavior) and target_period_s (with recommended values), but it does not explain `playbook` (the required parameter) or `keep_frames`. Since playbook is central and the schema offers no description, this leaves a gap for an agent constructing a valid call.

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

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

The description opens with 'Start a Playbook,' a specific verb-resource pairing that clearly states the tool's core function. It immediately distinguishes itself from siblings by mentioning polling with voltage_status, stopping with voltage_stop, and live adjustment with voltage_steer, so the agent can tell it apart without opening other schemas.

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

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

The description provides explicit context for when to use dry_run ('the correct way to check that your states, guards and transitions behave before letting it touch the machine'), recommends values for target_period_s, and explains how to stop or adjust a run using sibling tools. It also details automatic stopping conditions (budget, keyboard/mouse input, panic file), giving clear operational 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=true and openWorldHint=false, so the read-only nature is covered. The description adds useful context beyond annotations: the specific data included (recent cycles, governor refusals, per-stage timings) and its diagnostic intent. 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 with no waste. The action is front-loaded ('Poll a run'), followed by a list of what it returns and the diagnostic purpose. Every phrase 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 monitoring tool with an output schema present, the description conveys enough about the returned data to be useful. However, the lack of parameter documentation is a notable gap that makes it slightly incomplete.

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

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

Schema description coverage is 0%, and the description does not explain either parameter (run_id, journal_tail) at all. While run_id is somewhat inferable from its name, journal_tail is completely unexplained. The description fails to compensate for the schema's lack of documentation.

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 ('Poll') and resource ('a run'), then enumerates the returned data (state, variables, last burst, vision model view, cycles, refusals, timings). This clearly differentiates it from sibling tools like voltage_capture or voltage_execute_burst, which imply different actions.

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 implies usage during a run to monitor state and diagnose slow loops ('so you can tell whether a slow loop is capture, vision, decision, or execution'). However, it doesn't explicitly state when not to use it or point to alternatives such as voltage_doctor or voltage_diagnose, leaving some ambiguity.

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

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

Annotations already flag destructiveHint=true, so the description adds some context: hint persists, force_state jumps the machine, variables updates, dry_run can flip. However, it does not disclose potential side effects, irreversibility, or prerequisites despite the destructive nature. It does not contradict the annotations, but the coverage is not thorough.

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 concise and well-structured: a one-sentence overview followed by per-parameter explanations. It is front-loaded with the main purpose, uses backticks for param names to aid scanning, and has no filler or redundant statements.

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

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

For a tool with 5 parameters, zero schema descriptions, a destructive annotation, and an output schema, the description covers the core actions but misses run_id semantics, any warning about destructive consequences, and what the output schema contains. It is usable but not fully complete for safe and 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 0%, so the description carries the full burden for parameter meaning. It explains hint, force_state, variables, and dry_run, but omits run_id entirely, leaving its role merely implied by the phrase 'a live run.' This is a partial but incomplete compensation.

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

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

The description states a specific verb-resource pair: 'Correct a live run without restarting it,' which clearly distinguishes this tool from siblings like voltage_stop, voltage_pause, or voltage_run. It also enumerates the effects of each parameter, leaving no ambiguity about what the tool does.

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

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

Provides a concrete usage scenario for `hint` ('when the actuator is doing something legal but wrong') and explains the function of each parameter (e.g., force_state jumps the machine, dry_run flips). It implies this tool is for mid-run corrections vs. restarting, but does not explicitly name alternatives or exclusion conditions.

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

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

Annotations already declare destructiveHint=true, and the description adds concrete behavior: releases every held key/button and interrupts bursts. This goes beyond the annotation's generic destroy flag without contradicting it, giving the agent a more precise model of consequences.

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 concise sentences convey the purpose, safety, and edge-case behavior with zero filler. Information is front-loaded and every clause earns its place.

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

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

For a simple stop tool, the description covers the main behavior and safety profile. However, the lack of any parameter explanation means an agent might guess wrong about 'run_id' or 'reason' (e.g., whether run_id is required to target a specific run). Optional parameters with defaults mitigate, but the gap prevents 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 description coverage is 0% and the description does not explain either 'reason' or 'run_id.' The agent has no guidance on what these parameters control or when to provide them, though they are optional. With no parameter documentation anywhere, this is a notable 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?

The description states a specific verb ('Stop') and resource ('a run') while adding unique scope: 'release every held key and button.' This clearly distinguishes it from siblings like voltage_pause and voltage_run, and the mention of interrupting mid-flight bursts further clarifies its specific role.

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: 'Safe to call at any time' and explicitly covers the edge case of a mid-flight burst. However, it does not explicitly contrast with alternatives like voltage_pause or voltage_steer, leaving some ambiguity about when to choose this over a pause or a graceful stop.

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 mark readOnlyHint:true. The description adds substantial behavioral detail: it returns a complete list of errors rather than one at a time, reports unreachable states and dead transitions, and explains how to interpret warnings. This fully complements the annotation and does not contradict it.

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

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

The description is tightly written, starting with the primary purpose, then detailing checks, then error behavior, then usage guidance and a warning interpretation. Every sentence serves a purpose—no filler. It front-loads the action and clearly organizes information in short block format.

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 validation tool with an output schema declared (though not shown explicitly), the description covers what it does, how it behaves, when to call it, and how to interpret results. With annotations covering read-only safety and the output schema expected to define return values, nothing essential is missing for an agent to decide and invoke correctly.

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

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

The input schema only defines a generic 'playbook' object with no description (0% coverage). The description compensates by making clear that the parameter is the Playbook being validated, and it describes what validation entails (schema, guards, bursts, references). This gives the agent enough context to pass the correct object, even without knowing its internal 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 description opens with a specific, unambiguous statement: 'Fully check a Playbook without running it.' It enumerates the exact validations performed (schema, guards, bursts, transition targets, probe references) and reports unreachable states/dead transitions, distinguishing this validation tool from siblings like voltage_run and voltage_execute_burst. The verb 'validate' matches the tool name and clears its role.

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

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

Explicitly guides usage with 'Always call this before voltage_run,' which states when to use this tool relative to its primary sibling. It also adds a practical hint about interpreting warnings (e.g., 'tests for X but X is not in watch'). It does not list explicit exclusions, but the directive is clear and directly actionable.

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