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

Annotations only supply readOnlyHint, and the description reinforces that with 'Read-only; touches neither host nor board.' More valuably, it discloses failure semantics that annotations cannot express: warnings flag an unloadable probes section and the caller must fix the board YAML before trusting probes. That is real behavioral context beyond the structured fields.

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

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

Front-loaded with the purpose and the call-first directive, and the result paragraph is tightly packed. The parenthetical emphasis ('most importantly') is slightly editorializing, but no sentence is wasted.

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

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

With an output schema present, the description need not enumerate return fields, yet it still summarizes the data/warnings split so the agent knows how to interpret results. Purpose, ordering, safety, and failure handling are all covered for a single-parameter read tool.

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

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

Schema description coverage is 100% and the single 'board' parameter is fully documented there, including the omit-to-use-server-argument fallback. The description adds no syntax, format, or precedence detail for the parameter, 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 ('Discover what hardware you are working with: the active board profile') and enumerates the concrete payload (name, MCU, firmware_dir, artifact, flash connection, probes). An agent can distinguish it from siblings like doctor, build, and flash without opening a schema.

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

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

Gives explicit ordering guidance ('Call this FIRST in any session') and cross-references the probe tool by noting the probes list holds the names probe accepts. It does not, however, state any condition under which you should skip it or name an alternative to use instead, so it stops short of full when/when-not coverage.

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 only idempotentHint available, the description carries the behavioral load fully: it discloses incrementality, that no hardware I/O occurs, the two result shapes (succeeded/exit_code 0 vs failed/BUILD_FAILED), where diagnostics surface (data.log naming file and line), and where the artifact lands. These are traits the annotations do not cover.

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

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

Front-loads the operation and its incremental/non-hardware nature, then moves to routing and outcome semantics. Every sentence is functional — the result-code and artifact-path sentences directly support post-call interpretation.

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?

Despite an output schema existing, the description adds interpretive value (log file naming the offending line, artifact path readiness for flash) rather than repeating return structure, and the parameter gap is covered by the schema. Nothing needed to call or interpret 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 100% and the single 'board' parameter is fully documented with default and fallback behavior, so the schema does the work. The description adds no parameter-level detail beyond what is already structured, which is the expected baseline.

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

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

States a specific verb and resource ('Compile the board's firmware') and immediately scopes it with 'incremental — recompiles only what changed' and 'No hardware is touched', which cleanly separates it from flash and probe. An agent can identify the operation without opening the schema.

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

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

Explicitly frames when to use it ('a fast failure loop') and when it is unnecessary ('verify runs the same build internally, so you don't need this before verify'), naming the sibling that subsumes it. This is precisely the kind of routing guidance that prevents redundant calls.

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 declare readOnlyHint=true, and the description agrees ('Read-only') rather than contradicting. It adds real context beyond the annotation: large values block for that long, silent windows are reported as '(console silent)', and silence after reset usually indicates wiring or baud trouble. It stops short of describing the return shape in detail, relying on the output schema.

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

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

The purpose is front-loaded in the first clause, and the diagostic aside on '(console silent)' earns its place. It is slightly verbose across three segments but no sentence is pure filler.

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

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

An output schema exists, so return-value documentation is not required, and the description covers timing, blocking, and failure interpretation adequately. The only minor gap is that it leans on the output schema for the exact data.text contract, which is acceptable here.

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 both parameters are already documented with defaults and clamping behavior. The description only loosely restates the 'seconds' semantics ('for the given number of seconds') and adds nothing new about 'board', so baseline 3 is appropriate.

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

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

States a specific verb and resource ('capture everything the firmware prints on the console') and pins the passive/silent scope ('sending nothing'). This clearly separates it from the sibling console_send, which an agent can distinguish without opening either schema.

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

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

Gives concrete usage contexts: watch boot banners, self-test prints, or fault dumps. It implies the alternative ('sending nothing') but never names console_send explicitly, so the routing guidance is clear rather than exhaustive.

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

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

Annotations (readOnlyHint=false, openWorldHint=true) only signal that this mutates device state; the description goes much further by disclosing the response channel (data.response), the wait_s timing window, the '(no response)' plus warning behavior on silence, the 'ERR unknown-cmd' fallback, and that replies are live hardware readbacks rather than cached values. That is exactly the extra behavioral context annotations cannot carry.

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

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

Front-loaded with the core action and example, and every sentence carries at least some operational value. The board-specific command guidance is however repeated in the description and again in the line parameter, which is mild redundancy rather than wasted content.

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

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

An output schema exists, yet the description still usefully names the response field, the timing window, and the failure signals, leaving nothing an agent needs in order to invoke and interpret this tool correctly.

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

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

Schema description coverage is 100%, so line, board, and wait_s are already fully documented including the verbatim-writing and buffer-overflow behavior. The description reinforces the 'led0?' example and board-specific command set but adds no parameter syntax or constraints beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('send ONE command line on the console UART and collect its answer') with an explicit cardinality constraint that separates it from passive read siblings like console_read. An agent can tell this is the active command-dispatch tool without opening the schema.

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

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

Gives clear context for use — direct firmware interrogation, board-specific command set discoverable via board_info and probe definitions — and tells the agent how to interpret 'ERR unknown-cmd'. It does not explicitly say when to prefer console_read or another sibling over this tool, so it falls short of a full when/when-not/alternatives statement.

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 adds useful context about what the report contains (data.log with 'issues:' list, empty problems + exit_code 0 means healthy). It doesn't cover whether findings are re-runnable, timing, or side effects, but for a read-only diagnostic the disclosure is strong.

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

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

Three sentences that are front-loaded with purpose, then usage conditions, then output interpretation. No filler, every clause carries information.

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

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

Covers purpose, preconditions, and output semantics (issues list, exit code). With an output schema present and annotations covering safety, this is nearly complete. Could mention board profile precedence more clearly, but that's in the schema.

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

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

Schema description coverage is 100%, and the parameter itself has a detailed description in the schema. The tool description adds no parameter-level information beyond what's in the schema, so baseline 3 is appropriate.

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

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

States a specific verb (diagnose) and a precise set of checks (ST-Link probe visibility, console serial resolvability, cross toolchain installed). This is clearly distinguishable from siblings like probe or board_info, which perform operations rather than environment diagnostics.

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

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

Explicitly states when to run it: 'before anything else when a board operation fails' and 'ALWAYS when a tool returns status "incomplete" or code CAPABILITY_UNAVAILABLE'. It routes the agent to this tool in specific failure conditions, which is exactly what usage guidance should do.

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, and the description reinforces with concrete consequences ('whatever runs on the MCU is replaced'). Beyond that it discloses retry policy (up to 3 attempts on transient errors), failure semantics (FLASH_FAILED, exit_code 2), and where output lands (data.log), all of which go beyond the annotation.

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 destructive warning and primary action, followed by dependency, retry, and failure-handling detail. Every sentence carries distinct, actionable information with no filler.

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

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

An output schema exists so return values need not be explained, yet the description still covers dependencies, retries, and failure routing. Combined with the destructive annotation, an agent has everything needed to call it safely and interpret failures.

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

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

Only one optional parameter and schema description coverage is 100%, so the schema fully documents the board profile path including fallback behavior. The description adds no additional parameter meaning, which matches the baseline 3 when the schema does 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+resource ('write the built firmware to the board's flash over ST-Link'), plus the follow-on actions (verify, start application). It is clearly distinguishable from siblings like build, verify, and probe.

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

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

Explicitly routes the agent: 'call build first if sources changed since' and 'Run doctor to tell an environment problem apart from a write failure.' It names both the dependency and the diagnostic alternative with the condition that selects each.

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 only readOnlyHint=false to go on, the description carries the burden well: it discloses the console UART dependency, states that missing UART yields CAPABILITY_UNAVAILABLE and 'never a pass,' decodes failed + PROBE_FAILED as a failed assertion, and points to data.log for the exact step and board response. It even discloses that live register readbacks occur.

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?

Densely front-loaded: capability first, parameter behavior second, failure semantics last. Every sentence is informative, though the names/omit-[] sentence partly duplicates the schema and could be trimmed.

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

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

An output schema exists, so return values need no prose, yet the description still covers the ambiguous outcome cases (CAPABILITY_UNAVAILABLE, PROBE_FAILED) that an agent must interpret. Nothing needed to call this tool 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 description for 'names' already says it draws from board_info's probes list and that omit/[] runs all, so the description largely restates structured data. The cross-reference to board_info is mildly useful but adds little beyond the schema baseline.

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

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

States a specific verb+resource ('exercise the firmware ALREADY RUNNING ... with its defined probes') and immediately distinguishes itself from build/flash siblings via 'No rebuild, no reflash.' It also names the mechanism (sends console commands, asserts on answers) so an agent knows exactly what class of operation this is.

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

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

Gives clear context for use: probes run against already-flashed firmware, names selects subsets from board_info's "probes" list, and omit/[] runs all. It does not explicitly contrast with the closest siblings (verify, console_send/console_read), leaving some routing to inference, but the when-to-use picture is solid.

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

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

Goes far beyond the single destructiveHint annotation: discloses that it rebuilds, flashes over ST-Link, starts the app, requires boot evidence (UART banner or SWD RAM signature with fail-closed wipe/readback), and enumerates all failure codes with their meanings. Explicitly flags DESTRUCTIVE flash rewrite and the persisted output files.

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 identity before the operational detail, and uses 'What it does:' style structure. Dense and long, but almost every clause carries behavioral meaning for a complex destructive operation, with minimal 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?

Covers the full lifecycle, the success/failure semantics, the destructive impact, and where transcript/record artifacts land (data.log, data.record, data.record_dir). With the output schema present, no return-value detail is missing for an agent to call and interpret this 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?

Only one optional parameter (board) with full schema description coverage and a clear default/fallback stated in the schema. The description adds no board-path syntax or precedence detail beyond the schema, so the baseline 3 for high coverage 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 precise verb+resource ('the hardware gate', 'does this firmware actually work on the board') and defines success concretely (board booted the exact tree, probes passed). Explicitly distinguishes itself from siblings: 'a clean build is not a pass' separates it from build/flash/probe.

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?

Strongly routes the agent away from weaker signals ('Trust no other signal; a clean build is not a pass') and frames itself as the authoritative final gate. It stops short of an explicit when-not-to-use statement or naming a specific alternative tool to run first.

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