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

With no annotations, the description carries the full burden. It does disclose the key trait that the result is a heuristic approximation, the frame ordering (innermost first, stack order), and the state requirements. However, it says nothing about failure modes when the core isn't halted, whether the call has any side effects on the session, or how much the output should be trusted versus a symbol-resolved backtrace.

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 one-line purpose, then prerequisites, then the heuristic caveat, then conventional Args/Returns. Every sentence carries information; nothing is repeated from the schema or padded.

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

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

An output schema exists, so return-format detail isn't required, and the description still gives the frame ordering. Combined with stated prerequisites and the heuristic caveat, an agent has enough to invoke it correctly; only error/edge-case behavior is left unstated.

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

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

Schema coverage is 0% (titles only), and the description compensates well for both params: session_id is tied to debug_session_start, and words gets a default (64) plus a hard cap (256) plus meaning ('stack words to scan'). That is real added value, but the depth is modest for a tool whose accuracy depends heavily on window size, so it sits just above baseline rather than at the top.

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 ('Reconstruct an approximate call stack') and names the exact inputs it works from (PC, LR, stack scan), which clearly separates it from siblings like debug_registers or debug_mem that return raw state rather than a reconstructed frame list.

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

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

Gives concrete preconditions — a halted core and an ELF-loaded session — which tell an agent when the call is valid and imply debug_halt / symbol loading must precede it. It stops short of naming alternatives (e.g. debug_registers for exact register values) or what to do when the heuristic is unreliable.

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

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

With no annotations, the description carries the full burden: it discloses that function names resolve via the session's ELF and that the breakpoint list is returned after the operation. It omits meaningful behavior for a mutation tool — the finite number of hardware breakpoint slots, error behavior when clearing a nonexistent location, and whether the core must be halted.

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 one-line purpose, then Args/Returns blocks with no filler. Slightly redundant in restating parameter names that the schema already lists, but efficient overall.

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 output schema covers return values, and the description covers all three parameters and the four actions. For a debug-breakpoint mutation tool with no annotations, key operational facts (hardware breakpoint limits, halt requirements, failure behavior) are absent.

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

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

Schema description coverage is 0%, so the description must do the work — and it does: action enumerates all four values and the 'list' default, location is defined as function name or hex address with an explicit ELF resolution rule, and session_id's origin is stated. Only edge details (default empty location) are missing.

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 ('Manage hardware breakpoints') and pegs it to the FPB unit, which separates it conceptually from debug_watchpoint. Sibling differentiation is implicit rather than explicit, so it stops short of a 5.

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

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

The action list ('set', 'clear', 'clear_all', 'list' default) and the note that location is required for set/clear give clear per-mode usage. However, it never says when to prefer this over debug_watchpoint or what preconditions (e.g., halted core) apply.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the central behavioral effect (the CPU stops) and the result shape, which is more than nothing. However, it is silent on whether the call blocks until the core actually halts, what happens if the target is already halted, and whether the halted state persists until debug_resume.

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 summary sentence up front, followed by short Args/Returns blocks with no filler. The docstring scaffolding is slightly heavier than needed given that an output schema already exists, but nothing 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?

An output schema exists, so restating return values is not required, and the parameter source is covered. What remains missing for a state-mutating debugger tool with zero annotation coverage is blocking behavior, error conditions, and interaction with breakpoints or prior halts.

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 single parameter is only titled 'Session Id' in the schema. The description compensates by naming its provenance, 'Session ID from debug_session_start', which is exactly the information an agent needs to supply a valid value. It stops short of stating what happens with an invalid or expired session.

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

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

States a concrete verb and resource: 'Halt the CPU and report where it stopped.' An agent can distinguish this from debug_resume, debug_step, and debug_registers. It does not explicitly distinguish itself from debug_wait_halt, which is the closest sibling and the most likely confusion point.

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 statement of when to call this versus debug_wait_halt, debug_step, or debug_status. The only guidance is implicit: the Args note that session_id comes from debug_session_start, which tells the agent this must follow session creation. Useful but not a real when/when-not policy.

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

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

With no annotations present, the description does meaningful work: it discloses the real-time-vs-halted capability, that it avoids spawning a second OpenOCD, that struct symbols auto-expand into per-field reads, and that address/symbol are mutually exclusive. It does not cover write safety while the core is running, failure behavior for a stale session_id, or rate/latency traits.

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 one-line purpose, followed by a scoping caveat, then structured Args/Returns. Every sentence conveys information an agent needs; no restatement of the tool name or 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 format needn't be explained, and the description still sketches it. All 7 params are addressed and the session dependency is traced back to debug_session_start. Missing failure/edge-case behavior (invalid session, address inaccessible, write while running) keeps it short of full completeness for a mutation-capable hardware 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% for 7 params, so the description must carry the load — and it documents every parameter, including the read/write values for `action` (absent from the schema's string enum), hex formatting for `address`/`value`, and width auto-derivation from symbol size. Minor gaps remain: `count` units/default interaction and what happens when `width` is supplied alongside `symbol` (schema default 32 vs 'auto from symbol size') are not reconciled.

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

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

States a concrete verb pair (read/write) and resource (RAM/registers) scoped to the active debug session, and explicitly contrasts itself with stm32_read_memory. It does not distinguish itself from live_memory_read/live_memory_write or debug_registers, which read similar data, so an agent still has residual ambiguity among those siblings.

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

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

Gives a clear positive condition (works both running and halted, no second OpenOCD) and names the alternative it replaces (stm32_read_memory). There is no explicit 'when not to use' guidance or routing toward live_memory_* / debug_registers alternatives that overlap functionally.

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

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

With no annotations, the description carries the behavioral burden well: it declares a read operation, requires a halted core, and explains return formatting in hex plus PC/LR source annotation when an ELF is loaded. It does not explicitly state error behavior if the core is running, but the prerequisite is disclosed.

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

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

The definition is front-loaded with the core operation and then uses clear Args/Returns structure. Every sentence adds useful information about prerequisites, accepted values, or return formatting without unnecessary 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?

The description covers purpose, prerequisite, parameters, and return behavior, which is strong given the zero schema coverage and lack of annotations. It could be slightly more complete by stating what happens if the core is not halted or by naming the relevant halt/status sibling tools.

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

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

Schema description coverage is 0%, so the description must compensate for both parameters. It does so fully: session_id is tied to debug_session_start, and regs is explained with default 'core', 'all', and single-register forms including concrete examples.

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

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

The description states a specific verb and resource: read core registers. It adds a critical execution condition, 'while the core is halted,' and clearly distinguishes register access from sibling memory tools such as debug_mem and stm32_read_memory.

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

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

It gives a clear prerequisite that the core must be halted and identifies debug_session_start as the source of the session ID. It does not explicitly name alternatives or state when not to use this tool, so it falls short of full when/when-not guidance.

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

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

With no annotations, the description carries the full burden. It usefully discloses the two-mode behavior of the halt flag and that a new target state is returned, but it says nothing about side effects (RAM/peripheral state loss, whether breakpoints survive the reset) or permissions — material for a state-changing target operation.

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

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

Front-loaded one-line purpose followed by tight Args/Returns sections, with no wasted prose. The docstring-style formatting is slightly verbose but each line 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?

An output schema exists, so return values needn't be detailed, and the description still summarizes them as 'New target state'. Combined with the parameter explanations, an agent has enough to invoke it correctly; only side-effect disclosure 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 carry the parameters, and it does: session_id's provenance is stated and halt is defined precisely for both values, including that false is the default and what 'true' means operationally (halt at the reset vector).

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

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

The description gives a specific verb and resource ('Reset the target (system reset)'), which is unambiguous and clearly distinct from siblings like debug_halt, debug_resume, and debug_step. It doesn't explicitly name a sibling it replaces, but the operation is self-evidently different from the other debug tools.

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

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

It states the prerequisite for session_id ('Session ID from debug_session_start') and explains the two operating modes, including the concrete use case for the halt path ('startup code inspection'). It lacks explicit when-not-to-use guidance or a pointer to alternatives such as debug_halt for a pure 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?

No annotations are provided, so the description carries the full burden. It does disclose one useful behavior — the already-running case — but doesn't say where execution runs to (next breakpoint? indefinitely?), whether breakpoints/watchpoints persist, or what state the core is left in. That's significant missing context for a tool that hands control back to the target.

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 compact Args/Returns block with zero filler. The docstring-style scaffolding is slightly heavier than needed for a single parameter, but nothing 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?

An output schema exists, so the Returns line is bonus rather than required, and one param is a small surface. But for a control-flow mutation tool with zero annotations and zero schema descriptions, the description should say more about post-call execution state than it does.

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% and the schema only offers 'Session Id' as a bare title, but the description compensates by tying the value to its source ('from debug_session_start'), which is genuinely new information. It still doesn't describe the ID's format or what an invalid/stale session ID does.

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 ('Resume execution of a halted core'), which makes it trivially distinguishable from the opposite sibling debug_halt and from debug_step. It doesn't explicitly name those siblings, but the 'halted core' scope does the disambiguation work.

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 precondition ('halted core') implies when the tool applies, and says nothing about when it does not — e.g. whether to use debug_step vs debug_resume vs debug_wait_halt, or what happens if no session is active. Usage is inferable rather than stated.

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

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: the connection is persistent OpenOCD, sessions are per-probe and singular, and the returned session ID is a required token for subsequent debug_* calls. It does not say whether starting a session halts or disturbs a running target, or what happens on a duplicate/failed start — gaps that matter for a stateful, mutating operation.

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

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

Front-loaded with the one-line purpose, then a capability summary, then Args/Returns blocks — easy to scan. Slightly padded by the Returns section, which duplicates the output schema, but no sentence is genuinely wasted.

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

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

For a stateful session-opening tool with no annotations and no schema descriptions, the definition covers purpose, prerequisites, identifier formats, the optional-but-recommended ELF, and the session-ID contract. Remaining gaps are failure modes and target-state side effects, which the output schema does not cover either.

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% and both properties are bare strings with defaults, so the description must compensate entirely — and it does. 'probe' accepts a board nickname, probe nickname, or ST-Link SN (three accepted identifier forms), and 'elf_path' is documented with its concrete effect (symbol names in breakpoints and source locations in halt reports) plus a 'Recommended' signal.

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 a real-time debug session') plus the underlying mechanism (persistent OpenOCD connection), and enumerates the capabilities it unlocks (halt/resume/step/reset, breakpoints, watchpoints, registers, stack). The phrase 'through the debug_* tools' and 'One session per probe' make it easy to place relative to debug_session_stop, debug_status, and live_memory_start.

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?

Implies the workflow clearly: start this first, then 'pass [the session ID] to all other debug_* tools', and notes the 'one session per probe' limit. It does not explicitly say when to prefer this over live_memory_start or serial_connect, nor what to do if a session already exists, so it stops short of full alternative 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?

With no annotations, the description carries the burden and does well: it discloses that OpenOCD itself is shut down, and explains the core-state consequence of resume_first (firmware keeps running vs. core left halted) including the default. It omits failure modes (unknown/expired session), whether OpenOCD must be restarted afterward, and whether breakpoints/session artifacts are discarded.

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

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

Front-loaded with the action and the loudest side effect in the first sentence; the Args/Returns blocks are short and every line adds information. No padding or restatement of the tool name.

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 the Returns line is optional and the description needn't detail the payload. For an unannotated teardown tool the behavioral essentials (what is shut down, what happens to the core) are covered; error handling and post-shutdown state would round it out.

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 compensates fully: session_id is tied to its source tool, and resume_first is documented with its default and the concrete behavioral outcome of each setting. This is meaningfully more than the schema's bare titles and default.

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 a debug session') plus the consequential side effect ('shut down OpenOCD'), which clearly distinguishes it from debug_halt/debug_resume and from live_memory_stop. The implicit pairing with debug_session_start (via the session_id reference) makes the lifecycle position 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?

Usage is only implied: the session_id provenance ('from debug_session_start') establishes it as the teardown counterpart, but there is no explicit statement of when to call it or what to call instead when only halting/stopping a run is desired. No exclusions or prerequisites 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?

No annotations are provided, so the description carries the full behavioral burden. It correctly discloses the conditional output shape (PC/LR/SP and source line only 'when halted'), which is genuine value, but says nothing about whether the call is read-only, side effects, whether it blocks, or what happens with an invalid/terminated 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?

Front-loaded purpose sentence followed by compact Args/Returns blocks. The Returns block is somewhat redundant given an output schema exists, but nothing is padded or 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?

Adequate for a single-parameter read: purpose, parameter provenance, and return contents are covered, and an output schema exists so return shape need not be spelled out. Missing is the runtime context an agent needs — liveness/precondition of the session, error behavior, and whether polling is expected.

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% for the single session_id parameter, but the description supplies its provenance ('Session ID from debug_session_start'), which is real meaning beyond the schema. It still does not state the failure mode for a stale/unknown ID or whether the session must be alive.

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 (report) and resource (debug session status) and enumerates the payload: core state, location, breakpoints, watchpoints. This distinguishes it from debug_registers (register dump) and debug_backtrace (stack unwind), 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 — an agent can infer this is the polling/inspection call for an active session. It does not say when to prefer it over debug_wait_halt (for blocking on a halt) or debug_registers when only registers are needed, and no preconditions (e.g. session must be started) are stated.

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

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

With no annotations at all, the description carries the burden and does disclose the key behavioral trait — it only applies to a halted core — plus the valid count range and the return payload (new PC, function name, source line). It stops short of saying whether breakpoints are honored during the step or what happens if the session is invalid.

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

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

The operation is front-loaded in one sentence, followed by a compact Args/Returns block. Every line adds information — no restatement of the tool name and 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 the return-value explanation is a bonus rather than a requirement, and the halted-core precondition is covered. Missing edge-case behavior (stepping over breakpoints, invalid or expired session) keeps it from being fully complete for a debugger mutation 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 must compensate and it does: session_id is tied to its source tool (debug_session_start), and count is documented with its range (1-100) and default (1). Both parameters gain meaning that the bare schema does not provide.

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: 'Single-step the halted core by N instructions', which is clearly distinct from debug_resume (free-run) and debug_halt. It does not explicitly name a sibling as an alternative, but the operation itself is 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 phrase 'halted core' implies the prerequisite that the target must already be stopped, but this is never stated as an explicit condition and no error behavior for a running core is given. Nothing routes the agent between this, debug_resume, and debug_breakpoint.

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

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

With no annotations, the description carries the full burden and does well: it discloses the blocking nature, the default 5000 ms timeout, and the give-up behavior with current state. It does not state whether the target stays halted afterward or what the failure mode is when nothing halts.

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 behavior, then Args/Returns blocks that are easy to scan. The Returns section partly repeats the opening paragraph and restates what the output schema already provides, which is mild 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?

For a two-parameter blocking debug tool this is nearly complete: ordering, timeout, and expected output are all covered, and an output schema exists for return detail. The remaining gap is post-halt state (does the core remain halted?) and the no-breakpoint case.

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

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

Schema coverage is 0%, so the description must compensate, and it does: session_id is tied to its producer (debug_session_start) and timeout_ms is explained as a give-up budget with its default. It adds no format or range constraints beyond the default.

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 precise verb and effect: block until the core halts, then report where. It is clearly distinguishable from siblings such as debug_status (non-blocking) and debug_halt (which causes the halt rather than waiting for one).

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 states the triggering condition explicitly: "Use after debug_resume when a breakpoint is armed." That is a concrete ordering rule an agent can act on. It stops short of naming when-not to use it (e.g. instead of debug_status polling) or what happens if no breakpoint is armed.

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

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

No annotations exist, so the description carries the full load. It does disclose the hardware-scarcity trait and the 'break only when value matches' conditional-stop semantics, which is genuinely useful. It says nothing about permissions, whether an existing watchpoint is overwritten, or whether the resulting halt requires debug_wait_halt to observe.

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 a compact Args block, with defaults stated inline. The Returns section is somewhat redundant given an output schema exists, but it is one line and adds little 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?

All six parameters are covered and the return value is summarized (though an output schema already exists, so that line is optional). The remaining gap is integration context: how watchpoint hits surface to the agent and how this interacts with the halt/resume and wait_halt siblings.

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%, and the description fully compensates: it documents every parameter including accepted string values for action and access, the allowed widths, the default for each, that location is required for set/clear, and that location accepts either an ELF symbol name or a hex address. This is exactly what the empty schema 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?

Opening line is a specific verb+resource: 'Manage data watchpoints (DWT comparators)'. It clarifies the mechanism and a key constraint (only a few per MCU). It does not distinguish the tool from the closely related debug_breakpoint sibling, so it stops short of a 5.

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

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

The action list implies when to set vs clear vs list, and 'usually only a few per MCU' hints at scarcity. But there is no explicit guidance on choosing watchpoints over debug_breakpoint or debug_mem, and no stated prerequisites (e.g. whether the target must be halted).

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

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

With no annotations, the description carries the burden and does real work: 'read' plus 'without touching the JSONL file' establishes non-destructive, non-persistent semantics, and 'in-memory ring buffer' with 'max 100' discloses bounded retention. It leaves gaps on error behavior (unknown/stopped session_id, empty buffer) and on whether reads consume or advance a cursor.

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 statement is front-loaded in the first two sentences, with param and return notes following. The Returns section ('formatted as text') is low value given an output schema exists, but the Args section carries the undocumented max=100 detail, so little is truly wasted.

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

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

For a 2-parameter read tool with an existing output schema, the description covers purpose, scope, prerequisite session, and parameter bounds. The remaining gap is edge-case behavior when the session is absent or the buffer is empty, which an agent calling this would benefit from knowing.

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% and the schema titles are bare ('Session Id', 'Last N'), so the description is the only source of meaning. It explains the provenance of session_id (from live_memory_start) and adds the max of 100 for last_n, which the schema does not state. Both parameters are covered, though not the behavior for out-of-range last_n.

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

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

States a specific verb and resource: 'Read recent entries from a live memory session'. The second sentence sharpens the scope by naming the mechanism ('in-memory ring buffer') and what it does not touch ('the JSONL file'), which implicitly separates it from stm32_read_memory and the persistent-log siblings. It stops short of naming a sibling alternative explicitly, so not a 5.

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

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

The only usage signal is embedded in the parameter note: 'Session ID from live_memory_start', which implies the session must be started first. There is no explicit statement of when to prefer this over stm32_read_memory, debug_mem, or live_memory_write, and no exclusions or failure 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?

With no annotations, the description carries the full burden and does so well: it discloses that a persistent OpenOCD connection is held, that results are streamed to a JSONL file and mirrored into a ring buffer, and that exclusivity is per-probe. The explicit warning to stop the session before flashing or direct memory access is exactly the kind of cross-tool hazard annotation would otherwise supply.

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

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

Front-loaded with purpose, then the critical exclusivity warning, then Args in schema order — a reader can stop at any tier. The closing Returns block slightly duplicates the existing output schema, and a few parenthetical examples run long, but no sentence is 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 stateful tool with five parameters, no annotations, and an output schema, this covers what an agent needs: lifecycle, exclusivity, side effects on disk, poll-rate floor, and interaction hazards with flashing and direct memory tools. Return values are the output schema's job and the description only sketches them.

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

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

Schema coverage is 0%, so the description must compensate and does: each of the five parameters is given meaning, including three accepted element formats for variables with worked examples, struct auto-expansion behavior with an expand:false escape hatch, the 250ms floor on interval_ms, and the output_path default. It also resolves the trap that variables is typed as a string but must contain a JSON array.

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 ("Start continuous background memory monitoring via SWD") and immediately ties itself to its siblings live_memory_read and live_memory_write, which are the read/edit counterparts of the session it launches. An agent can distinguish it from debug_session_start or stm32_read_memory without opening any schema.

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

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

Explicit when/when-not guidance: only one session per probe, stop existing sessions first, and stop live_memory before flashing or using stm32_read_memory/stm32_write_memory. That names concrete conflicting siblings and the ordering constraint that governs them.

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 zero annotations the description carries the full burden and does disclose real side effects: it stops the background polling thread and kills the OpenOCD process, then returns statistics. It doesn't state what happens with an unknown/stale session_id or whether the killed OpenOCD process is shared with other tools, which keeps 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 summary sentence first, then the mechanism, then a compact Args/Returns block. Every line adds information; 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?

Output schema exists so return values needn't be spelled out, yet the description usefully previews them (duration, read count, error count, output path). For a one-parameter lifecycle terminator this is nearly complete; only error/failure behavior on a bad session_id is unaddressed.

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

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

Schema coverage is 0%, so the description is the only source of meaning — and it supplies it, naming session_id as the ID obtained from live_memory_start. That provenance is the key fact an agent needs to supply a valid value, though no format/example is given.

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 ("Stop a live memory monitoring session") with a scope that clearly separates it from live_memory_start, live_memory_read and live_memory_write. An agent can tell what it terminates without opening any schema.

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

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

Usage is implied by the session lifecycle — you stop a session you started — but there is no explicit when/when-not guidance and no mention of the neighbouring alternatives (e.g. debug_session_stop, serial_disconnect) that could be confused with it. The exclusivity condition is left to inference.

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

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

With no annotations, the description carries the burden and does well: it discloses the write path (session's OpenOCD connection), that the session continues and subsequent polls reflect the new value, that floats require a 32-bit symbol, and that width auto-detects from symbol size. It omits risk notes about writing arbitrary addresses and any permission/state preconditions.

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 key behavioral fact (session keeps running), then structured Args/Returns blocks. Every line adds information; nothing is redundant.

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

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

For a 5-parameter mutation tool with no annotations, the description covers purpose, mechanism, parameter formats, exclusivity constraints, and a brief return note (an output schema also exists). An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 0%, so the description must compensate fully, and it does: session_id provenance, accepted value formats ("0xFF", "255", "0.85"), symbol as variable name or C dotted path with auto-detected width, address as hex, width meaning 8/16/32 bits and restricted to address form. Every one of the 5 parameters gains meaning beyond the schema.

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

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

States a specific verb and resource: 'Edit a variable through a RUNNING live memory session (live expression edit)'. The emphasis on running session and OpenOCD write path implicitly distinguishes it from stm32_write_memory, but no sibling is named explicitly, so it stops short of a 5.

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

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

Clear context for use: it writes through the live session so 'the monitoring session keeps running' and there is 'no need to stop and restart'. Mutual exclusivity of symbol vs address is stated. However, it gives no explicit exclusions (e.g. when to use stm32_write_memory or live_memory_read instead).

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

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

No annotations exist, so the description carries the full load, and it discloses the key non-obvious behavior: the connection persists across tool calls until explicitly disconnected, and the connection_id is the port path itself. It omits failure modes such as a busy port, permission/dialout requirements, and whether multiple simultaneous connections are supported, which is a meaningful gap for a resource-acquiring tool.

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

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

Front-loaded with the purpose, then structured Args/Returns sections with zero filler prose. The only slack is mild repetition of the port path in the Returns block ("the same value you passed as the port argument"), though that redundancy aids comprehension rather than hurting 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?

With an output schema present, the description needn't detail return payloads, and it still adds the critical fact that connection_id equals the port path. Persistence semantics and sibling relationships are covered. Missing only edge-case behavior (port in use, permission errors) that an agent would benefit from knowing 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 description coverage is 0%, so this description must compensate, and it does: port is explained as a path with a concrete example ("/dev/cu.usbmodem1234") plus the tool to discover valid values, and baudrate is explained with its default of 115200. Both parameters gain meaning they do not have in the bare schema.

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

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

States a specific verb and resource ("Open a serial connection to an STM32 board") and immediately distinguishes itself from the sibling data-plane tools (serial_send, serial_read, serial_disconnect). An agent can tell this is the setup step in a four-tool lifecycle without opening any schema.

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

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

Explicitly says to use serial_list_ports to find available ports, which routes the agent to the correct prerequisite sibling. It also implies the ordering (connect before send/read) via "for use with serial_send, serial_read". No explicit exclusion or "do not use when" statement, but the connect step has no alternative in this sibling set, so the gap is minor.

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

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

With no annotations, the description carries full behavioral burden. It clearly discloses the main side effects—closing the port and removing it from the pool—but does not mention idempotency, error behavior for invalid/already-closed connections, or whether other connections are affected.

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, and organized with Args and Returns sections. Every sentence contributes to understanding the action, parameter source, and return 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 one-parameter disconnect tool with an output schema and no annotations, the description covers the action, side effects, parameter provenance, and return type. It is nearly complete, though it could mention error or idempotency behavior for a mutation-like 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 0%, so the description must add meaning for the single required parameter. It does so usefully by identifying connection_id as the ID obtained from serial_connect, which goes beyond the bare schema title 'Connection Id.'

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: 'Close a serial connection.' It also clarifies the effect—closing the serial port and removing it from the connection pool—so the agent can distinguish it from sibling tools like serial_connect, serial_send, and serial_read.

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 by stating the connection_id comes from serial_connect, but it does not explicitly say when to disconnect, whether it should be called before reconnecting, or how it relates to alternatives. The usage context is inferable but not spelled out.

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

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

With no annotations, the description carries the full burden; it discloses that enumeration covers 'this machine' and that ST-Link VCP ports get a marker, which is genuine behavioral detail. It does not state that the call is non-invasive (does not open or lock ports), nor whether enumeration can be slow or miss virtual/hot-plugged ports.

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

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

Front-loaded with the core action, and the field list (path, description, VID:PID, serial number) is useful pre-call context. The trailing 'Returns: List of serial ports with details' sentence is largely redundant given an output schema exists, so it is not perfectly lean.

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 already documents the return shape, so the description need not have restated it; what it does provide — the machine-local scope and the [ST-Link VCP] marker convention — is exactly the kind of thing the schema cannot express. Nothing essential for a zero-arg enumeration 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?

The tool takes zero parameters, so there is no parameter semantics to explain — the baseline of 4 applies. The description correctly adds no parameter chatter that would be irrelevant here.

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

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

States a specific verb and resource (list / serial ports) plus the scope: ports on this machine, not remote ones. It also differentiates from the nearby stm32_list_probes by clarifying that ST-Link VCP ports are annotated in the output rather than being a separate probe enumeration.

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

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

Usage is only implied: the natural inference is 'call this before serial_connect to learn the device path', but the description never says that or names serial_connect as the follow-up. No prerequisites, exclusions, or note about when port enumeration would be empty or unhelpful.

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

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

With no annotations, the description carries the full burden and does a decent job: it discloses the polling mechanics (50ms inter-byte, 200ms silence break), the blocking timeout behavior, and the exact no-data sentinel string. It does not say whether the read drains/consumes the buffer, what happens on an invalid or disconnected connection_id, or whether concurrent reads are safe — meaningful gaps for a buffer read.

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

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

Front-loaded with the purpose, followed by behavior, then a compact Args/Returns block — the structure is easy to scan. There is mild redundancy in restating schema defaults (2.0, 4096) and in repeating the return value that the output schema already covers.

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 3-parameter read tool with no annotations, the description covers purpose, timing behavior, parameter meaning, and the no-data case. The remaining gaps — buffer consumption semantics and error conditions on a stale connection — are the only things an agent might still need.

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, and it does: all three parameters are explained, including provenance for connection_id ("from serial_connect") and the meaning plus defaults for timeout and max_bytes. It stops short of units/edge cases (e.g. timeout=0 for non-blocking, max_bytes truncation 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?

States a specific verb and resource ("Read data from the serial port buffer") and immediately clarifies the read semantics — returns whatever is available or arrives within the timeout. An agent can distinguish it from serial_send by verb alone, but the description never explicitly contrasts itself with the sibling tools (e.g. serial_sequence, live_memory_read).

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?

"Useful for catching async output like boot messages or periodic prints" gives a concrete usage context, which is more than most definitions offer. However, it never says when NOT to use it (e.g. for request/response after serial_send) or names an alternative tool, so the routing guidance is incomplete.

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

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

With no annotations, the description carries the full burden and does meaningful work: it discloses that sending appends a line ending, that the read is a polling loop with 50ms inter-byte and 200ms silence-break timing, and that read_timeout bounds the wait. What it omits is failure behavior (unconnected board, no response) and any warning that writing to a live target can perturb 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?

Front-loaded with the purpose, then Args/Returns sections — well structured and easy to scan. There is a small redundancy between the first sentence and 'Sends the data string (plus line ending) to the connected board,' but nothing is padded.

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

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

For a five-parameter, two-required tool with no annotations, the description covers behavior, all parameters, and the return shape (an output schema also exists, so that section is a bonus rather than a necessity). The remaining gap is error/edge-case behavior when the connection is invalid or the read times out silently.

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% — every property is just a title — so the description must compensate, and it does: all five params get meaning, including the line_ending value set ('lf', 'cr', 'crlf', 'none') that the schema does not encode as an enum, plus the read_timeout default and its unit. Only 'data' is thin (no encoding or size 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 ('Send data over serial') plus the conditional read behavior, which is enough to distinguish it from a pure-read sibling like serial_read. It does not explicitly name serial_read or serial_sequence as the alternatives, so sibling differentiation is implicit 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?

Usage is implied ('optionally read the response' hints that pure reads belong to serial_read), and connection_id is tied back to serial_connect, but there is no explicit when-to-use/when-not statement or named alternative. An agent must infer the routing from the sibling list rather than from the description.

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

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

With no annotations, the description carries the full burden and does well: it discloses that mem_write/mem_read spawn a fresh OpenOCD process with tens-of-ms overhead so sub-10ms memory delays are inaccurate, that delay steps are accurate, the on_failure default, the filter_responses semantics, and where capture PNGs land. It lacks any statement about concurrency, permissions, or partial-failure result shape beyond the return summary.

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 primary capability and the important timing caveat, then organized as Args/Returns. Length is justified by the empty schema, though the per-step type reference duplicates some of the prose that follows 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?

A complex multi-mode tool with a rich output schema, and the description covers step construction, failure policy, and timing limits. Minor gap: it says 'steps: JSON array' while the schema types it as a string, leaving the encoding requirement implicit.

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% (steps is a bare string), so the description must do all the work — and it does, enumerating every step type with example JSON, field meanings, defaults, hex address format, symbol+elf_path alternative, width rules, and label semantics. An agent can construct a valid call from this text alone.

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

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

States a specific verb and resource: 'Run a multi-step hardware sequence (serial + SWD memory) in one tool call.' The scope ('sequential, real timing, no tool-call overhead') clearly separates it from one-shot siblings like serial_send and stm32_write_memory.

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: timing-sensitive test sequences, blinking GPIOs over SWD, bit-banging registers, mixed serial/memory flows. It stops short of explicitly naming when to prefer serial_send or stm32_read_memory instead, so the exclusion side is 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?

No annotations exist, so the description carries the full burden, and it does disclose meaningful behavior: it shells out to STM32_Programmer_CLI, passes firstinstall=1, and surfaces a named error condition with a recovery path. It stops short of stating destructive effects (whether flash/option bytes are erased) or whether a power cycle/reset is required after the co-processor stack is loaded, which are real gaps for a firmware-writing operation.

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

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

Front-loaded with purpose and ordering, then structured Args/Returns sections tied to the actual parameters; nothing is bloated. The 'Uses firstinstall=1' detail is implementation trivia that contributes little for an agent.

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 summarizes the response shape, and it covers prerequisites, failure diagnosis, and sibling routing. Given no annotations at all, it should additionally say what the install overwrites and whether a board reset/power cycle follows.

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% (bare strings only), and the description compensates for all three parameters: probe accepts three identifier forms (board nickname, probe nickname, ST-Link SN), variant is constrained ('only full is currently wired', others live at different addresses), and wireless_dir is optional with a named binary directory. This is information an agent could not get from 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 ('Install BLE stack on an STM32WB board') plus a scoping prerequisite, and positions itself as 'Step 2 of first-time bringup', which distinguishes it from the FUS tools in the sibling list. An agent can identify the operation and its place in the workflow 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 an explicit precondition ('requires FUS already upgraded'), an ordering rule ('Step 2 of first-time bringup'), and a concrete fallback: on FUS_STATE_IMG_NOT_FOUND, run stm32_fus_upgrade first. This names the sibling tool and the condition that routes to 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?

With no annotations, the description must carry the behavioral burden. It does disclose the transport (connects via SWD) and the read-only nature of the call, but says nothing about failure modes when no board is attached, whether it claims the probe and conflicts with an active debug session, or any permission/state requirements.

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

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

Purpose is front-loaded in the first sentence and the Args block earns its place by defining the identifier forms. The Returns block largely restates the info list already given in the opening sentence and is redundant given an output schema exists.

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 tool with an output schema, this covers purpose, identifier formats, and when to call it. The missing piece is behavior on connection failure or probe contention, which matters for an SWD-attaching tool with no annotations.

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%, but the description compensates by explaining that `probe` accepts a board nickname, a probe nickname, or an ST-Link serial number to target a specific board. The only gap is that it does not state what happens when `probe` is omitted (the default empty string).

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

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

States a specific verb and resource (read board info over ST-Link/SWD) and enumerates exactly what is retrieved: ST-LINK version, voltage, CPU type, flash size. It is clearly distinguishable from siblings like stm32_list_probes or debug_status, though it never names an alternative 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?

"Useful for verifying the ST-Link connection before building/flashing" gives a concrete when-to-use context. There are no exclusions or named alternatives (e.g. versus stm32_list_probes for enumerating attached probes), so it stops short of full routing guidance.

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

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

With no annotations at all, the description carries the full burden. It discloses useful behavior: 'clean' forces a full rebuild and is slower, and the return includes filtered compiler output, errors/warnings, ELF size, and the .elf path. It does not cover failure modes, timeouts, filesystem/build-artifact effects, or whether build output is cached between runs.

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

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

The description is front-loaded with the core action and organized into Args and Returns sections, which makes it easy to scan. A few lines border on redundant with the schema, but no sentence is truly wasteful.

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

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

For a three-parameter build tool, the description covers the essential inputs and a summary of outputs, and the presence of an output schema means return values need not be exhaustively restated. The main remaining gap is the absence of usage guidance relative to stm32_build_and_flash and any environment 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 description coverage is 0%, so the description must document all three parameters. It does so clearly: project_path must be absolute and contain .project/.cproject, configuration is 'Debug' or 'Release', and clean triggers a pre-build clean. The schema defaults for clean and configuration are not restated, which is minor since they are visible in the schema.

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

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

The description states a specific verb and resource ('Build STM32 firmware using CubeIDE headless builder') and explains that it compiles the project at project_path, which is clearly identifiable. It lacks explicit differentiation from the sibling 'stm32_build_and_flash', so the agent must infer which build entry point to use.

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 when this is appropriate (a build-only operation) and notes that CubeIDE headless mode detects added/deleted sources without Makefile maintenance. However, it never explicitly says to use this instead of 'stm32_build_and_flash', nor does it state preconditions such as having a configured toolchain.

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

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

With no annotations, the description must carry the full behavioral burden. It does well on what the operation does (compile, then flash over ST-Link, optional clean/reset/verify), but omits key traits: that it overwrites the board's existing flash (destructive), whether flashing is skipped when compilation fails, and the need for a connected probe.

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 one-line purpose, followed by a short explanation and a compact Args block for the six fields, plus a returns line. Nothing is padded, and the primary guidance appears before the supporting detail.

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 detail is not required, and the parameters are well covered. What is missing is the failure and prerequisite behavior that an agent needs before invoking a hardware-mutating tool with no annotations: probe connection requirements and what happens on a failed build.

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, and the Args block documents all six parameters: the absolute CubeIDE project root path, the "Debug"/"Release" configuration values that the plain string schema does not constrain, and the probe identifier formats (board nickname, probe nickname, or ST-Link serial number). Remaining flags are described only by restating their titles.

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

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

States specific verbs and resources: it compiles the project and flashes the resulting .elf to a connected STM32 via ST-Link, in one step. It further distinguishes itself from the sibling stm32_build and stm32_flash tools by declaring it is the preferred combined workflow.

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

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

Explicitly says this is the most common workflow and should be used instead of calling stm32_build and stm32_flash separately, naming the alternatives directly. It doesn't say when to prefer the split calls (for example, build-only for compile checks), leaving that to inference.

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

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

With no annotations, the description must carry the full burden, and it does disclose real behavior: it overwrites the board's flash, uses OpenOCD/SWD, and explains what reset and verify actually do. It does not state that flashing is destructive/irreversible, what happens on verification failure, or how a probe is chosen when multiple boards are attached.

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 one sentence, followed by an efficient Args block that documents exactly the four parameters. The Returns block is mildly redundant given an output schema exists, but costs little.

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 mutating hardware tool with no annotations, the definition covers purpose, mechanism, and every parameter, and an output schema covers return values. The missing piece is the absence of safety context (flash is overwritten) and sibling routing, which would matter for an irreversible hardware 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 0%, so the description must compensate, and it does: it names all four parameters and adds meaning the schema lacks (accepted formats .elf/.bin/.hex for elf_path, hard-reset semantics for reset, content comparison for verify, and nickname-or-SN targeting for probe). Defaults and value types are left to the schema, which 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 ('Flash firmware to STM32 board via ST-Link') and adds mechanism detail (OpenOCD over SWD, writes to flash memory). It does not explicitly distinguish itself from the close sibling stm32_build_and_flash, which an agent might reasonably confuse it with.

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 description (use when you already have a built firmware file and a connected board), but there is no explicit when-to-use or when-not-to-use guidance. The obvious alternative, stm32_build_and_flash, is never mentioned, so the agent must infer the routing 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?

With no annotations at all, the description carries the full burden and does the important part: it discloses that FUS operations wipe flash sectors [0..3] via a helper binary, which is exactly the destructive side effect an agent must know before invoking. It also states the return content (full transcript of both steps). It does not mention duration, prerequisites such as an active probe/debug session, or whether a partial failure leaves the device in a recoverable 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?

Front-loaded with the action and the destructive caveat, then structured Args/Returns. Efficient overall. Minor redundancy: the follow-up re-flash instruction appears both in the body and again in the Returns section as 'a reminder to re-flash user firmware.'

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-stage destructive operation with an output schema, the definition covers the critical facts: what it does, what it destroys, and the required follow-up. The output schema relieves it of explaining return format. The remaining gap is preconditions (probe availability, whether a debug session must be active first), which matters for a bringup 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 0%, so the description must supply meaning and it does for both parameters: 'probe' is a board nickname, probe nickname, or ST-Link SN, and 'wireless_dir' is an optional path to STM32WB_Copro_Wireless_Binaries. This is genuinely additive over bare string types. It omits that both default to an empty string and what the empty default resolves to.

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

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

Names a specific composite action (FUS upgrade followed by BLE stack full install) scoped to STM32WB, and immediately narrows it with 'Does NOT re-flash user firmware.' That negative scope is what separates it from the sibling tools stm32_fus_upgrade and stm32_ble_stack_install, so an agent can pick correctly 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 explicit sequencing guidance: after this call, run stm32_build_and_flash with the correct project_path. That names an alternative tool and the condition that selects it. It stops short of saying when to prefer this one-shot tool over calling stm32_fus_upgrade and stm32_ble_stack_install individually, which is the one routing decision left to inference.

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

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

With no annotations at all, the description carries the full burden. It usefully discloses the concrete invocation behavior (mode=UR, firstinstall=0, honoring FUS_INSTALL.md) and the binary-directory fallback chain, but says nothing about the risk profile of a firmware write: whether it is irreversible, how long it takes, whether a failure can brick the FUS, or what permissions/tooling (STM32_Programmer_CLI) must be present.

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

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

Front-loaded with the purpose, then prerequisites, then Args/Returns — an agent can stop reading after sentence two and still be correct. The Returns block is largely redundant given an output schema exists, which costs a little tightness but not much.

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 firmware operation this covers purpose, ordering in the bringup sequence, argument resolution, and sourcing of the binaries — enough to invoke it correctly. The remaining gap is the operational risk/failure behavior, which matters most here and is absent.

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

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

Schema description coverage is 0% and the schema only carries bare titles, so the description must compensate and does: `probe` is defined as board nickname, probe nickname, or ST-Link SN, and `wireless_dir` is marked optional with its full fallback resolution ($STM32_WIRELESS_BINARIES then ~/stm32cube-wb/...). That is more meaning than the schema provides 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 first sentence gives a specific verb and resource ("Upgrade FUS on an STM32WB board") and the description adds scope (step 1 of bringup, only for boards with an older FUS). It implicitly separates itself from stm32_ble_stack_install by ordering, but never distinguishes itself from the closely named sibling stm32_fus_bootstrap.

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 use it ("Step 1 of first-time STM32WB bringup. Must run before installing a modern BLE stack on a board shipped with an older FUS"), which is a real precondition an agent can check. However, it gives no guidance on when to prefer stm32_fus_bootstrap or what to do if the FUS is already current.

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

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

No annotations are provided, so the description carries the full disclosure burden. It helpfully reveals the hidden behavior of reading from a persistent board map file (~/.stm32-mcp/board_map.json) and that it actively queries each probe for MCU info — the latter implies possible interaction with a target (potentially halting or resetting it if connected), but the description never states whether this is safe on a running target or requires an idle board. It also never explicitly declares the operation read-only or side-effect-free.

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 lead sentence front-loads the core action, and the follow-up details the enumeration and enrichment logic. The 'Returns:' block is structured and readable, but since an output schema already exists, it somewhat duplicates structured data and lengthens the description unnecessarily.

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 listing tool, the description covers what it does, how it gathers data, where nicknames come from, and what the output contains. An output schema exists, so the explicit Returns block is redundant but not harmful. The only real gap is the absence of any guidance about its relationship to stm32_board_info and whether querying each probe is safe 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?

The tool takes zero parameters, which is the baseline-4 case. Nothing about parameters needs explaining, and the description correctly presents this as an unconditional, no-argument operation.

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: "Show all connected ST-Link probes and boards with nicknames," then elaborates on enumeration, MCU info reads, and enrichment from the board map. The purpose is unambiguous. It does not, however, distinguish itself from the close sibling stm32_board_info, which presumably also reports board details, leaving the agent to guess which to call when both are available.

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 use this tool versus stm32_board_info or the serial_list_ports sibling, and no prerequisites or exclusions are mentioned. The agent must infer usage entirely from the tool name and output description.

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

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

No annotations are provided, so the description must carry the full burden of disclosure, and it does reasonably well: it names the OpenOCD backend, explains the elf_path dependency for symbol resolution, states that width is auto-detected from the resolved symbol, and describes the return format as hex values. It omits whether the core must be halted or resumed while reading, and what errors occur when no board is connected.

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: a one-line summary states address-versus-symbol access, followed by a compact Args/Returns block, so it is easy to scan. There is minor redundancy between the summary and the Args block (both explain symbols), but no wasted padding.

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

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

Because an output schema exists, the definition does not need to explain the return values, although it still gives a one-line description. All six otherwise undocumented parameters are covered, along with the OpenOCD and connected-board requirement; the only gap is the absence of guidance on when to use this tool instead of the overlapping memory-read siblings.

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 must document the parameters itself, and the Args block defines all six: the address format ("0x20000304"), the symbol format (a plain name or a C path such as "g_app.dosing.cfg.pid_kp"), the purpose of elf_path, count as a number of units, width values 8/16/32 with auto-detection, and probe identity or auto-selection. The width default of 32 differs from the auto-detection behavior the description states, which is useful information.

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 definition names a specific verb and resource (read memory from the connected STM32 via OpenOCD) and states both access modes: a raw hex address or a symbol resolved from the ELF. This is clear, but the definition never names the siblings whose job overlaps, such as debug_mem or live_memory_read, so the agent must work out on its own which of these tools to use.

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 useful rules for choosing a mode: address and symbol are mutually exclusive, a symbol needs elf_path, and an empty probe auto-selects the only connected board. It says nothing, though, about when to prefer this tool over live_memory_read or debug_mem, and nothing about prerequisites such as whether the target must be halted.

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

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

With no annotations, the description carries the full burden and does well: it discloses that this mutates persistent mappings, that board nicknames survive probe swaps, and that empty nickname deletes the mapping. It omits error behavior (e.g., what happens if both identifiers are supplied) and any permission or auth requirements.

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

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

Front-loaded with the core action, then structured into persistence semantics, constraint, args, and return. The physical labeling advice ('colored dots, tape') is mildly tangential but serves as a practical reminder. No wasted repetition of schema types.

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?

Because an output schema exists, the description needn't detail return values, and the one-line 'Confirmation message' suffices. The input semantics, persistence behavior, and removal path are all covered. Only error/precondition handling (e.g., what happens when both identifiers are passed) is left implicit.

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 fully, and it does: nickname is described as a human-readable name with examples, mcu_uid and stlink_sn are each tied to their device class, and the exactly-one constraint plus the empty-string-as-delete semantics add critical meaning not present in the schema's bare string types and empty defaults.

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 both resource types: 'Name a board (by MCU UID) or probe (by ST-Link serial number).' An agent immediately knows what the tool does and which device classes it targets, distinguishing it from sibling tools like stm32_list_probes or stm32_board_info.

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

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

Gives clear conditions: exactly one of mcu_uid or stlink_sn must be provided, and an empty nickname removes the mapping. It also clarifies board nicknames persist across probe swaps while probe nicknames don't, which helps choose the right identifier. No other tool alternatives are named, but none are directly equivalent.

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

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

With no annotations, the description carries the full disclosure burden. It discloses the transport (OpenOCD), the two addressing paths, and that the call returns a confirmation. It omits the traits an agent most needs for a memory mutation: whether the target must be halted, whether the write can corrupt a running program, and whether a bad address fails safely or faults the core.

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 one-line summary, then a paragraph of context, then per-argument docs. Every argument entry adds real information. The 'Returns: Confirmation of the write operation' line is wasted, since an output schema already exists, and the docstring formatting is slightly over-long for a six-parameter tool.

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

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

Because an output schema exists, the thin return description is not a real gap. Parameter-level completeness is excellent. What is missing is the operational envelope for a mutation with no annotations behind it: required debugger/session state, halt requirements, and failure behavior.

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

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

Schema description coverage is 0%, so the description must do all the work, and it does: concrete format examples for address ("0x20000304") and value ("0xFF" or "255"), width enumerated as 8/16/32 with auto-detection from symbol size, symbol examples in both plain and nested C-path form, and the elf_path dependency. This is meaningfully richer than the bare schema titles.

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: writing a value to target memory via OpenOCD, by raw address or ELF-resolved symbol. The two addressing modes and the C-path syntax make the operation unmistakable. It does not name siblings such as stm32_read_memory or live_memory_write, so an agent must infer the boundary between one-shot debugger writes and live session writes.

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 practical selection rules: address and symbol are mutually exclusive, symbol requires elf_path, and an empty probe auto-selects the only connected board. That covers how to pick between the two addressing modes. It never says when to prefer this over live_memory_write or debug_mem, nor what prerequisites (halted core, session state) must hold.

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

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

With no annotations, the description carries the full burden and does well: it discloses that output is one line per expression with address/size/type, explains what the type field means and how to act on it, and notes the struct sub-field expansion convention ('<expr>.<field>'). It omits failure behavior for unresolved symbols and whether the ELF is parsed locally vs on target, which keeps it from 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 purpose, then cleanly separated Args and Returns blocks. The GDB/grep framing earns its place by conveying differentiation, and no sentence is redundant padding.

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

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

For a two-parameter lookup tool with an output schema, everything an agent needs is present: both arguments explained, accepted expression grammar shown, and return shape described including the struct-field convention. Nothing material is missing.

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

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

Schema coverage is 0%, so the description must fully compensate — and it does. It explains elf_path, and critically clarifies that expressions, although typed as a plain string in the schema, accepts either a single expression or a JSON array, with concrete syntax examples covering plain symbols, dot paths, and array indices.

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 — resolve C expressions against the firmware ELF — and frames itself against the status quo it replaces (grepping headers, hand-running GDB), which implicitly separates it from the debug_* and live_memory_* siblings that operate on a live target. An agent can tell what this does without opening the schema.

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

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

It gives a clear usage context ("one-call replacement for grepping headers and hand-running GDB") and routes the agent downstream: 'use [the type] to pick the right live_memory/display treatment', which tells you this is a pre-step before live_memory_read. It stops short of naming an explicit alternative or a when-not-to-use condition, so it lands below the top score.

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