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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds meaningful context: that this is a passive inspection that does not trigger an iteration and that it returns trajectory plus decision state, which is beyond what the annotations convey.

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

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

A single front-loaded sentence that leads with the action and resource and packs the scope constraint and return contents with zero 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?

With no output schema, the description carries the burden of describing returns and does so (pass/fail counts, status, decision). Annotations cover the safety profile. Minor gap: no mention of how the trajectory is scoped or paginated, but complete enough to call correctly.

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

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

Only one optional parameter ('session', default 'default') and schema description coverage is 100%, so the schema fully documents it. The description adds nothing about the parameter, which is the expected baseline when the schema does the work.

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

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

States a specific verb ('Read') and resource ('the acceptance loop's trajectory'), and enumerates the returned data (per-iteration pass/fail counts, status, current decision). The clause 'without running an iteration' functionally distinguishes it from sibling run_acceptance_iteration.

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?

'Without running an iteration' implies this is the non-mutating status-check counterpart to run_acceptance_iteration, giving implied usage. However, it names no alternative explicitly and gives no explicit when-to-use/when-not conditions, so the agent must infer the routing.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety burden is lifted. The description adds meaningful context beyond them: it only works on a halted core, and the overflow verdict is conditional on stack_size/stack_limit being supplied. It does not describe the return payload structure, but with annotations covering behavior this is solid.

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 what is reported, then the defaults/parameter rules, then the positioning statement. Four compact sentences, each doing work; only slight overlap with the schema on parameter behavior.

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

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

With no output schema, the description adequately covers what comes back (used/free bytes plus a verdict) and the precondition (halted core, overflow check needs a size or limit). An agent has enough to invoke it correctly, though return-format detail 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 100%, so the schema already documents all five parameters. The description adds minor value by restating the stack_top default source and the stack_size vs stack_limit relationship, but mostly echoes the schema. Baseline 3 applies.

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

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

States a specific verb+resource ('Reports stack used/free bytes') plus a distinct outcome ('a clear overflow verdict for the halted core'), which separates it from nearby siblings like read_call_stack or diagnose_fault. The closing line 'key tool for diagnosing stack overflows' pins down its niche 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?

Explains the conditional behavior clearly: provide stack_size or stack_limit for the overflow check, otherwise only usage is reported. It also scopes the tool to a 'halted core'. It does not name alternative sibling tools, so it falls short of a 5.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the aggregation rule ('ok is false if ANY step failed') and how data.succeeded/data.failed vs count/total are counted. It does not discuss per-step error isolation or permission needs, keeping it short of a 5.

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

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

Three sentences, front-loaded with the purpose and the latency benefit. Each sentence carries information, though the middle return-semantics sentence is dense and slightly run-on.

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

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

There is no output schema, so the description must carry return semantics, and it does so reasonably (ok flag, succeeded/failed counts, count/total distinction). For a batch meta-tool it is nearly complete; it could say more about partial-failure handling when stop_on_error is false.

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

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

Schema description coverage is 100%, so the baseline is 3. The description still adds meaning by clarifying that session applies to every step ('Pass session to run every step against a named debug session'), and implies steps are an ordered sequence. stop_on_error is left to the schema.

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

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

States a specific verb+resource ('Runs several tool calls in ONE round trip') and reinforces it with a concrete example (read registers + backtrace + several variables). It is clearly a batching/meta-tool, but it never names the single-call sibling (call/call_read) it contrasts against, so differentiation is implicit rather than explicit.

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

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

Gives clear context for when to reach for it ('the fastest way to do a sequence of operations... without per-call latency') with an illustrative use case. It does not state any when-not condition or explicitly point to the alternative single-call tool for one-off invocations.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only the argument signatures, with no mention of permissions, session scoping behavior, or what a 'list' returns; it does not contradict the annotations but adds little beyond them.

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

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

Extremely compact and front-loaded: one sentence plus a signature-style breakdown of each action. It is dense but wastes nothing; the terse backus-naur-like notation is the only mild readability cost.

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

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

For an 8-parameter, no-output-schema mutation tool, the description covers all four actions but omits any statement of return behavior (notably for 'list'), does not mention the optional 'session' parameter, and gives no indication of how set/delete affect program state. Adequate but with clear gaps.

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

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

Schema description coverage is 100% and all 8 parameters are documented in the schema itself, so the baseline of 3 applies. The description's signature notation mirrors the schema (location, condition, temporary, ignore_count, access_type) without adding format or constraint detail beyond it.

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

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

The description states a specific resource (breakpoints/watchpoints) and enumerates the four operations (set/delete/list/watch) with their key arguments, so an agent immediately knows this tool manages debug breakpoints. It does not explicitly distinguish itself from similarly-purposed siblings like run_to_line or debug_until, which also stop execution, keeping it 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 each mode applies (set vs delete vs list vs watch), but there is no explicit when-to-use or when-not guidance and no routing to alternatives such as run_to_line or run_to_line-style stop helpers. Usage is inferable but not stated.

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

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

Annotations already declare destructiveHint=true, non-idempotent, open-world, so the safety profile is covered. The description adds useful artifact context (Keil emits .axf usable by debug tools) and states the return payload (exit code, success flag, log tail), but never explains what the destructive hint means (overwritten build outputs) or permission needs.

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

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

Three front-loaded sentences, purpose first, with no filler. The .axf/debug-tools sentence is slightly tangential but earns its place by linking the build artifact to downstream tools.

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 12 parameters and no output schema, the description does the needed work by naming the toolchains and describing the return values. Only the meaning of the destructive annotation and any required setup are left unaddressed.

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

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

Schema description coverage is 100%, so every parameter including the kind enum is already documented. The description adds only that Keil produces .axf and names the toolchains; it does not add syntax or defaults beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (builds) and resource (firmware) plus the four supported toolchains, and it is clearly distinct from sibling flash_firmware (build vs deploy). An agent can tell exactly 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?

"so the AI can rebuild after a fix" gives an implied usage scenario, but there is no explicit when-not guidance or named alternative (e.g., build_firmware vs flash_firmware sequencing). Usage is inferable rather than 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?

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the risk profile is largely covered structurally. The description adds the delegation semantics ('Returns that tool's result') but does not warn that side effects depend entirely on the invoked tool or discuss auth/rate limits, so it adds only moderate context.

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

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

One tight paragraph, front-loaded with the capability and immediately followed by the condition and a concrete example. Every sentence earns its place with no filler.

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

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

With no output schema, the description usefully notes that it returns the invoked tool's result, closing the biggest information gap. For a generic dispatcher the coverage is strong, though it could say more about how errors or destructive side effects from the delegated tool surface.

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

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

Schema description coverage is 100%, so tool, args and session are all documented in the schema itself, which sets the baseline at 3. The description reinforces usage with a call(tool=..., args={...}) example but adds no syntax, format, or constraint detail beyond what the schema provides.

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 (invoke) and resource (ANY stm32-gdb-mcp tool by name) and makes the dispatch role explicit, which cleanly separates it from every concrete sibling like start_debug_session or read_memory. An agent immediately understands this is a meta-call escape hatch rather than a domain operation.

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 the selecting condition explicitly — use it when the target tool is 'NOT in your current tool list' because clients with tool-count limits may hide some — and provides a concrete example with start_debug_session. It stops short of stating when to prefer a directly-listed sibling over this generic path, which is the only gap.

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

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

Annotations declare readOnlyHint/idempotent/destructive=false, but the description adds substantial context beyond them: it avoids an approval prompt, the gate is per-ACTION not per-tool, and a refusal names the actions it would accept. These are genuine operational behaviors an agent could not infer from the annotations or schema.

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

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

Front-loaded with the key distinction ('Like call, but restricted to tools that only READ state'), and every sentence carries a distinct piece of information (prompt avoidance, per-action gate, refusal behavior). It runs slightly long and the per-action nuance takes a few clauses to land, 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?

For a gateway/dispatch tool with no output schema, the description covers purpose, when to prefer it, the subtle per-action eligibility rule, and error/refusal behavior. An agent has everything needed to invoke it correctly and interpret a rejection.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value by demonstrating the tool/args relationship with concrete examples (args={} and args={'action':'get'}). It does not clarify the optional 'session' parameter, which the schema already documents, so it stops short of a 5.

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

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

States a specific capability (invoke read-only tools) and explicitly contrasts itself with the sibling 'call', which can reach anything. The agent can distinguish the two without opening either schema, and the 'restricted to tools that only READ state' clause pins down the exact scope.

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 when-to-use (hidden read-only tools), when-not-to-use ('Refuses anything that writes; use call for those'), and names the alternative 'call'. The per-action guidance ('get' works, 'set' does not) tells the agent exactly which invocations are eligible, not just which tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds real behavioral value beyond that by disclosing the exact payload composition and the decoding (symbol-resolved backtrace/locals), plus the implicit requirement that the target be halted. It stops short of describing formatting, truncation, or pagination.

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

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

Two compact sentences with zero filler, front-loaded with the 'where am I' framing so the agent immediately grasps the intent. Every clause earns its place by naming a concrete returned artifact.

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

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

With no output schema, the description carries the burden of describing the return value, and it does so concretely (registers, PC/LR/SP, backtrace, locals). Combined with annotations covering safety and idempotency, an agent has enough to call it correctly; only edge cases like a non-halted target or empty stack are 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?

There is a single optional parameter with 100% schema description coverage ('Optional debug-session name. Omit for the default target.'), so the schema fully documents it. The description adds no parameter-level detail, which is the correct baseline when the schema does the work.

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

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

The description states a specific verb+resource ('One-call "where am I"') and enumerates exactly what it returns: decoded core registers, a PC/LR/SP summary, a decoded backtrace, and innermost-frame locals. It reads as an aggregate snapshot tool, but it does not name the sibling tools it consolidates (read_call_stack, read_registers, analyze_stack), so differentiation is implicit rather than explicit.

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

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

It gives a usage context ('the fastest way to get full halted context') that implies you call it when you want a complete halted picture in one shot. However, it names no alternatives and no exclusions, so an agent must infer when a narrower sibling like read_call_stack or read_registers is preferable.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the safety profile is largely covered. The parenthetical 'keeps the run-id' adds useful scope detail beyond annotations, clarifying what survives the clear, but the description says nothing about what happens to the journal content, recoverability, or auth needs.

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

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

One short sentence that front-loads the action and appends the key constraint. No wasted words; every clause earns its place.

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

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

For a simple one-parameter tool with no output schema and annotations covering safety, the description is adequate but thin. It omits when to use it and any notion of the effect on the journal content, leaving minor gaps for an agent to resolve.

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

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

Schema coverage is 100% and the single optional 'session' parameter is fully documented in the schema, so the baseline is 3. The description adds no detail about the parameter (e.g., default vs named session behavior beyond what the schema states).

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

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

Clear specific verb (clears) plus resource (session journal) and scope qualifier (keeps the run-id), which lets an agent distinguish it from siblings like get_session, session_diagnostics, or recover_session. It does not explicitly name any sibling, so 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?

The description gives no when-to-use context, no prerequisites, and no alternatives (e.g., how this differs from recover_session or session_diagnostics). The agent must infer the scenario in which clearing the journal is appropriate.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, and the description usefully adds that a close tears down both the GDB client and server. It does not say what happens if the session does not exist, whether the teardown is recoverable, or what a caller should expect afterwards.

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

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

One front-loaded sentence with zero filler; the verb, resource, and effect are all in the first clause.

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

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

For a mutation tool with no output schema and no annotations beyond safety hints, the description covers the operation's effect but omits error/failure behavior and the post-close state of the session, leaving meaningful gaps.

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

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

Schema coverage is 100%, with both 'session' and 'session_id' fully documented in the schema itself. The description adds no parameter detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ("Closes a named debug session") and adds the concrete effect of tearing down the GDB client and server. It does not, however, distinguish itself from the very similar sibling 'stop_debug_session', so sibling differentiation is missing.

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

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

No guidance on when to close versus stop, recover, or get a session, and no stated prerequisites. The only conditional hint (omit the name for the default target) lives in the schema, not 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?

Annotations declare the mutation profile (readOnlyHint=false, destructiveHint=true), and the description adds genuinely useful context beyond them: it explains the register mechanism and the resulting target behavior (watchdog freeze while the core is halted), which clarifies what the side effect actually is. It does not, however, say whether the freeze is reverted on session close or how to undo 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?

Two tightly packed sentences, front-loaded with the action and rationale, with zero filler. The trailing default-resolution note is short and useful.

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

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

Given no output schema and a four-parameter mutation tool whose annotations already carry the safety profile, the description covers purpose, mechanism, consequence and the family default adequately. It stops short of describing the reversion/unfreeze story, which would matter for a tool that alters target watchdog 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 100%, so the baseline is 3. The description adds one meaningful default-resolution rule not in the schema: 'Family is taken from the debug profile MCU if omitted,' which tells the agent it can safely omit family. It adds nothing further about the peripherals list syntax or session semantics.

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

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

States a precise verb and resource ('Freezes peripherals (IWDG, WWDG, RTC, timers)') and names the exact mechanism (DBGMCU freeze registers) plus the concrete outcome ('watchdog cannot reset the target out from under the debugger'). An agent can immediately tell this apart from generic siblings like halt_execution or debug_config.

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 tool's purpose implies its usage scenario (halting debugging sessions where watchdogs would otherwise reset the target), and the 'apply=false' dry-run path hints at a safe pre-check workflow. However, it never states when to reach for this versus siblings such as debug_config or debug_profile, nor any exclusions or prerequisites.

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

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

Annotations cover the safety profile (non-destructive, non-readonly), and the description adds a valuable behavioral trait beyond them: calling while already running yields already_running rather than an error. It does not describe what happens at the breakpoint stop or return format, but adds real context.

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

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

Two tight sentences, front-loaded with the core action and termination condition, followed by the useful edge-case behavior. No filler.

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

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

For a simple execution-control tool with no output schema, the description covers action, scope, and the key edge case (already_running). It could mention interaction with breakpoints/stops, but is nearly complete.

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

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

Schema coverage is 100% and the single optional 'session' parameter is fully documented in the schema (omit for default target). The description adds no parameter-level meaning beyond that, so baseline 3 applies.

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

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

States a specific verb (resumes execution), the resource (target device), and the termination condition (until the next breakpoint). This distinguishes it from step, run_for_duration, and run_to_line without needing to name them.

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

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

Gives a concrete when-to-use pattern ('make sure it is running' is expressible) and clarifies the already-running case. It does not name or exclude alternatives like step or run_for_duration, 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?

Annotations already disclose read-only=false, idempotent=false, and destructive=false, so the safety profile is partially covered. The description adds nothing beyond that: it doesn't explain that capture writes a core file to 'path' while load reads from it (a key semantic difference), whether the target is halted, or what the session parameter affects. Given the mutation and non-idempotent hints, this is a notable gap.

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

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

It is a single terse line with the purpose front-loaded and zero filler. The action/path shorthand borders on cryptic, but nothing is wasted, so it is efficient if minimal.

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, dual-mode operation with no output schema, the description omits what a core dump is, what capture does to the running target, how session interacts, and what the caller should expect back. The rich schema covers parameters but the behavioral context an agent needs to invoke this safely is largely missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The 'action=capture(path) | load(path)' notation restates the required parameter pairing already expressed by the oneOf schema and adds no format, default, or meaning beyond it; the crucial fact that 'path' is an output for capture but an input for load is left to the schema.

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

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

The description states a specific verb and resource ('Core-dump capture / load') and spells out the two operational modes via action values, so an agent immediately knows the tool captures or loads core dumps. It stops short of distinguishing this tool from near-neighbors like capture_state or snapshot, so it does not reach a 5.

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

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

There is no when-to-use or when-not guidance: nothing says when to capture versus load, whether a debug session must exist first, or which siblings are alternatives. The action notation shows the mechanics of invocation but gives no contextual selection criteria.

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

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

Annotations only declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false); the description adds little beyond that and never says save overwrites the destination file, whether writes are reversible, or what load/validate return. Worse, it labels the file '.json' while the schema describes 'Path to a YAML debug config file', a contradiction that can actively mislead an agent about the format.

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

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

Two tight fragments, front-loaded with the resource and then the operations; nothing is padded. The only issue is accuracy, not verbosity.

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

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

With no output schema, the description should explain what load and validate yield, but says nothing about return values, error behavior, or the role of the 'session' parameter. For a mutating, file-writing tool this leaves a significant gap for an agent to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, and the oneOf already encodes which parameters each action requires. The inline signatures (load(path), save(path,config), validate(config)) restate that mapping compactly but add no format or constraint detail, and the description omits the optional 'session' parameter entirely.

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

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

The description names a specific resource (debug-config file) and enumerates the three concrete operations (load/save/validate) with their argument signatures, so an agent can tell what the tool does at a glance. It does not, however, differentiate itself from any sibling tool by name or scope.

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?

Listing action=load(path) | save(path,config) | validate(config) implies which operation to pick for a given need, which is better than nothing, but there is no explicit when-to-use guidance, no prerequisites (e.g. session context), and no routing to alternatives.

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

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

Goes well beyond the annotations by disclosing top-level-only merge semantics, whole-block replacement of nested blocks, the concrete hub example of accidental data loss, and that the profile is in-memory only and empty again after a server restart. That last point is critical volatility context the annotations (readOnly=false, destructive=false, idempotent=false) do not convey.

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

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

Dense and front-loaded, opening with the resource and actions before explaining merge semantics and the lifetime caveat. The hub example earns its place, though the 'replace is the only way to remove' point is restated, adding mild redundancy.

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

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

For a no-output-schema tool it does state the return value ('full resulting profile') and covers the tricky merge/volatility behavior thoroughly. The gaps are the unexplained optional parameters (notably session) against 13 params at 31% coverage, so it is strong but not complete.

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

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

With only 31% schema description coverage, the description carries much of the load: it enumerates the set-able fields and richly explains merge and hub. However, several parameters (session, board, notes, server_type/server_args) get no meaning beyond their names, so compensation is partial.

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 the resource (active debug profile) and the two operations (action=get | set) with the set-field list, so an agent knows it reads/writes the session's debug configuration. Sibling differentiation is weak, though: it does not explicitly separate itself from adjacent tools like debug_config, hub, or get_session.

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 conditional guidance for the merge flag: enable it to add one nested key without dropping identity, leave it off to replace and thereby remove a stale entry. This is real when-to-use reasoning, though it stays at the parameter level and names no alternative tool for configuration.

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

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

Annotations declare safety profile (readOnly=false, destructive=false, idempotent=false), so the bar is lower. The description adds real value: it discloses the return payload (stop event, decoded backtrace, innermost-frame locals) and the temporary/conditional breakpoint behavior, which annotations alone don't convey.

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

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

Two sentences, front-loaded with the action, and the collapse rationale is a tight second clause. No 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?

With no output schema, the description correctly summarizes the return values (stop event, backtrace, locals). Reasonably complete for a repro tool; minor gap on error/timeout outcomes but not blocking.

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

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

Schema coverage is 100%, so the schema already documents all six parameters. The description reinforces 'optional conditional/temporary breakpoint' but adds little syntax or default detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb chain (set breakpoint, run, return stop event) on a specific resource (a location) and explicitly names what it collapses. An agent can distinguish it from breakpoint/run/read_call_stack siblings immediately.

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?

Frames usage as a 'one-call repro step' and names the three sibling operations it replaces (set_breakpoint + run + read frame/vars), giving clear context for selection. It does not explicitly exclude alternatives like run_to_line or run_and_wait, keeping it below a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully discloses the decoded output shape (bitfield names, enumerated values), but omits the key behavioral prerequisite that SVD data must be loaded for decoding to succeed, and says nothing about failure behavior when it is not.

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

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

A single front-loaded sentence with no filler or repetition. It is appropriately sized for the tool's simplicity, though it could have spent a few more words on the load_svd dependency.

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

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

With no output schema, the description does convey what the return value looks like (bitfields, enums), which is valuable. But for a tool sitting in a debug session, the missing mention of the SVD prerequisite and the unresolved overlap with read_peripheral_register leave meaningful gaps.

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

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

Schema description coverage is 100% and the description adds no parameter-level detail beyond what the schema already documents (peripheral, register, optional session). Baseline 3 is appropriate since the schema carries the parameter semantics.

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 ('Reads and decodes a peripheral register') and adds the distinguishing detail that results carry SVD bitfield names and enumerated values, so it is clearly richer than a raw read. However, it never references the near-identical sibling 'read_peripheral_register', so an agent cannot tell the two apart from the description alone.

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

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

No when-to-use guidance, no prerequisites, and no named alternatives are given. The description does not say when decoding is preferable to the sibling read_peripheral_register, nor that an SVD must be loaded (via load_svd) before decoding works.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds that it can read either a loaded spec or a previously produced verdict, but doesn't state what happens if no spec is loaded or which verdict (last run only?) is returned.

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

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

Two tight sentences, front-loaded with the core action, then the mode breakdown. No filler; every clause carries information.

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

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

With no output schema, the description usefully describes the shape of each mode's result, and the schema covers the session parameter and its default. Only minor gaps remain, such as behavior when no spec is loaded, but the definition is sufficient to call the tool correctly.

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

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

Schema coverage is 100% and the schema lists the allowed 'what' values, but the description goes further by explaining what each value returns (summary = name + check counts, checks = full list, last_result = the run_acceptance report). That is genuine meaning beyond the schema's bare enum list.

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

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

States a specific verb (Read) and resource (the loaded AcceptanceSpec or the last verdict), which immediately distinguishes it from load_acceptance (which loads a spec) and run_acceptance (which executes). It doesn't explicitly call out the siblings it is not, but the read-only framing 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?

Usage is implied: you call it to view the loaded spec or the most recent verdict. However there is no explicit when-to-use guidance or routing to alternatives (e.g. 'use this instead of run_acceptance when you only want to inspect'), so the agent must infer the context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds the data-provenance fact (content originates from import_netlist), but nothing about session scoping, error behavior when no netlist was imported, or output size; with annotations carrying the load, a 3 is appropriate.

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

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

A single dense sentence, front-loaded with the action and data source, then the option list. Slightly run-on, but every clause carries information and 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?

No output schema exists, and the description compensates by describing what each view returns; annotations cover the safety profile and the schema covers both parameters. For a read-only describe tool, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely enriches the terse "summary|pins|nets|power|peripherals" enum by explaining what each view returns (e.g. summary = MCU + peripherals + counts, power = power/ground nets). The session parameter is left to the schema.

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

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

Specific verb ("Read") plus a specific resource ("the BoardDescription imported by import_netlist"), and it enumerates the five selectable views. An agent can tell this apart from validate_board, inspect_project, or describe_framework 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?

It states the precondition clearly (this reads what import_netlist produced) and explains what each "what" value yields, which is the main selection decision an agent faces. It never names an alternative tool or a when-not condition, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: the plan is 'synthesized', it must follow design_framework, and the 'unresolved' view exposes TODO holes needing target data or a design decision.

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

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

Front-loaded with the verb and resource, then the selectors, then the prerequisite last. Dense with parentheticals but every clause carries information; no filler sentences.

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

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

No output schema exists, so the description carries the return-value burden and does so by enumerating the report sections. It omits what happens if design_framework was never run (empty result vs error), which is the only notable gap for a two-parameter read tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining what each 'what' selector actually returns (summary = mcu + clocks + peripherals, gpio = per-pin config, peripherals = init blocks, unresolved = TODO holes), which is meaning the flat enum string in the schema does not convey.

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

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

Specific verb ('Read') plus a specific resource ('the synthesized FrameworkPlan'), and it enumerates the distinct views (summary, clocks, gpio, peripherals, init_order, unresolved) so an agent knows exactly what it gets. It differentiates itself from design_framework by naming it as a prerequisite, though it never distinguishes itself from render_framework.

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?

'Run design_framework first' gives an explicit ordering prerequisite, which is real usage context that prevents calling it before a plan exists. It stops short of stating when-not to use it or naming render_framework as an alternative for visual output.

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?

Far beyond the annotations, it discloses auto-fill of mandatory .Init members with HAL defaults, derivation from the netlist (UART flow control, SPI NSS), explicit/derived/default tagging per field, AF auto-derivation from a pin DB, and precedence rules (explicit af_map overrides DB). It also states the safety-relevant policy that ambiguous fields are surfaced as unresolved rather than guessed.

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

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

The purpose and output list are front-loaded in the first sentence, and each following sentence carries distinct information (parameter shapes, defaults, derivation, precedence). It is dense and slightly 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 five-parameter, nested-object tool with no output schema, the description covers purpose, prerequisites, parameter semantics, behavioral rules, and the shape of the produced plan (clocks, muxing, init blocks in dependency order). 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 100%, so the schema already documents all five parameters; the baseline is 3. The description adds genuine value on top, documenting the design and af_map shapes, the STM32_GDB_MCP_PIN_DB env fallback for db_path, and the merge/precedence semantics of from_spec.

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

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

The description names a specific verb (Synthesize), resource (FrameworkPlan / Pillar D), and concrete outputs (clocks to enable, pin muxing, peripheral init blocks in dependency order), so an agent knows exactly what the tool produces. It also ties itself to the sibling import_netlist as a prerequisite, anchoring it in the 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?

It clearly states the precondition ('Import a netlist first') and explains when to supply design/af_map versus relying on auto-fill, and how from_spec merges with explicit design. It does not explicitly contrast with sibling tools like describe_framework or render_framework, so routing between those 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds a concrete behavioral trait beyond annotations: it preserves serial numbers so identical probes are not collapsed, which is important for identifying multiple devices. It does not cover return format or error cases.

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

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

Two tightly written sentences, front-loaded with the action and resource, with no filler. Every clause carries information.

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

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

For a simple detection tool with one optional parameter and no output schema, the description conveys the essential purpose and a key output guarantee (serial-number preservation). It could say more about the returned format (e.g., list of serials/names), but the annotation set covers safety and the tool's scope is clear.

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

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

Schema coverage is 100% and the single optional 'session' parameter is documented in the schema ('Optional debug-session name. Omit for the default target.'). The description adds no additional meaning about the parameter. Baseline 3.

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

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

States a specific verb ('Lists') and resource ('physical ST-Link, J-Link, and CMSIS-DAP probes currently connected over USB'), and adds the serial-number preservation guarantee that differentiates it from a generic list tool. The scope is unambiguous and no sibling performs the same action.

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

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

Provides no when-to-use guidance, prerequisites, or alternatives. It does not say whether to call this before starting a debug session or how it relates to tools like start_debug_session or self_check. Implied usage only.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and closed-world behavior, so the safety profile is covered. The description adds session scoping but does not describe return shape, failure behavior, or prerequisites beyond that.

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

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

A single front-loaded sentence with no filler. It communicates the essential purpose immediately.

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

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

For a simple detection tool, the purpose plus schema and annotations are nearly sufficient; the boolean-style result is implied by 'detects whether.' However, it does not explicitly state the return form or behavior when no session exists, leaving minor gaps.

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

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

Schema description coverage is 100%, and the sole optional session parameter is fully documented in the schema. The description adds no extra meaning beyond what the schema already provides, so the baseline is 3.

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

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

States a specific verb and resource: detect FreeRTOS symbol availability. The scope, 'current GDB session,' makes it clearly distinct from siblings such as read_freertos or session diagnostics.

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

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

The description says what the tool does but not when to use it instead of alternatives like read_freertos or detect_probe. There is no explicit when-to-use, when-not-to-use, or prerequisite guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds that the output is an interpreted result ('likely fault causes') rather than raw register dumps, which is genuinely useful, but it omits any precondition about the target being halted in a fault state and does not describe what is 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?

A single front-loaded sentence with zero filler; every word (verb, resource family, output type) earns its place.

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

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

With no output schema, the description must carry the return-value burden, and it only gestures at the output ('likely fault causes'). It also omits the crucial precondition that a fault condition exists to diagnose. Adequate but with clear gaps for a diagnostic tool.

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

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

Schema description coverage is 100% for the single optional 'session' parameter, so the schema already explains the omit-for-default behavior. The description adds no additional semantics about the session parameter, making the baseline 3 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 pair (reads and decodes) and a specific resource (Cortex-M fault registers), plus the derived output (likely fault causes). The scope is clear, but it does not distinguish itself from close siblings such as reconstruct_fault_context or coredump, so an agent cannot route between them from the text alone.

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

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

There is no when-to-use guidance, no prerequisite (e.g. target halted due to a fault), and no mention of alternatives like reconstruct_fault_context or session_diagnostics. The agent is left to infer the diagnostic context entirely.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds default values ($pc, N) that are already in the schema, but no behavioral context beyond what structured fields provide.

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

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

A single, front-loaded sentence with zero waste. It states the action, count, and default location efficiently, though it could benefit from marginally more structure to aid selection among siblings.

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

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

For a simple read-only tool whose annotations cover safety and whose schema is fully described, the description is minimally adequate. However, it lacks any usage context or differentiation from many similar debug siblings, leaving selection ambiguous.

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

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

Schema description coverage is 100%, so the schema fully documents all three parameters. The description repeats the default location ($pc) and instruction count concept, adding no new meaning. Baseline 3 is appropriate when the schema carries the explanatory load.

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 ('Disassembles') and resource ('instructions') with scope ('N instructions at a location'). Clear what the tool does, but does not distinguish itself from sibling debug tools like step, read_memory, or read_call_stack.

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

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

Provides no when-to-use guidance, no alternatives, and no prerequisites. The agent is left to infer context from the name alone among many debug-oriented siblings.

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

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

Annotations declare write (readOnlyHint=false), non-destructive, non-idempotent, non-open-world, so the safety profile is already covered. The description adds genuine context beyond them: that it produces one self-contained artifact tied to the run-id and can optionally embed a snapshot and a coredump. It omits any note on disk/permission requirements or cost of capturing a coredump.

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

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

A single dense sentence that front-loads the action and artifact, then qualifies the optional components. Every phrase earns its place with no redundancy.

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

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

For a write tool with no output schema, the description adequately explains what is produced and where it is anchored (run-id). It could say more about what the report enables next or any preconditions, but nothing critical for calling it is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including the 'requires a halted target' constraint on include_snapshot. The description confirms the optional snapshot/coredump nature but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Writes') and resource ('a single self-contained JSON report') and enumerates the composite content (journal + metrics + profile, optionally snapshot and coredump), which distinguishes it from siblings like snapshot, coredump, and session_diagnostics. It does not explicitly name a sibling it replaces, 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 clause 'so a bug session is fully reproducible and shareable from one artifact' implies the use case (packaging a bug session for sharing), but there is no explicit when-to-use vs when-not guidance and no named alternative such as snapshot or coredump for narrower needs.

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

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

Annotations declare readOnlyHint=false, idempotentHint=false, so the agent knows this is not a pure read, yet the description never explains what state it mutates or what permissions/conditions are required. It does disclose one meaningful behavioral fact beyond the annotations: compare 'runs action between the two captures', i.e. it can drive execution (consistent with the step/continue/halt enum), which is genuinely valuable context.

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

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

Front-loaded with the purpose, then compressed into pipe-delimited signatures; every clause carries content. It is dense and telegraphic rather than verbose, though the trailing 'compare runs action between the two captures' restates what the signature already implies.

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 tool with nested objects and no output schema, the description covers action, assertions, table, and expressions but omits the 'session' parameter entirely and says nothing about what results are returned. Adequate for the main action flows, incomplete for the full surface.

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 ~80% schema coverage the baseline is 3, and the description earns an extra point by spelling out the per-action argument shapes: assertions=[{expression,expected[,operator]}], table={index_range,columns}, and the action list for compare. This maps parameters to intent more directly than the schema's raw object definitions.

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 ('Evaluate C/GDB expressions') and enumerates the three operations it actually performs (assert/capture/compare), so its scope is legible. However, it never distinguishes itself from sibling evaluation tools like read_variable, read_memory, or read_registers, leaving the agent to infer the boundary.

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

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

The action signatures implicitly communicate what each mode is for (assert compares to expected, capture snapshots, compare diffs two captures), which is usable guidance. But there is no explicit when-to-use/when-not statement and no routing to alternative tools for plain variable reads.

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

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

Annotations already flag the tool as destructive, non-read-only, and non-idempotent. The description adds substantial context: the internal sequence (load symbols, reset-halt, temporary breakpoint, run to entry, return decoded stop context) and session-pinning logic, including that hub_channel is ignored when a session is already live.

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

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

Two sentences, front-loaded with the core operation. The second sentence is dense but delivers non-redundant session behavior; no wasted words, though a more structured presentation could improve readability.

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

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

For a complex, multi-step tool with no output schema, the description covers the purpose, action sequence, session selection, and return value ('decoded stop context'). All required parameters are documented in the schema, and nothing critical for correct invocation appears missing.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters, including defaults for run_to ('main') and hub_channel behavior. The description reinforces the default entry point and session logic but does not add syntax, format, or examples beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description states a specific composite verb+resource ('one-call bring-up: flash an ELF... reset-halt, set breakpoint, run...') and explicitly frames it as a single call that replaces multiple steps. It distinguishes itself from single-operation siblings like flash_firmware or reset_target by emphasizing the 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?

It gives a clear usage context: with hub_channel or usb_location and no session running, it starts a session pinned to that probe, and it does not disconnect other probes. However, it does not explicitly name alternatives (e.g., call flash_firmware then reset_target) or state when not to use this tool, so guidance falls short of the top score.

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

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

Annotations already declare destructive=true and idempotent=false, so the safety profile is covered. The description adds real context beyond that: the driver-boundary rounding behavior, the deliberate absence of a mass-erase default, and the recovery framing. It does not describe failure/abort behavior or what the call returns.

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

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

Three sentences, front-loaded with the core action, then use case, then the key constraint. The OpenOCD parenthetical adds precision without padding; 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?

For a destructive, non-idempotent tool with no output schema and annotations covering safety, the description supplies purpose, trigger scenarios, required-arg expectations, and boundary/verify behavior. The only gap is the absence of any statement about the outcome or failure modes after erasing, but the verify parameter partially compensates.

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

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

Schema description coverage is 100%, so the schema already documents length/address rounding, verify, session, and sector_size. The description only reinforces that both address and length are mandatory and explains the design rationale ('deliberately no mass-erase default'); it adds no per-parameter meaning beyond the schema, so baseline 3 applies.

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

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

Precise verb+resource: 'Erases a flash range on the target,' reconciled with the OpenOCD 'flash erase_address pad' primitive. The scope ('rounded out to the driver's erase-sector boundaries,' 'no mass-erase default') is distinct from flash_firmware/write_memory, which write rather than erase an arbitrary range.

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 when-to-use context: 'The recovery tool for a board that will not boot,' with three concrete scenarios (corrupt OTA journal, stale boot descriptor, half-written image). It gives strong positive guidance but does not explicitly name an alternative tool or an exclusion condition relative to siblings like flash_firmware.

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

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

Annotations already flag destructiveHint=true and non-idempotence; the description adds substantial behavior beyond that: default post-flash reset-and-run, the option to leave the target halted, and a named refusal mode (elf_layout_unsupported) with the workaround. It stops short of describing timing, session state effects, or how a failure leaves 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 core action and each subsequent sentence carries new information (formats, default run, opt-out, refusal workaround). Slightly dense and dependent on parenthetical device-tool jargon, but no wasted sentences.

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 destructive, non-idempotent single-parameter-ish operation with no output schema, the description covers the action, the default side effect, the opt-out, and one notable failure mode with an alternative. Adequate without over-explaining return values.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: why reset_run=false matters (breakpoint setup), what the omitted session defaults to, and which formats file_path accepts. Useful context without re-documenting syntax.

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 (Flashes) and resource (compiled firmware binary) plus supported input formats (.elf/.axf). An agent can immediately tell this is the flash-and-execute path rather than the sibling flash_erase or verify_flash 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?

Gives clear conditions for the reset_run=false variant ('to set breakpoints before the firmware starts') and for using a fromelf BIN instead of an AXF. It does not explicitly contrast itself with the sibling flash_and_run, so routing between those two is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful semantic that level 0 is the innermost frame, but says nothing about return format or how 'source/variables' continue from current context.

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

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

Two dense, front-loaded sentences with zero filler. The action/param map is compressed into a single readable line and the key semantic constraint is appended last.

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 6 fully documented params and a oneOf schema, and no output schema required, the description covers the shape of all three operations adequately. It stops short of explaining what each action returns, but the schema carries the rest.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real value by mapping which parameters belong to which action (select→level, source→location/count, variables→level/include_raw), which is not obvious from the oneOf structure alone. The 'level 0 is innermost' note also clarifies the most important enum-adjacent parameter.

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 resource (stack frames) and enumerates the three operations (select/source/variables), so an agent knows this is stack-frame navigation rather than a stack dump. It does not explicitly differentiate from close siblings like read_call_stack or analyze_stack, which would push it higher.

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 breakdown implies when each operation applies (choose level, view source, inspect variables), but there is no explicit guidance on when to prefer this tool over read_call_stack, analyze_stack, or step. Usage is inferable but not stated.

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

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

Annotations already establish readOnly=true, idempotent=true, non-destructive=false, so the safety profile is covered. The description adds substantive value by detailing what each view returns (args/ok/summary/duration for journal, per-tool counts and durations for metrics), which is meaningful behavioral context beyond the annotations.

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

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

One front-loaded sentence with the resource and view breakdown, no filler. It is dense and readable, though the parenthetical enumeration is heavy enough that a slightly more structured form might scan faster.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so for all three views. Remaining gaps (pagination/ordering beyond 'most recent N', session default behavior) are minor for a read-only introspection tool.

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

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

Schema coverage is 100%, so the enum values and limit semantics are already documented. The description nonetheless enriches the view parameter by explaining the distinct content of each mode and notes that limit applies specifically to journal, adding meaning the bare schema descriptions do not convey.

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

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

States a specific verb (returns) and resource (this session's record) and immediately enumerates the three views with what each yields. An agent can distinguish it from list_sessions (which enumerates sessions rather than reading one session's contents) 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?

The view names imply which one to pick for a given goal, but the description never states when to use get_session versus alternatives like session_diagnostics, list_sessions, or export_debug_report, nor when a view is preferable. Usage 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?

Annotations already declare this is a non-read-only, non-destructive, non-idempotent operation, covering the safety profile. The description adds nothing beyond the verb: it does not say whether execution state is preserved, whether the halt is resumable via continue_execution, or how it interacts with breakpoints or running scenarios. It does not contradict the annotations.

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

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

A single short sentence with no filler and the action front-loaded. It is appropriately sized, though it is thin rather than efficient—the brevity comes partly from omission of useful context.

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

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

For a simple one-optional-parameter mutation with annotations present and no output schema, the description is minimally adequate. It still leaves the agent unsure about resumability and the operational effect of halting relative to sibling stop/reset tools, which a one-line addition could resolve.

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

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

With a single optional parameter and 100% schema description coverage, the schema already fully explains the session argument ('Omit for the default target'). The description adds no extra meaning, which is the expected baseline when the schema carries the parameter burden.

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 action (interrupts/halts) on a specific resource (target device execution), so the core purpose is unambiguous. However, it does nothing to distinguish itself from closely related siblings like continue_execution, stop_debug_session, reset_target, or wait_for_stop, leaving the agent to infer the boundary.

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

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

There is no guidance on when to use this versus alternatives such as stop_debug_session (session teardown) or reset_target (restart). No prerequisites, no follow-up guidance (e.g., whether continue_execution can resume afterward), and no exclusions are given.

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

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

Annotations already flag destructiveHint=true / not readOnly, so the bar is lower, yet the description still adds real behavioral context: cutting port power cold-boots the board and un-enumerates its probe, the dashboard is a read-only live page on 127.0.0.1 whose URL is returned, and 'confirm' guards power/data cuts when a session is live. It stops short of stating permission/rate-limit or expected failure behavior.

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

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

Front-loads the tool's identity, then compresses all seven action signatures into one dense line, then adds two short behavioral sentences. Nearly every clause carries information, though the signature list is terse enough to require careful reading.

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

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

For a 7-action, 16-parameter mutation tool with no output schema, the description covers the action set, key defaults (channel mapping, state values), the dashboard return value, and the destructive cold-boot consequence. It omits returns for most non-dashboard actions and any sequencing guidance, so it is strong but not exhaustive.

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

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

Schema coverage is 100%, so every parameter is already documented in the schema, and the inline action(...) signatures largely restate that mapping. The description does reinforce that channel is 1-based and defaults to the session's mapped channel, but adds little syntax or default information beyond what the schema already carries. Baseline 3 applies.

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

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

Opens with a concrete verb+resource scoping ('Programmable USB hub: per-port power, USB2 data lines, cold boot, and V/I sampling') and then enumerates the seven actions with their signatures, so an agent immediately knows this is a hardware power/data control surface rather than a debug-inspection tool. It is clearly distinguishable from the surrounding debug/flash 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?

The action list implies the usage of each operation, and the note that 'Removing port power cold-boots that board and un-enumerates its probe' hints at when power cycling is appropriate. But there is no explicit when-to-use vs when-not-to-use guidance, no ordering advice among actions (e.g., discover before power), and no pointer to alternatives.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false; the description justifies the write by disclosing that 'the result is stored on the session', which explains the mutation and how to retrieve it. It also notes the optional pin-capability DB enables physical pin resolution, adding context beyond the annotations, though it does not discuss failure behavior or idempotency.

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

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

Three tightly packed sentences with zero filler; the core purpose and output shape come first, then input options, then the read-view pointer. Every sentence 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?

With no output schema, the description compensates by enumerating the return structure (MCU part/family/line, pin map, power nets) and pointing to describe_board for views, and it covers the session-storage side effect. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value: it frames path/text as mutually exclusive inputs and explains that db_path (or the STM32_GDB_MCP_PIN_DB env var) triggers physical pin resolution with AF corroboration — behavior the schema does not spell out.

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 (parse) and resource (schematic netlist, KiCad .net) and precisely characterizes the output (BoardDescription: MCU part/family/line, per-pin map, power/ground nets). It is clearly distinguishable from siblings like describe_board, which it names as the read-side counterpart.

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

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

Explicitly frames the tool as 'the input contract for automated framework design', tells the agent it may pass either 'path' or 'text', and routes it to describe_board for reading results. It lacks explicit when-not conditions or alternatives for other import paths (e.g., import_spec), so it stops short of a 5.

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

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

Annotations declare this is a mutation (readOnlyHint=false) that is non-destructive and non-idempotent. Beyond that, the description adds real behavioral context: deterministic expansion, a named-but-absent peripheral being a 'conflict,' unmodeled intent surfaced as 'unresolved -- never guessed.' It stops short of describing the returned conflict/unresolved payload, but it substantially enriches the annotation profile.

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

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

Front-loaded with purpose and workflow, and the prerequisite/downstream sequencing bookends the text well. It is dense with examples and slightly verbose, but nearly every clause conveys new vocabulary or behavior rather than 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 mutating tool with no output schema, the description covers the translation contract, conflict/unresolved handling, prerequisite import, and downstream consumption. It does not state the exact response shape (e.g., what the unresolved/conflict report looks like), which is the main residual gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema's single example, enumerating the accepted vocabulary per peripheral type (framing, direction, flow_control, spi_mode, data_size, resolution, conversion, update_hz, dma/interrupt/priority opt-ins) and the HAL expansion rule. This meaningfully clarifies the opaque 'spec' object.

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: translate a controlled-vocabulary product spec into per-peripheral design params and cross-check against the netlist. It explicitly distinguishes itself from its siblings import_netlist (prerequisite) and design_framework (downstream consumer), so an agent can tell them apart without opening schemas.

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

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

Gives explicit ordering: 'Import a netlist first so the spec is cross-checked,' and names the downstream call 'design_framework(from_spec=true) builds the plan from the translated params.' The when-to-use context and the alternative route are both stated, leaving little to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety and side-effect profile is fully covered. The description adds that this is a scanning/discovery operation over project artifacts, but says nothing about whether results are cached into session state, whether it re-scans each call, or how it interacts with the optional debug 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?

A single front-loaded sentence with no filler or repetition. It is tight and readable, though it is arguably too terse for a tool whose output shape is undocumented.

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

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

With no output schema, the description carries the burden of explaining what a caller gets back, and it only vaguely implies a list of discovered artifacts without stating the return shape, grouping, or failure behavior when nothing is found. Annotations cover the safety side, so the remaining gap is moderate rather than severe.

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

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

Schema description coverage is 100%, and both parameters (session, project_root) have their defaults and fallback behavior documented in the schema itself. The description mentions no parameters at all, so it adds no meaning beyond the schema — baseline 3 is correct.

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 ("Discovers") and resource ("firmware project artifacts") and enumerates concrete examples (ELF, map, linker script, SVD, .ioc). However, it never distinguishes itself from siblings that also ingest project artifacts such as load_svd, load_device_pack, or load_symbols, so the agent must guess which discovery tool applies to a given need.

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 indication of when to call this tool, when not to, or what alternative covers a related need. The only hint is the implied "discovery/first step" framing, which the agent must infer from the word 'Discovers' alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context by documenting the return shape of resolve ({resolved,symbol,offset,section,file,line}) and the meaning of resolved=false, which matters because there is no output schema.

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

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

Two tightly packed sentences with the general purpose stated first, then the operation-to-argument mapping, then the one non-obvious return contract. The terse notation is efficient and front-loaded, though it is dense enough that it reads more like a reference line than prose.

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

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

With six operations and no output schema, an agent needs return-shape information for each mode, but only resolve is documented; it is unclear what size, type, address, functions or variables return. The tool's purpose and argument mapping are complete, but the return contract is only partially covered.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds real value beyond it by binding each operation to its expected argument — size(expr), type(expr), address(symbol), functions([regex]) — clarifying which of the six parameters pairs with which what value. The bracket notation on regex also communicates that it is an optional filter.

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

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

The description names a specific capability ('Symbol / type introspection') and enumerates all six operations via the what= syntax, so an agent immediately knows this is a symbol/type query tool rather than a memory or register reader. It does not explicitly name which siblings to prefer (read_variable, expressions, load_symbols), so sibling differentiation is only implicit.

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 operation list implies what each mode is for (size/type/address/resolve/functions/variables), which is more than nothing, but there is no explicit when-to-use vs when-not guidance and no named alternatives among the many sibling introspection tools. Usage must be inferred from the operation names.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low. The description adds real behavioral context beyond that: what the result contains (liveness and port), the existence of a 'default' session alongside named ones, and the per-session isolation guarantee. No return-format or failure behavior is described, keeping it out of 5 territory.

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

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

Two tightly written sentences, with the core behavior front-loaded and the multi-board tip second. The second sentence is arguably about other tools rather than this one, but it earns its place by explaining the session argument the agent will reuse everywhere.

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-required-param, read-only listing tool with annotations covering the safety profile and no output schema, the description covers what is returned (liveness, port) and the naming model. Nothing essential for calling it correctly is missing; only failure/empty-list behavior is unstated.

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

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

Schema coverage is 100%, so baseline is 3. The description nevertheless adds non-obvious semantics: the session name may be any arbitrary string and each name yields fully isolated state, which the schema's one-line description does not convey.

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

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

States a specific verb and resource ('Lists all debug target sessions') and adds scope detail — the default plus any named — plus what each entry shows (liveness and port). It does not name the closest sibling (get_session) for a single-session lookup, so differentiation is implicit rather than explicit.

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

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

The second sentence explains the multi-session model and how to pass 'session' to any tool, which is genuinely useful context. But it never says when to call list_sessions versus get_session, session_diagnostics, or recover_session, so the guidance for choosing this tool is only implied.

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

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

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=false), so the bar is lower. The description adds real context beyond them: state is persisted ('Stored on the session') and the spec's check vocabulary is enumerated, which aids correct authoring. It omits error/failure behavior and permission needs.

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

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

Front-loaded with purpose and sources, then the check vocabulary. Dense but every clause earns its place; the check-type enumeration is long yet genuinely informative for authoring a spec.

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

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

No output schema, and the safety profile is covered by annotations. The description supplies the source format, the check vocabulary, and the follow-up call, which is sufficient for a loader. Missing only failure/return-format details, which is minor here.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds the explicit either/or relationship between the two sources ('inline spec object or a JSON path'), which is meaningful semantics the schema only states separately. No syntax detail for the check schema beyond the type list.

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

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

States a specific verb (Load) and resource (AcceptanceSpec), clarifies what the spec represents (product-spec → deterministic checks), enumerates the supported check types, and distinguishes itself from run_acceptance by naming evaluation as the next step. An agent can tell it apart from siblings like import_spec and synthesize_acceptance.

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 (load here, then evaluate with run_acceptance), which is useful. However, it never states when to prefer this over near-siblings such as import_spec or synthesize_acceptance, and provides no prerequisites or exclusions.

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

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

Annotations only declare the write/repeat safety profile; the description adds substantive behavior: malformed packs are rejected with a problem list, never half-loaded, and shadowing a built-in family is gated behind allow_override=true. That is exactly the extra context the annotations do not carry.

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

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

Purpose is front-loaded in the first clause, followed by coverage facts, input modes, and failure semantics in a tight block. Slightly dense and the 'Facts are DATA, never guessed' phrasing is rhetorical rather than operational, but every other sentence earns its place.

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

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

With no output schema, the description covers return behavior (rejection with problem list, coverage report on no-arg call) and the override prerequisite. 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 description coverage is 100%, and the description's parameter remarks (path as JSON file, inline pack precedence, override gating) largely restate what the schema already documents. It adds no syntax or format detail for session, so baseline 3 applies.

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

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

States a specific verb+resource ('Register a verified device-fact pack') and names the exact content it controls (DMA request routing, NVIC vectors, PLL profile, timer bus/width), which distinguishes it from sibling loaders like load_svd or describe_board. 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?

Explains the trigger (adding a new STM32 family beyond the built-in F4/L4), the two input modes (path= JSON file or inline pack=), and a no-argument mode that reports current coverage. It lacks explicit when-not-to-use guidance or a named alternative, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=false, so the agent knows this mutates state without being read-only or repeatable. The description adds no behavioral context beyond that: it doesn't say the loaded SVD is attached to the session, what happens to a previously loaded SVD, or how invalid/missing files are handled.

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

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

A single front-loaded sentence with no filler or redundancy. It is efficient, though the extreme brevity is the root of the gaps noted in other dimensions rather than a structural flaw.

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 non-read-only state-mutating tool with no output schema, the description omits what the load actually affects (session-scoped vs global), persistence across sessions, and failure behavior. An agent cannot tell from this text alone how the operation changes system state.

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

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

Schema description coverage is 100%, with both 'session' and 'filepath' documented in the schema itself, so the baseline is 3. The description adds no meaning beyond the schema (e.g., path resolution rules or what the default target means).

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 (Loads) and resource (SVD file) plus the downstream purpose (peripheral parsing), which is more informative than a bare 'load' label. However, it does not distinguish itself from sibling loaders like load_symbols or load_device_pack, so an agent must infer which loader applies.

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

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

No when-to-use guidance, no prerequisites, and no alternatives named. The phrase 'for peripheral parsing' only weakly implies it should precede read_peripheral_register/decode_peripheral_register, and nothing tells the agent how it relates to load_device_pack or load_symbols.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so safety is partly covered, but the description adds meaningful context beyond them: that symbols are per-session, that no flashing occurs, and that the profile elf_path is a fallback. It does not disclose the non-idempotent behavior hinted by idempotentHint=false or error behavior when a path 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?

Three tightly-packed sentences, front-loaded with purpose and the key constraint 'WITHOUT flashing', and every sentence earns its place by adding a distinct fact (non-flashing, per-session lifetime, fallback path).

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

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

With no output schema and zero required parameters, the description covers what an agent needs to call it: when to use it, the no-flash constraint, and the elf_path fallback. It could be stronger by noting behavior on failure or the distinction from flash_firmware's side effects, but it is nearly complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters, including the same elf_path default the description repeats. The description adds no syntax, format, or precedence detail beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb (loads) and resource (symbols from an ELF/AXF) with an explicit scope qualifier, 'WITHOUT flashing', that immediately distinguishes it from the sibling flash_firmware. An agent can identify exactly what this does versus the nearby flash/build 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?

Explains the triggering conditions ('after a fresh connect or recover_session you need this') and names the alternative ('or flash_firmware'). It also states the purpose of loading (so symbol breakpoints resolve), giving the agent clear selection logic.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the safety profile is partly covered. The description adds the channel-to-parameter mapping, but says nothing about whether start blocks, whether logs persist across sessions, what get returns, or that clear discards buffered entries — all relevant for a stateful multi-action 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?

A single dense line that front-loads the purpose, then presents actions and the channel/parameter rules compactly with no filler. Every clause carries information; nothing is redundant with surrounding prose.

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

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

With 12 parameters, four mutating/side-effecting actions, and no output schema, the definition should say more about what get returns (entries with indices, per since_index) and what clear/stop do to ongoing capture. It covers the invocation surface but leaves the result and state-management behavior to inference.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's channel-conditioned parameter grouping (port/baudrate for uart, command/args/file for rtt/swo) largely echoes what the schema property descriptions already say, adding little beyond orientation.

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 concrete verb and resource ('Firmware log capture over a channel') and then enumerates the four operations with their argument shapes, so an agent immediately knows this is a log-capture tool rather than a config or state tool. It does not explicitly contrast itself with nearby siblings such as setup_swo or capture_state, which keeps it from a 5.

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

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

The action grammar (start/stop/get/clear) implies the lifecycle, and the note that rtt/swo take command/args or file while uart takes port/baudrate hints at channel-dependent usage. However, there is no explicit statement of when to choose this tool over setup_swo, capture_state, or session_diagnostics, nor any prerequisites or exclusions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond them: it requires no session, no probe and no target, and it explains the compact-mode interaction that can hide tools. That is genuine value, though it does not describe return format or cost.

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 dense sentence that front-loads the identity payload before the 'no prerequisites' clause and the usage trigger. Every clause carries distinct information (what is returned, what is not needed, when to call it) with no filler.

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

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

No output schema exists, so the description is right to enumerate the returned fields, and it does so fairly exhaustively. For a single-optional-param read-only introspection tool this is close to complete; it omits nothing an agent needs to call it correctly, though return shape nuance (ordering, formats) is 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?

Only one optional parameter with 100% schema description coverage, so the schema already documents the debug-session name and its omission default. The description's 'Needs NO debug session' adds a mild hint about the optional nature but no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource: it 'identifies THIS running stm32-gdb-mcp server' and then enumerates the exact facts returned (release version, git commit, package/install dir, compact mode state, tool counts). An agent immediately knows what it gets. It does not, however, name or distinguish itself from near-neighbors like self_check or tool_help.

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 trigger ('call it the moment a tool you expect is missing or behaves like an older build') and frames the alternative to avoid ('guessing which checkout the client actually launched'). It also pre-clears prerequisites ('Needs NO debug session, NO probe and NO target'). It stops short of naming a sibling it should be preferred over, so no exclusion clause.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description adds genuinely useful context beyond that by spelling out the decoded return shape and the one-line summary, which matters since there is no output schema.

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

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

Two tight sentences, front-loaded with the core action and return shape, with the optional flag mentioned second. No wasted text.

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

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

For a read-only inspection tool with full annotation coverage and full schema coverage, the description supplies the return structure an agent needs in the absence of an output schema. Only the session parameter's role and sibling differentiation are 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 coverage is 100%, so both parameters are already documented. The description only restates include_raw's effect (raw GDB output) and says nothing about the session parameter, so it adds little 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 ('Reads the call stack') and even characterizes the returned structure ({level, func, file, line, addr} plus a one-line summary). It does not distinguish itself from nearby siblings like analyze_stack or frame, which likely overlap.

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 guidance on when to choose this over analyze_stack, frame, or reconstruct_fault_context. The only conditional instruction ('Set include_raw=true...') is parameter usage, not tool selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds real value beyond them by disclosing what each mode actually retrieves (TCB pointers, names/priorities/stack, heap_4/5 usage), which is not inferable from the annotations or schema.

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

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

A single dense sentence with the primary verb and the mode enumeration front-loaded; every parenthetical clause maps to a real parameter value and none is filler. No wasted words.

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

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

With no output schema, the description carries the burden of explaining returns, and it does so for each mode. It omits only secondary details such as the exact output shape or how session/max_tasks/max_priorities interact with results, which the schema partially covers.

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

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

Schema coverage is 80% (baseline 3), and the description goes beyond the bare enum list by explaining the semantics of every 'what' value and restating that 'queue'/'mutex' require a Queue_t handle expression. It adds meaningful interpretation the enum alone 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 (Reads) and resource (FreeRTOS state) and then enumerates exactly what each 'what' value yields, including internal structures like pxCurrentTCB and ready/delayed/suspended/deleted lists. An agent can distinguish this from siblings like detect_rtos or analyze_stack 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 conditional requirements (queue/mutex need a handle) and describes what each mode returns, but never states when to reach for this tool versus detect_rtos, analyze_stack, or read_variable. Usage is implied by the mode descriptions rather than explicitly scoped.

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

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

Annotations already declare the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real value beyond them: it documents the return shape (raw bytes in memory order plus value_le), the little-endian byte ordering, and the rationale that hand-reversing leads to misread bit positions. That is useful behavioral/output context not present in the annotations.

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

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

Three sentences, front-loaded with the core action, and no repetition of the schema. The third sentence is longer but earns its place by explaining the byte-ordering pitfall that motivates value_le.

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

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

There is no output schema, so the description carries the burden of explaining return values, and it does so clearly (raw bytes plus value_le, with little-endian semantics). For a simple read tool whose annotations already cover the safety profile, nothing essential for invoking it correctly is missing.

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

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

Schema coverage is 100%, so the schema documents address, length, and session, making 3 the baseline. The description adds meaning tied to length by specifying the useful sizes (1/2/4/8 bytes) for which value_le is produced, which is semantic guidance absent from the schema itself.

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 'Reads' plus resource 'a block of memory from the target', and it goes further by describing what the call returns (raw bytes plus value_le). It does not, however, draw a line against adjacent siblings such as read_variable, read_registers, typed_memory, or read_peripheral_register, so the boundary is left to the agent to infer.

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 one concrete usage instruction -- use value_le when the read targets a peripheral register -- which is clear context for interpreting the result. But there is no statement of when to choose read_memory over its many read-oriented siblings, and no prerequisites or exclusions, so the guidance is largely implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds the SVD dependency as behavioral context but says nothing about failure behavior when the SVD is absent or the name is unknown, and nothing about the return format.

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

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

A single front-loaded sentence with the action, resource, and lookup mechanism stated in order and zero filler. Nothing is superfluous.

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

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

For a simple read tool with full schema coverage and annotations covering the safety profile, the description is nearly sufficient. The only gap is that it does not indicate what a read yields (raw value vs decoded fields), which matters given there is no output schema.

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

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

Schema description coverage is 100% – every parameter (session, register, peripheral) is documented with examples ('ODR', 'GPIOA') including the optional session. The description adds no meaning beyond the schema; baseline 3 applies when the schema does all the work.

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

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

Clear specific verb+resource ('Reads a peripheral register') with a scope qualifier ('using its name from the loaded SVD') that distinguishes it from an address-based read. However, it does not differentiate itself from close siblings such as read_registers or decode_peripheral_register, which an agent must still disambiguate by schema inspection.

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?

'From the loaded SVD' implies a prerequisite (an SVD must be loaded, cf. load_svd) and that lookup is by symbolic name, which is useful context. But there is no explicit when-to-use, when-not-to-use, or named alternative versus read_registers/decode_peripheral_register, so guidance is only implied.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description adds what the fault and cycle modes actually yield, but omits the notable side effect that enable=true enables and zeroes the counter (a state change on a tool marked idempotent) and says nothing about return shape.

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

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

Two compact, front-loaded sentences with no filler. The terse bracket notation is dense but still parseable, and the leading sentence establishes scope before the mode breakdown.

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

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

For a 4-parameter tool with no output schema, the description covers the mode semantics adequately but leaves gaps: the behavior of enable (zeroing the counter), the meaning of session, and the shape of returned register data are not addressed. Annotations carry the safety story, so this is workable but incomplete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description lightly annotates include_raw and enable within the mode shorthand but adds no syntax or semantics beyond what the oneOf schema already documents.

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 CPU register groups') and enumerates the three selectable modes (core/fault/cycle), so an agent knows exactly what the tool does. It stops short of distinguishing itself from near-siblings like read_peripheral_register or diagnose_fault.

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

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

The mode listing implies when to pick fault ('decodes CFSR/HFSR') versus cycle ('reads the DWT cycle counter'), which is useful selection guidance. However, there is no explicit when-not or pointer to overlapping siblings such as diagnose_fault, which also handles fault analysis, so usage must be inferred.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile is fully covered. The description's only added behavioral detail is the scoping requirement ('currently in scope'), which usefully implies the target must be halted/at a stop; it says nothing about failure modes such as optimized-out or out-of-scope variables.

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

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

A single tight sentence with no filler, and the key qualifier ('currently in scope') is placed where it will be read. Nothing is padded or restated from the schema.

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

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

No output schema exists, so return-format explanation would be welcome but is absent; the tool is simple and annotations cover safety, so the description is adequate. It stops short of noting prerequisites (halted session, symbols loaded) or what happens when the variable cannot be resolved.

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

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

With 100% schema description coverage, both parameters ('name' and optional 'session') are already documented in the schema. The description adds no additional parameter meaning such as name syntax, fully-qualified paths, or session default behavior, so the baseline 3 applies.

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

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

The description gives a specific verb and resource ('Reads the value of a C variable') plus a scope qualifier ('currently in scope'), so an agent knows exactly what it returns. It does not differentiate itself from closely related siblings like track_variable, inspect_symbol, or expressions, which an agent might otherwise 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?

The phrase 'currently in scope' implicitly tells the agent the variable must exist at the current execution point, which is a real usage constraint. However, there is no explicit when-to-use/when-not guidance and no routing to alternatives such as track_variable for ongoing monitoring or expressions for computed values.

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

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

Annotations already declare a non-read-only, non-idempotent, non-destructive, closed-world operation, and the description does not contradict that. It adds real behavioral context about the underlying method (MSP/PSP unwinding, EXC_RETURN handling), but it never explains why the tool is not read-only or what side effects/preconditions the non-idempotent hint implies.

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

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

Two sentences, front-loaded with the core action and mechanism, and the second sentence delivers the invocation condition with zero filler. Every clause carries technical meaning about what the tool does or when to call it.

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

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

For a diagnostic tool with annotations present and no output schema, the description covers what it does, why it is non-trivial, and when to invoke it. It would be fully complete with the prerequisite (e.g., symbols loaded) and a note on how it relates to the fault-diagnosis siblings, but nothing essential 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?

With a single parameter at 100% schema description coverage, the schema already fully documents 'session' (optional, default target). The description adds nothing about the parameter's meaning or format, so this sits at the baseline of 3 where structured data does the heavy lifting.

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

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

The description names a specific verb (reconstructs) and resource (the crash site after a HardFault) and details the mechanism: decoding fault registers, unwinding the auto-stacked exception frame from MSP/PSP via EXC_RETURN, and resolving to source file:line. This is far more specific than a tautology, but it never distinguishes itself from nearby siblings such as diagnose_fault, analyze_stack, or coredump, which an agent could plausibly 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?

It gives an explicit trigger condition: 'Run this when halted in a fault handler,' which is exactly the state-dependent cue an agent needs. However, it names no alternatives or exclusions, so an agent halted in a fault has no guidance on when to prefer diagnose_fault or analyze_stack over this tool.

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

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

Goes well beyond the annotations (which only flag readOnly/destructive/idempotent false) by disclosing what gets torn down and restarted, retry/backoff behavior, hub data-line toggling and power-cycling escalation, and that hub actions are reported in recovery_steps. Rich operational context an agent could not get from structured fields.

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

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

Front-loaded with the core action, then the trigger, then the hub escalation, then the reporting note. Dense but every sentence carries information; only slightly verbose in the hub explanation.

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

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

For a complex recovery tool with no output schema, it covers trigger, mechanism, escalation, and result reporting. Annotations supply the safety profile, so remaining gaps are minor.

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

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

Schema coverage is 100%, so the schema already documents deep, session, and escalate. The description explains the escalation concept but does not add parameter-specific syntax or format detail beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb (recovers) and resource (session) and details the exact mechanism: tear down GDB client/server, restart server, reconnect. This clearly distinguishes it from siblings like close_session, stop_debug_session, or start_debug_session.

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 gives the trigger condition: 'Use after a probe_unavailable or connection_lost error.' It also describes the escalation path when a hub is configured. It stops short of naming an alternative tool to use instead when recovery is not the right call.

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

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

Beyond the annotations, the description discloses meaningful behavior: each unresolved value becomes a clearly marked TODO and 'nothing is fabricated,' and it names what is returned (files, content, todo_count). It does not clarify whether files are written to disk (annotations imply non-read-only) or describe error/permission conditions, so it is strong but not exhaustive.

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

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

Three tight sentences, front-loaded with the core action and output, followed by the behavior guarantee (TODOs, no fabrication) and the prerequisite. 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?

With no output schema, the description carries the return-value burden and does so (files, content, todo_count), and it names the upstream dependency. It is nearly complete for this tool; only error/failure and disk-write behavior are left unspecified.

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

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

Schema description coverage is 100%, so both parameters (style, session) are already documented with defaults in the schema. The description adds no parameter-level detail, so baseline 3 is appropriate.

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

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

States a specific verb (Render) plus the exact resource and output artifacts: the synthesized FrameworkPlan turned into a HAL C init skeleton (bsp_init.c + bsp_init.h). An agent immediately knows what this produces and can distinguish it from design_framework (which builds the plan) and describe_framework.

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

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

Explicitly states the prerequisite: 'Run design_framework first.' This is clear context for when the tool is actionable, but it offers no alternatives or when-not-to-use conditions, 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?

Annotations already declare a non-readOnly, open-world write with no idempotency. The description adds real behavioral context beyond that: it bundles journal/metrics/version automatically, is deduplicated per session so retries won't spam, and defaults to the stm32-gdb-mcp repo. It doesn't state auth/permission needs or what happens if gh is unavailable, so not 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?

Four compact sentences, front-loaded with the core action and mechanism, then the trigger, then the dedup safeguard, then the default target. Every sentence earns its place with no filler.

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

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

With no output schema present, the description still conveys enough for correct invocation: what gets bundled, the dedup behavior, and the default repo. It leaves the return/confirmation behavior unstated, a minor gap for a write tool posting to an external service.

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

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

Schema description coverage is 100%, so each parameter is already documented, making 3 the baseline. The description adds only marginal meaning beyond the schema (confirms the repo default and the session target), so no lift above baseline.

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

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

States a specific verb (Files) and resource (GitHub issue about MCP problems from this session), plus the key mechanics: auto-bundling the session journal, metrics, and MCP version via the gh CLI. An agent can distinguish this from export_debug_report or self_check without opening a schema.

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

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

Explicit trigger: "Call this when a tool misbehaves or confuses you." This gives clear context for use. It doesn't name alternatives (e.g., export_debug_report for a local export vs. filing upstream) or explicit when-not conditions, keeping it below a 5.

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