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

With no annotations, the description carries the full burden. It discloses that the tool identifies 30 fault patterns and outputs human-readable diagnosis and troubleshooting steps, which is useful behavioral context. But it omits safety/read-only nature, rate limits, or side effects.

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

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

The description is front-loaded with the core function and an enumerated list of fault patterns, which clarifies scope. The long enumeration is informative but slightly verbose; it could be condensed without losing meaning.

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

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

Given the simple input schema and the presence of an output schema, the description provides sufficient context: what the tool does, what it detects, and what it outputs. The main gap is sibling differentiation, but that is covered under usage guidelines.

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

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

With 0% schema description coverage for the single parameter log_text, the description partially compensates by listing example inputs (serial_read output, pasted logs, compiler errors). It adds meaning but does not specify format, size, or handling of mixed content.

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: '分析日志' (analyze logs) and identifies 30 fault patterns, giving human-readable diagnosis and steps. Clearly defines the tool's function, though it does not explicitly differentiate from siblings like error_code_lookup or decode_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?

Specifies acceptable input sources (serial_read output, pasted serial logs, compiler/linker errors), implying when to use it. However, it does not state when to prefer alternatives or when not to use it, leaving usage context implied rather than explicit.

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

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

With no annotations, the description carries the full burden and does disclose meaningful runtime behavior: failures do not abort the run, and each step yields PASS/FAIL/TIMEOUT plus an echo tail. It leaves gaps on whether the port must already be opened via serial_open, whether the port is locked exclusively during the run, and the destructive potential of sending arbitrary AT commands (e.g. AT+RST).

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 what the tool does, then a compact worked example for the non-obvious parameter shape, then the output/behavior contract. No sentence is redundant and the example earns its space by removing schema ambiguity.

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

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

An output schema exists, so return values need not be re-explained, and the description still helps by previewing the PASS/FAIL/TIMEOUT structure. What is missing for a port-based tool is the setup precondition (must serial_open/serial_list be used first) and any exclusivity note; otherwise the definition is sufficient 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 0%, so the description must compensate, and it does explain the most important parameter well: the steps array shape with cmd/expect (regex)/timeout_s shown by concrete example. However, port, default_baud, and total_timeout_s receive no explanation at all, and the relationship between per-step timeout_s and the top-level total_timeout_s is unstated.

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 ('批量执行 AT 指令序列并逐条断言') plus the use case ('半自动回归测试'), which cleanly separates it from the single-shot serial_send / rs485_send siblings in the list. 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?

The description gives a clear context for use ('半自动回归测试') and an operating rule ('中途失败不中断，方便一次看全'), which tells the agent this is the right choice when it wants a full pass/fail sweep rather than fail-fast behavior. It never names an alternative tool or states when not to use it, 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?

With no annotations, the description carries the burden and does so well: it discloses the USB CDC no-op behavior and its rationale (baud rate is not in the data path), the silent-device case, and that offline scoring avoids occupying the port. It does not state whether the port must be free/exclusive (potential conflict with serial_open) or the time cost implied by sample_s across candidates.

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 core behavior, then adds the offline and silent-device cases before the USB CDC caveat. Generally tight, though the ★ section is somewhat verbose and slightly repetitive about repeated byte reads.

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 hardware-detection tool with an output schema (return values need not be explained) and no annotations, the behavioral coverage is strong. Remaining gaps are sample_s semantics and port exclusivity/timing expectations.

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

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

Schema description coverage is 0%, so the description must compensate. It adds real meaning for log_text (triggers offline mode) and candidates (explicit list to force scanning, with a concrete example), but says nothing about sample_s and only implicitly covers port.

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 ('自动探测波特率' - auto-detect baud rate) plus the mechanism (open port at each candidate, sample, score by log-likeness, recommend). It is clearly distinguishable from siblings like serial_open/serial_read, which do not perform detection.

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

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

Explicitly routes the agent: supply log_text to use offline scoring that does not occupy the port; tell the user to reset when the device is silent; and on USB CDC ports the tool short-circuits, with the escape hatch being an explicit candidates list. Both when-to-use and when-not-to-use are covered.

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

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

No annotations are supplied, so the description carries the full behavioral burden. It does disclose a genuine behavioral trait - the pitfall list is ordered by failure rate - and states that a data source is reported. However it never states that the call is read-only/side-effect free, and gives no hints on caching, name-resolution failure behavior, or cost, which for a zero-annotation tool leaves a meaningful 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?

Three tight sentences, front-loaded with purpose, then examples, then the usage trigger. No filler; every clause adds information an agent needs.

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

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

An output schema exists, so return-value explanation is unnecessary, and the description correctly focuses on scope, examples, and timing. For a single-parameter read lookup with no annotations, the only remaining gap is that valid name values are only illustrated, not bounded (the description could have pointed to board_list for discovery).

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

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

Schema description coverage is 0% and the single 'name' property has no schema description, so the description must compensate and largely does by supplying concrete example values ('bluepill', 'blackpill_f411') that reveal the expected identifier style. It stops short of describing the full naming convention or where valid names come from.

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

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

Names a specific verb+resource ('输出指定开发板的板级知识') and itemizes what that knowledge contains: onboard peripherals and their occupied pins, a board-level pitfall list sorted by failure rate, power-supply notes, and the data source. An agent can tell it apart from most siblings, though it never explicitly contrasts itself with the obvious neighbor board_list (which presumably enumerates the names this tool accepts).

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

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

Gives a clear usage trigger: consult this before hardware selection or before troubleshooting board-level pitfalls. It does not name alternatives (e.g. board_list for discovery, pinmap_get for pin detail) or state when not to use it, so it stops short of full when/when-not guidance.

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

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

No annotations are provided, so the description carries the disclosure burden. 列出 implies a safe read-only listing, and the description usefully adds that entries include board-level pitfall checklists, but it never explicitly states the read-only nature or scope/return shape—minor gaps for a simple list 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?

Two tight sentences with the resource front-loaded and the usage hint following. No filler, though the second sentence could be marginally sharper about when it matters.

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

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

An output schema exists, so return values need not be explained, and a parameterless list tool needs little behavioral detail. The description covers what it lists and why to call it, leaving it adequate though not rich.

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

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

The tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. Nothing in the description is needed to clarify parameter meaning.

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: 列出 (list) 板级知识库已收录的开发板 (boards catalogued in the board-level knowledge base). It is clearly a list operation, distinguishable from the singular board_get sibling, though it does not explicitly name that sibling.

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

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

Adds a clear when-to-use cue: check this before selecting a board so you can see if a ready-made board-level pitfall list exists. No explicit exclusion or named alternative (e.g. board_get for details) is given, so it stays just 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?

With no annotations, the description carries the burden and does well: it declares the operation is non-invasive (does not touch any bus, pure handshake) and explains the port-resolution fallback to MCU_DEBUG_BRIDGE_PORT. It omits any auth/permission note and does not restate the baudrate behavior, but for a read-only probe this is minor.

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 core definition, then the diagnostic rationale and the port/env detail. Several lines are spent on troubleshooting motivation, but each sentence adds routing or parameter value; no obvious filler.

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

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

An output schema exists, so return values need not be described. For a simple 2-param, no-required probe the description covers purpose, when-to-use, and the key port fallback; only baudrate behavior is left undocumented.

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

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

Schema description coverage is 0% for 2 parameters, so the description must compensate. It explains the port fallback via the MCU_DEBUG_BRIDGE_PORT environment variable, which is genuinely useful, but says nothing about baudrate or its default 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 action (handshake / self-check with the bridge firmware) and its scope ('不碰任何总线，纯握手'), which immediately separates it from the many bus tools (i2c_scan, spi_scan, serial_*). An agent can tell what it does and what it does not touch 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?

Gives explicit usage context: it is the first step when 'bus tools aren't working' — confirm the bridge is alive before suspecting wiring. It frames the diagnostic order clearly but does not name a concrete alternative sibling (e.g. probe_list or serial_list) to choose against.

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

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

With no annotations, the description carries the full burden and does so richly: read mode does not reset or halt the core, full mode resets the target once and halts the kernel, requires write permission (需要写权限), and has the side effect of polluting RCC_RSR. It even explains the empirical reason the two modes were split.

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

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

Purpose and the two modes are front-loaded and the reset warning is prominent. It is somewhat long, with an empirical-rationale paragraph, but the content is load-bearing rather than redundant.

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

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

For a tool with no annotations and real side effects, the description supplies the safety profile, mode tradeoffs, and prerequisites; an output schema exists so return values need no explanation. 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?

Schema coverage is 0%, so the description must compensate. It fully explains the mode parameter's semantics (read vs full), but the sn parameter is never mentioned anywhere, leaving half the parameters undocumented.

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 (目标芯片的身份与存储信息) and enumerates exactly what is returned: 型号 / Device ID / 修订 / Flash 容量 / UID / 读保护. This is clearly distinguishable from siblings like reset_reason or decode_register.

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 splits usage by mode: read (default, no reset) vs full (extra data at the cost of a reset+halt), and adds an exclusion — do not call it first when investigating reset cause because it pollutes PINRSTF in RCC_RSR. Full when/when-not/alternative coverage.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it only enumerates the shape of the returned record. It never states that this is a read-only lookup, whether it can error on an unknown name, or any side effects/auth requirements. The content list overlaps with what the output schema already conveys.

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 compact sentence plus a provenance clause; the resource and its content are front-loaded and nothing is padded. The slash-delimited field list is dense but readable for this domain.

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

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

An output schema exists, so return values need no full explanation, and the description adequately covers the data's theme. It nonetheless omits error behavior, prerequisite state, and any read-only assurance, leaving an agent to infer them for a lookup tool with no annotations.

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

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

Schema description coverage is 0% and the sole parameter 'name' is undocumented in the schema. The description partially compensates by stating where the name comes from (component_list), which is useful provenance, but it does not give the expected format or validity constraints for the value.

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

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

The description names a specific verb+resource: fetching the selection details (选型详情) of a single component, and enumerates the content facets (interface, address, porting requirements, top pitfall, factory verification record, wiring notes). This clearly distinguishes it from the sibling component_list, which enumerates rather than details one item. It stops short of a 5 only because it never states the operation in a single crisp clause.

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?

"name 来自 component_list" gives a concrete workflow hint (get the name from component_list first), which is genuine usage guidance. However, there is no explicit when-to-use/when-not-to-use framing and no mention of prerequisites or what to do if the component is unknown.

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

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

No annotations are provided, so the description carries the burden. It does disclose the returned fields (bus addresses, microsecond timing) and an output schema exists, so return format is covered, but it says nothing about read-only nature, auth needs, or rate limits.

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

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

Front-loads the resource and scope, then the usage trigger, then the filter note. Every sentence earns its place; only minor redundancy across the interface list and the filter example.

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

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

With an output schema present, return values need not be re-explained, and the description covers scope, usage trigger, and the single filter parameter. Complete for an agent to call it correctly.

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

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

Schema coverage is 0%, so the description must compensate, and it does: it explains that 'bus' filters by interface and supplies the candidate values (i2c/uart/timer_pwm/gpio_timing) plus an example ('i2c'). This meaningfully exceeds the bare schema.

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

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

States a specific verb (list) and resource (sensors/modules), scoped by interface categories (i2c/uart/timer_pwm/gpio_timing), and notes what is included (addresses, microsecond timing). The list-vs-get distinction from the sibling component_get is implicit rather than named, so it falls just 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?

Gives a concrete when-to-use trigger ('when answering which off-the-shelf part for temp/humidity/ranging/attitude, check here first, don't report from memory'). Strong positive guidance, but no explicit exclusion or named alternative such as component_get for a specific part.

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

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

With no annotations, the description carries the full burden and does so richly: it discloses that the tool refuses to interpret garbage addresses (BFARVALID/MMARVALID=0), flags IMPRECISERR as making BFAR untrustworthy, and emits a CFSR hint when FORCED=1. These are exactly the guardrails an agent must not skip, far beyond what a bare name would 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?

Front-loaded with purpose, then the trigger, then an executable example, then the three caveats as a scannable bullet list. Every element earns its place; no preamble or filler.

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

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

For a 5-param, no-required-args diagnostic tool with an output schema (so return values need not be explained), the description covers purpose, trigger, input semantics, default-behavior caveats, and the follow-up path. 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 0% and there are 5 params, so the description must compensate. It does so well by showing a concrete call example (cfsr/hfsr/bfar), stating 'any combination' is accepted (implying all optional), and explaining register-field interrelations (BFARVALID, MMARVALID, IMPRECISERR). It stops short of documenting the arch and mmfar parameters, so it is not fully complete.

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 (decode Cortex-M fault registers) and the value delivered (plain-language diagnosis + troubleshooting directions). It is clearly differentiated from siblings like decode_register/decode_register_svd by the fault-specific scope, and it explicitly routes follow-up work to symbol_lookup.

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?

States the exact trigger condition ('when the device crashes / enters HardFault') and names the follow-up alternative (symbol_lookup) once a trustworthy address is obtained. An agent knows when to reach for this tool and what to do next, without needing to open any schema.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explains the fields input format, but does not state that the operation is read-only, side-effect-free, or how errors are handled; 'decode' implies a pure read, but this is not explicit.

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

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

Three short sentences: purpose, fields format, and usage. The content is front-loaded and every sentence earns its place with 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?

Given the output schema covers return values and the tool is relatively simple, the description covers purpose, usage, and the tricky fields parameter well. However, it does not disambiguate from decode_register_svd, and the 'width' parameter remains unexplained, leaving a minor 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 description coverage is 0%, so the description must compensate. It provides a concrete example for the complex 'fields' array, showing key differences between 'bit' and 'lsb'/'width' forms, which is essential and absent from the schema. It leaves 'value' and 'width' unexplained, though 'value' is self-evident and 'width' has a schema default.

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

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

The description states a specific verb and resource: '把寄存器原始值按位域拆开解释' (decode register raw value into bit fields). It is clear, but it does not explicitly distinguish this tool from the sibling decode_register_svd, which could also decode registers. The manual fields format differentiates it implicitly, but no direct contrast is made.

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 when-to-use condition: '手头有寄存器值不知道每个位什么意思时用' (use when you have a register value and don't know what each bit means). No alternatives or exclusions are mentioned, so it stops short of explicit when-not guidance.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that output includes enum value hints and descriptions, which is useful, but it does not state read-only nature, error handling for invalid files or names, or any side effects.

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

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

The description is front-loaded with the core purpose, followed by a clarifying example. It is concise and every element earns its place, though the example could be slightly more compact if paired with explicit parameter labels.

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

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

An output schema exists, so return values need not be detailed, but the 0% input schema coverage means the description should do more to define the required parameters. It provides an example and explains svd_path, but omits peripheral/register semantics and error behavior, leaving gaps for a four-parameter tool.

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

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

Schema description coverage is 0%, so the description must compensate. It explicitly explains that svd_path points to a vendor SVD file, and the example maps all four positional arguments, but it does not define peripheral, register, or value beyond the example, leaving some ambiguity.

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: decode register bitfields using a CMSIS-SVD file. It clearly conveys the tool's function, but does not explicitly differentiate from the sibling tool decode_register, which likely serves a similar purpose without SVD.

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 offers no explicit when-to-use or when-not-to-use guidance, nor does it name alternatives such as decode_register. It only implies usage through the mention of CMSIS-SVD files and an example, leaving selection between siblings 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?

No annotations, so the description carries the burden. It does add genuine behavioral context: the code is pre-validated and deliverable as-is, and only *_port.h needs adaptation. But it omits any side-effect/safety profile and does not clarify whether this is purely a read/lookup operation.

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

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

Two compact sentences, front-loaded with the core output description and followed by the source of the parameter and a delivery caveat. No filler.

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

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

An output schema exists, so return values need not be re-explained; the description covers purpose, parameter provenance, and the key adaptation caveat. Complete enough to call correctly, with only the sibling-selection question left open.

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

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

Schema coverage is 0% and the single name parameter has no description in the schema. The description partially compensates by stating the name originates from driver_list, giving provenance, but adds no format or matching-rule detail.

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

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

States a specific verb (输出/output) and resource (指定驱动) plus the concrete return payload: wiring table, complete code, and verification records. This distinguishes it from driver_list (enumeration) and driver_wiring (wiring only), though the overlap with driver_wiring is not explicitly resolved.

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?

"name 来自 driver_list" implies a required lookup step before calling, which is useful sequencing guidance. However, it never states when to choose driver_get versus driver_wiring or driver_list, so usage is only implied rather than contrasted.

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

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

No annotations are provided, so the description carries the burden. It does disclose a meaningful data trait (templates are pre-validated and come with factory verification records), and 'list' implies a read-only operation, but nothing is said about freshness, result size, or what a verification record means in practice.

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

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

Two short sentences, front-loaded with what is listed and followed by the decision cue. No filler or restatement of the title.

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

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

With an output schema present and zero input parameters, the description need not explain return values. It covers purpose and entry-point positioning; only the hand-off to driver_get/driver_wiring for actual usage 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?

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

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

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

States a specific verb (列出/list) and a precisely scoped resource: pre-validated driver templates that carry factory verification records. This is clearly separable from siblings like driver_get (retrieve one) and driver_wiring, without needing to open a schema.

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

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

Gives explicit when-to-use context (sensor portion of a project) and a when-not alternative ('instead of writing your own'). It does not name the natural follow-up sibling (driver_get) for pulling full details, so it falls just 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?

No annotations are provided, so the description carries the full burden. It discloses the categories of content returned (wiring table, pitfalls sorted by failure rate, log reading, exam highlights), which is useful, but says nothing about permissions, freshness/caching, or the read-only nature beyond the implicit 'look up'.

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 sentences with the core purpose front-loaded and the usage trigger second. No filler; each clause carries meaning. Slightly list-like but appropriately sized for the tool.

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

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

An output schema exists, so return-value explanation is not required, and the single-parameter signature is simple. The description covers purpose, content, and trigger adequately for a read-only knowledge lookup; only the parameter's exact expected form is left unstated.

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

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

Schema description coverage is 0% for the single 'name' parameter. The description implies the parameter is a driver identifier ('specified driver') but adds no format, casing, or accepted-value guidance beyond that inference. Marginal value over the bare schema.

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

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

States a specific verb+resource: '查指定驱动的接线知识库' (look up the wiring knowledge base for a specified driver), and enumerates the content types returned (wiring table, ranked pitfall list, log interpretation, exam points). This clearly separates it from driver_list/driver_get, though it never names those siblings explicitly.

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

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

Gives an explicit usage trigger: check this before answering 'how do I wire XX sensor / why doesn't it work'. That is clear context for when to reach for it. It stops short of naming alternatives to use instead (e.g., driver_get for metadata), so it is not a full when/when-not/alternatives statement.

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

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

No annotations are provided, so the description carries the full disclosure burden. It does reveal the shape of the returned knowledge (artifacts, build config, log signatures, pitfalls), which is useful, but never states that this is a read-only, side-effect-free lookup or whether it depends on a prior scan. For a low-risk reference lookup with an output schema, this is adequate but thin.

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

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

Two short lines, zero filler, with the purpose front-loaded and the parameter constraint immediately after. Every sentence earns its place.

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

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

With an output schema present, the description need not explain return values, and it correctly focuses on the key source and identifier semantics. The only real gap is the absence of any note on read-only behavior or failure handling for an invalid ecosystem key.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: it explains that 'name' is the key produced by ecosystem_list and supplies three concrete example values. It stops short of stating whether an unknown key errors or returns an empty result.

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 ('输出指定生态的识别特征') and enumerates exactly what the output covers (工程产物 / 构建配置 / 日志特征 / 常见坑). It also differentiates itself from the sibling 'ecosystem_list' by positioning itself as the detail lookup keyed by that tool's output.

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

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

Gives a clear prerequisite: obtain the 'name' key from ecosystem_list, with concrete key examples (zephyr / keil / rust_defmt). It does not state any when-not-to-use condition, but the list-then-get workflow is unambiguous.

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

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

No annotations are provided, so the description carries the burden, but for a zero-parameter read-only listing tool the safety profile is self-evident. It discloses the contents of the list and its role in the diagnostic workflow, but adds nothing about freshness, stability, or ordering of results.

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

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

Two short sentences, front-loaded with the concrete list of ecosystems, followed by the use-case rationale. No filler; 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?

An output schema exists, so return values need not be explained, and the description adequately covers the tool's purpose and place in the workflow. It stops short of explicitly connecting to the sibling tools that consume its result, which would have made it complete.

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

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

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

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

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

States a specific verb+resource ('列出已收录的嵌入式生态/框架') and enumerates concrete examples (Zephyr / RT-Thread / PlatformIO / Keil / IAR / Rust defmt). This clearly distinguishes it from the sibling 'ecosystem_get', which retrieves a single ecosystem.

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 trigger context: '拿到不认识的工作目录、或一段陌生的报错时', and gives the rationale for acting first. It does not, however, name the alternative sibling (e.g. project_detect / ecosystem_get) that an agent should use after this step, so routing is inferred rather than stated.

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

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

With no annotations, the description carries the full burden and does meaningful work: it discloses the aggregate diagnostic output ('能干什么、缺什么、缺了会导致哪些工具不可用') and, importantly, the honesty constraint that it only reports what it actually probed and explains why anything unprobed is missing. It does not restate return format, which is acceptable since an output schema exists.

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

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

Front-loads the purpose and its scope in the first line, then the trigger condition, then a behavioral caveat. Each of the three statements adds distinct information; nothing is redundant with the name or schema.

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

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

For a zero-parameter read-only diagnostic with a full output schema, the description covers purpose, trigger, and a key behavioral caveat, which is sufficient to call it correctly. The only minor omission is any indication of cost or runtime when probing many subsystems.

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

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

The tool takes zero parameters, so there is nothing to document beyond the schema; baseline 4 applies. No parameter meaning is missing or ambiguous.

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

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

States a concrete verb (self-check) and enumerates the specific resources it inspects — dependencies, serial, programmer/flasher, knowledge-base root, version — and frames itself as a one-shot aggregate ('一次问清'), which separates it from granular siblings like toolchain_status, probe_list, and flash_tool_detect. An agent can identify it as the environment entry point without opening the schema.

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

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

Explicitly says when to run it ('拿到陌生机器、或工具突然不好使时先跑这个') and articulates the benefit over trial-and-error. It stops short of naming an alternative tool to use instead in specific cases, so the routing to siblings is implied rather than stated.

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

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

No annotations, so the description carries the behavioral burden, and it does disclose meaningful traits: data source (external JSON knowledge base), citation provenance, enumeration behavior when arguments are omitted, and the no-guessing fallback. It stops short of stating anything about the return shape, but an output schema exists.

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

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

Front-loaded purpose, then argument modes, then coverage list, then the failure rule — every sentence carries distinct information with no repetition of the schema or title.

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

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

Output schema exists, so return values need not be re-explained. With the source, modes, covered tables, and the not-found behavior all documented, an agent has everything required to invoke it correctly.

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

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

Schema coverage is 0% with two undocumented params, so the description must compensate — and it largely does, defining the interaction semantics of table and code (blank/only/both) and listing valid table values. It omits any format hints for the code string itself (case, prefixing).

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: look up error codes in an external knowledge base (knowledge/error_codes/*.json) with per-entry source citations. It clearly distinguishes itself from lookup siblings (decode_register, decode_fault, symbol_lookup) by scoping to embedded/AT/Modbus/MQTT error codes.

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 enumerates the three invocation modes keyed on argument combinations (table blank = list tables, table only = list codes in that table, table+code = definition/troubleshooting/source). It also names the covered tables and gives an explicit when-not rule: say 'not covered' rather than guessing another code.

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

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

With no annotations, the description carries the full burden and does so richly: it discloses the two-gate dry_run/confirm write path, the readonly isolation mode that refuses outright, and the auto-reset behavior plus the concrete consequence (halted SWD core, board won't run) if reset is skipped. This is exactly the behavioral context an agent needs for an irreversible action.

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 safety-critical double-gate and isolation constraints are front-loaded before the examples, and each section earns its place. It is fairly long and dense, but the density is justified by the irreversible nature of the operation 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?

An output schema exists, so return-value documentation is unnecessary. For a high-risk mutation tool with 7 parameters and zero schema coverage, the description still covers safety gates, auth/isolation gating, per-family usage, probe selection and post-flash reset behavior — nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it explains the semantics of dry_run (default True, returns command only), confirm (must be True together with dry_run=False), sn (probe serial for multiple same-model debuggers), chip, port and tool through worked examples. It leaves file_path format (absolute/relative) and the tool default 'auto' meaning unstated, so not quite complete.

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

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

States a precise verb+resource (flash firmware to a dev board) and immediately flags the operation as irreversible. This clearly distinguishes it from read-only siblings like flash_verify, flash_tool_detect and chip_info, so an agent knows this is the actual write path.

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

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

Gives concrete when-to-use scenarios per chip family (STM32/ST-Link default, ESP, generic Cortex-M via pyocd) and states the default-preferred toolchain. It stops short of naming explicit alternatives/exclusions against siblings, but the usage context is concrete and actionable.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses that it inspects the local machine for specific flashing tools and acts as a prerequisite check, which implies a read-only operation, but it never explicitly states that it is read-only/non-destructive, nor does it mention permissions, environment assumptions, or how it searches for the tools.

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

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

Two short sentences with zero filler. The first sentence front-loads the purpose and enumerates the tools detected; the second gives the usage trigger. Every sentence earns its place.

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

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

For a zero-parameter detection tool with a full output schema, the description tells the agent what it detects and when to call it, and the output schema can convey return values. It omits OS-specific or permission caveats, but the essential agent needs are 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?

The input schema has zero parameters and 100% schema description coverage, so the baseline is 4. The description adds no parameter guidance, but none is needed for a tool that takes no arguments.

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 (检测/detect) and resource (installed flashing tools: esptool/st-flash/pyocd/openocd). It is clear the tool inspects the local machine for programming executables, though it does not explicitly contrast with the sibling `toolchain_status`, which may also report installed tooling.

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

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

Explicitly says '烧录前先调这个看有什么可用' (call this before flashing to see what is available), giving a clear when-to-use trigger relative to flash_firmware. It does not name exclusions or alternative detection approaches.

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

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

With no annotations provided, the description carries the full burden and does so well: it declares the operation read-only, notes it runs over hotplug, and discloses the diagnostic output (first mismatch offset plus 8 bytes of surrounding context, distinguishing a fully unwritten segment from a few bad bytes). It omits auth/permission needs and any performance or chunk-related behavior, keeping it short of a 5.

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

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

Front-loads the core action, then the comparison-to-`-v` rationale, then file formats, then the debugging trigger, then the checksum caveat. Every section is relevant to invoking the tool correctly, though the emblem-heavy formatting and the extended `-v`/checksum digressions are slightly more verbose than strictly necessary.

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

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

An output schema exists, so return values need not be spelled out, and the description still explains the key diagnostic payload. For a verification tool it covers usage, file formats, and comparison semantics well; the gaps are the undocumented `sn` and `chunk` parameters rather than missing conceptual guidance.

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

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

Schema description coverage is 0%, so the schema contributes nothing beyond bare titles. The description compensates for file_path (explaining .bin/.hex/.elf support and the default 0x08000000 base address for .bin) and partially for address, but says nothing about `sn` or `chunk`, leaving half the parameters undocumented in both places.

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: byte-by-byte comparison of a firmware file against actual chip contents. It distinguishes itself from the sibling flash_firmware and from CLI's `-v` and `-checksum`/`-fchecksum` mechanisms, so an agent can tell exactly what this tool is and is not.

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 condition ('flash reported verified but device doesn't work, call this first to rule out a failed write'), names the alternative it supersedes (`-v` re-flashes; this reads back), and explicitly warns against verifying with `-checksum`/`-fchecksum` because their semantics differ. When-to-use, when-not, and alternatives are all present.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose a strong trait: failures (missing header, length out of bounds, truncated frame) are reported individually with leftover bytes and never silently dropped. That is exactly the kind of context an agent needs. It does not mention the max_frames cap or how endianness/length_size affect parsing, so it is not fully complete.

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 mechanism, follows with a tight when-to-use line, then three illustrative one-line calls, and closes with the critical no-silent-drop warning. Every element earns its place and the examples substitute effectively for prose parameter explanations.

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

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

An output schema exists, so return values need no prose. The description covers purpose, use condition, the header/length_offset dependency, checksum options, and error behavior, which is strong for an 8-param tool. The remaining gap is the four undocumented tuning parameters (endian, max_frames, length_size, length_includes_header).

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

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

Schema description coverage is 0% across 8 parameters, so the description must compensate and it only partly does. It explains header, length_offset (offset relative to frame start), and the checksum enum values (none/sum8/crc16_modbus), but endian, max_frames, length_size, and length_includes_header are left undocumented anywhere.

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 (generic binary frame parsing) plus the mechanism (header + length field splitting, optional per-frame checksum). This implicitly distinguishes it from protocol-specific siblings like modbus_parse and nmea_parse, but never names them explicitly, so an agent must 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?

Gives a concrete use condition: custom MCU protocol hex streams that don't line up. It also states the parameter-filling advice (fill as little as possible) and the header/length_offset dependency. It stops short of explicitly routing to or away from the sibling parsers (modbus_parse, nmea_parse), so alternatives are implied rather than stated.

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

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

With no annotations, the description carries the behavioral burden and does add real context: it discloses that the tool actively validates the address width and rejects 8-bit addresses, and that all-0 / all-0xFF reads produce two distinct diagnostic cause lists (notably that 0xFF usually means the device is unpowered/disconnected, not that the register holds 0xFF). It does not describe error codes, bus-selection behavior, or access requirements.

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

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

Front-loaded with the core action and the single most dangerous parameter mistake up front, then a starred gotcha note. No filler sentences; every clause carries actionable information.

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

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

An output schema exists, so return-value format need not be covered, and the description instead covers the failure interpretation an agent actually needs. It is nearly complete for a register read, with the remaining gap being the undocumented bus/port/baudrate parameters and no explicit pointer to sibling tools.

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

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

Schema description coverage is 0% across 6 parameters, so the description must compensate. It does define addr (7-bit, with 0x68 vs 0xD0/0xD1 example), reg, and count (range 1–256), but leaves bus, port and the unexpected baudrate parameter completely unexplained, so nearly half the parameter surface remains undocumented.

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: read an I2C slave register, and even characterizes the archetypal use case (checking whether an IMU is alive). This clearly separates it from i2c_write_reg, i2c_scan and spi_read_reg siblings.

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

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

Gives concrete usage context ("the most common 'is this IMU alive' action") and a hard precondition: addr must be the 7-bit form (0x68, not 0xD0/0xD1) because the tool rejects the 8-bit form. It does not explicitly route the agent between this and siblings like i2c_scan or decode_register, so it stops short of a full when/when-not guide.

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

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

With no annotations, the description carries the behavioral burden and handles it well: it discloses that reserved address segments are skipped, that the default scan range is 0x08–0x77, and that an ACK only proves a responder exists, not that the part is functional. It does not cover permissions or error behavior, but for a read-only scan this is substantial disclosure.

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

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

Front-loaded purpose sentence followed by a clearly delineated three-point caveat block. Every element earns its place, though the formatting emphasis markers add some noise.

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

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

An output schema exists, so return values need not be explained, and the description instead supplies the interpretive caveats an agent needs to avoid over-reading scan results. The remaining gap is the silently undocumented bus/port/baudrate parameters.

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

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

Schema description coverage is 0% across 5 parameters, so the description must compensate. It explains low/high as a narrowing range and gives their conceptual default, but bus, port, and baudrate are completely undocumented in both schema and description. It also states a default range of 0x08–0x77 while the schema shows low=0/high=0, leaving the actual default behavior ambiguous.

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 uses a specific verb+resource: '扫描 I2C 总线上的 7 位地址' (scan 7-bit addresses on the I2C bus), and clearly frames the output as which responding addresses might hold which device. It also implicitly distinguishes itself from i2c_read_reg by describing the scan as the identification starting point.

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

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

It gives context for use ('板子上到底挂了什么' first-hand answer), points to the alternative tool for identification ('要定种必须读它的 WHO_AM_I / ID 寄存器（i2c_read_reg）'), and warns when the scan will be misleading (devices behind a TCA9548A mux). What is missing is explicit routing versus the other scan siblings (spi_scan, onewire_scan), but the context is clear.

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

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

With no annotations, the description carries the full burden and does well: it discloses the verify readback side effect, the rationale for the default-off behavior, and an authorization gate (isolation-layer write permission) including what happens on rejection. It does not cover rate limits or what happens to the device on partial failure, but the mutation's safety profile and auth requirements are clearly surfaced.

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 core action, then data format, then verify semantics, then the permission note — a logical order with little waste. The ★ and bold emphasis markers add minor visual noise but each 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?

An output schema exists, so return-value explanation is unnecessary. The description covers the operationally significant behavior (verify, permission gating) for a mutation tool, with the main remaining gap being the undocumented peripheral parameters (bus/port/baudrate).

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

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

Schema description coverage is 0% across 7 parameters, so the description must compensate. It adds real meaning for two of them — accepted data encodings ('0x01' / '1,2' / [1,2]) and verify's readback behavior — but bus, port, addr, reg, and baudrate remain entirely undocumented in both schema and description.

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

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

States a specific verb and resource (写 I2C 从设备的寄存器), which an agent can immediately distinguish from the sibling i2c_read_reg. The scope is unambiguous and does not depend on reading the schema.

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

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

Gives concrete guidance on when to enable verify (read-write vs write-only registers like command/soft-reset registers) and the consequence of defaulting it on. It also states the write-permission precondition (read-only profile gets rejected). It stops short of naming i2c_read_reg as the alternative for reads, so it is clear context rather than full when/when-not routing.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the default no-op behavior, the exact flag combination and permission tier needed to mutate, the irreversibility of deletion, the built-in retention defaults, and that logs may contain credentials.

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 safety-critical default first and uses markers (★, ⓘ) to make scanning easy; every sentence carries needed information for a destructive tool. It is somewhat long, but the length is largely justified by the risk profile.

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

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

An output schema exists, so return values need not be explained. Combined with defaults, prerequisites, irreversibility and the credential warning, an agent has everything needed to call this destructive 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 0%, so the description must compensate and does: dry_run's default/effect, confirm's role in enabling real deletion, and the meaning of keep_days/keep_count=0 (built-in 30-day / 200-item policy). All four params get semantics beyond the bare schema.

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

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

Names a specific verb+resource (session-log retention policy / cleanup entry) and immediately scopes it with the condition 'when logs only grow'. No sibling does pruning, so the agent can identify this tool unambiguously.

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 precise conditions: dry_run=True is the default safe path that deletes nothing, and real deletion requires dry_run=False + confirm=True + write isolation tier. Strong when/when-not guidance, though it never names an alternative tool (e.g. sessions_list/analyze_log) for inspecting logs first.

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

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

No annotations are provided, so the description carries the full behavioral burden. It clearly discloses the two operating modes (compute vs verify), which is meaningful behavioral context, but says nothing about input format expectations, error/validation behavior, or performance. Adequate but not rich for an annotation-free 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?

Two tight clauses: purpose first, then a mode-by-mode breakdown. Well front-loaded and low-waste. The parenthetical '(RS485 毕设必备)' is decorative filler that adds no operational value.

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

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

An output schema exists, so return values need not be described. For a two-parameter, no-annotation tool, the description covers the core decision (compute vs verify) adequately. The remaining gap is the hex_frame format convention, which matters for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It fully explains the 'check' parameter semantics (compute vs verify), which is good, but leaves 'hex_frame' format unspecified — an agent cannot tell whether to pass spaced hex, continuous hex, or with/without prefix, nor whether CRC bytes are included. Partial compensation.

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

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

States a specific verb pair (计算/校验) and a precise resource (Modbus RTU CRC16), so an agent immediately knows this is a checksum utility. It does not explicitly distinguish itself from nearby siblings like modbus_parse or frame_parse, but the resource is narrow enough to be unambiguous.

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

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

The description explicitly routes the two modes: check=False computes CRC over the data portion, check=True verifies a complete frame (data+CRC). This is clear when-to-use guidance for each branch. It lacks any exclusion or pointer to sibling tools for related tasks.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the output semantics for both normal and exception frames, which is useful, but a pure parser has little side-effect profile to reveal and the description says nothing about input expectations (raw hex, CRC included or not) or error handling on malformed frames.

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 sentences with the core purpose front-loaded and the usage trigger trailing behind it. No filler, though the parenthetical exception-code list is slightly long for the value it adds over the output schema.

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

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

An output schema exists, so return-value detail is not owed, and the description covers purpose, the exception-handling branch, and the usage trigger. The remaining gap is input-format specification, which matters for a tool whose only job is to accept a frame.

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

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

Schema description coverage is 0% for the single parameter hex_frame, so the description must compensate and it does not. It refers to a 'frame' generically and adds no syntax guidance such as whether the CRC bytes should be included, byte order, or whitespace tolerance, leaving the caller to guess what a valid value looks like.

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 ('解析 Modbus RTU 帧') and enumerates the two branches it handles: normal responses decoded into register/coil values, and exception responses (function code |0x80) mapped to codes 01-06 with troubleshooting advice. It is clearly more specific than a generic parser, but it never names the nearest siblings (modbus_crc, frame_parse) so the agent must infer the boundary itself.

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 triggering context: use it when the slave 'should respond but doesn't, or returns a frame you can't read.' That is a clear when-to-use. It offers no exclusions or named alternatives (e.g. modbus_crc for CRC computation, frame_parse for non-Modbus frames), so routing is only partially resolved.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses per-sentence XOR checksum validation, that failed frames are explicitly flagged as untrustworthy rather than silently misinterpreted, and that non-NMEA lines are flagged and skipped. Missing only limits, but the key correctness/error-handling behavior is disclosed.

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

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

Front-loads purpose, then supported types and output fields, then a runnable example, then the two behavioral caveats. Every line adds value and nothing is redundant.

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

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

An output schema exists so return values needn't be detailed, yet the description still summarizes emitted fields (UTC, lat/lon, fix quality, sats, HDOP, speed, date). Combined with the behavioral notes, it is sufficient for a single-parameter parser; only edge conditions like mixed valid/invalid input handling are implicit.

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

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

Schema coverage is 0% for the single 'text' parameter, so the description must compensate and largely does — it defines the input as the full raw NMEA string and supplies a literal example, removing ambiguity about format.

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 (NMEA 0183 语句) and enumerates the exact supported sentence types (GGA/RMC/GSA/GSV/VTG/GLL). An agent can distinguish this from sibling parsers like modbus_parse, frame_parse, or analyze_log without opening any schema.

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

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

Explicitly instructs how to feed the tool ('把模块吐出来的整段原始数据直接贴进来' — paste the whole raw module output) and provides a concrete literal example call. It gives clear context but does not contrast with alternative parsers or state when NOT to use it.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses the failure mode and diagnostic insight (pull-up requirement) and that output is a complete list, but omits anything about the scan's timing, bus/port acquisition behavior, or error signaling.

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?

Well front-loaded: purpose first, then the diagnostic caveat. Both sentences earn their place without padding, though the emphasis styling on the pull-up tip is slightly heavy for the space.

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

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

An output schema exists so return values needn't be explained, and the description covers purpose and a failure mode adequately. However, with three fully undocumented parameters and no usage routing versus sibling scan tools, it is only minimally 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 0% and the description explains none of the three parameters (bus, port, baudrate). The names are somewhat self-evident, but for a hardware scan tool the meaning of 'port' and the interaction between bus/port is left entirely undocumented.

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: performs 1-Wire Search ROM, lists each device's 64-bit ROM code, and resolves family codes to device names. The '1-Wire' qualifier implicitly separates it from i2c_scan/spi_scan siblings, though it never names them explicitly.

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

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

The only context offered is a troubleshooting hint for when nothing is found (missing 4.7k pull-up). It never says when to choose this over i2c_scan/spi_scan or what prerequisites exist, so the agent must infer selection from the bus name 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?

With no annotations, the description carries the full burden and does meaningful work: it discloses auto-detection across GNU ld / Keil / IAR, that unrecognized input is reported rather than guessed, and the crucial 'inferred' symbol-size caveat (may be overestimated). It omits any note on performance or file-size limits but the interpretive caveat is genuinely valuable.

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 purpose, then format support, then a copyable example, then usage, then a caveat. Dense but every line contributes; the embedded code example is slightly awkward as prose but 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?

An output schema exists, so return-value formatting need not be explained. The description still covers supported formats, detection failure behavior, usage context, and result interpretation, leaving only the undocumented top_n parameter as a 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 description coverage is 0%, so the description must compensate. It shows a path example (parse_map("build/app.map")), which helps for the required param, but top_n is never explained — its meaning (top N largest symbols?) and role must be guessed from the title alone.

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

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

States a specific verb+resource (parse .map file) and enumerates the concrete outputs: section occupancy (Flash/RAM), symbol table, and suspicious large symbols. An agent can immediately distinguish this from the other 60+ analysis tools, none of which target map files.

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 use-case framing in "when RAM blew up / which big array eats stack," which routes the agent correctly. It stops short of naming alternatives or stating when NOT to use it (e.g., vs sibling symbol_lookup), so it does not reach 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?

No annotations are provided, so the description carries the full burden. It discloses that the content is derived from header comments, implying read-only documentation retrieval. However, it does not explicitly state read-only behavior, side effects, or failure conditions. Adds some context but not comprehensive.

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

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

Two compact sentences, front-loaded with purpose and then parameter sourcing. Every clause 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?

An output schema exists, so the description need not detail return values. It explains the content source and where to obtain the parameter. Minor gaps remain around error handling or alternatives, but it is complete enough for a simple getter with output schema support.

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 one parameter and 0% schema description coverage, the description compensates by stating the origin of 'name' (from peripheral_api_list). It does not add format, constraints, or examples, leaving some ambiguity about valid values.

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

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

States a specific verb (get) and resource (full text of a single driver's peripheral initialization requirements) and names the source (*_port.h adaptation layer comments). It explicitly distinguishes itself from the list sibling by noting that 'name' comes from peripheral_api_list.

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

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

Provides clear context: use this after peripheral_api_list to fetch full text for a given name. The parameter sourcing is stated. No explicit when-not or alternative tools are mentioned, but the dependency is clear.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses the kind of content returned (peripheral assignments and init-order constraints), but says nothing about the 'bus' filter behavior, result scope, or any operational constraints.

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 clauses, front-loaded with the resource definition followed by the usage trigger. No wasted wording.

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

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

An output schema exists, so return values need not be described, and the content scope is reasonably conveyed. But the sole input parameter is undocumented in both schema and description, and no annotations exist, leaving the definition incomplete for correct invocation.

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

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

There is one parameter ('bus') with 0% schema description coverage, and the description never mentions it or its filtering semantics. The description therefore fails to compensate for the schema gap; an agent cannot tell what 'bus' filters by.

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 (peripheral API usage knowledge: which peripherals each driver occupies like I2C1/TIM1/UART2 and init-order requirements) and an intended use. It does not explicitly distinguish itself from the sibling peripheral_api_get, 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?

It gives a concrete when-to-use: porting drivers or troubleshooting 'peripheral configured but can't read data'. However it names no alternative (e.g., peripheral_api_get) and gives no when-not guidance, leaving routing to inference.

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

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

With no annotations, the description carries the full burden and does so well: it enumerates the classes of problems detected (nonexistent pin function / hallucinated wiring, double-occupied functions, SWD repurposing, remap-bank mismatch, non-5V-tolerant pins, ESP32 hard constraints like flash-reserved/input-only/strapping) and the warning behavior for reusing board-occupied pins. An output schema exists, so return values need not be described. No performance or error behavior is disclosed.

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

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

Front-loaded with purpose, then worked examples, then optional-parameter behavior, then the detection list, then the usage mandate. Dense but every sentence adds information; slightly long, though none of it 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 moderate-complexity validation tool with an output schema, the description covers purpose, all three parameter formats, detection scope, and the precondition for use. Little an agent needs to invoke it correctly is missing; only alternative-routing and error behavior are absent.

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

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

Schema coverage is 0% and the nested pins object has no per-key documentation, so the description must compensate — and it does, giving the exact expected format for each parameter: mcu as "stm32f103c8t6", pins as {"PA9": "USART1_TX", ...} (pin→AF-function map), and board as an optional name like "bluepill".

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: checks whether MCU pin assignments conflict, with a parenthetical scoping the knowledge source (built-in datasheet-level AF mapping). This clearly distinguishes it from lookup siblings pinmap_list/pinmap_get, which merely retrieve mappings.

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 prescribes when to use it: '写代码分配引脚之前必须先过一遍' (must run before writing pin-assignment code). It also notes board is optional and why to supply it (onboard-peripheral occupancy triggers warnings). It does not name sibling alternatives or state when-not-to-use, 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?

No annotations are provided, so the description carries the full burden. It discloses what the output contains (mux map, caveats, conflict hints), which is genuinely useful, but it never states that this is a side-effect-free read operation or how large/verbose the raw JSON may be.

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 sentences, purpose front-loaded, then usage conditions. No wasted phrasing; the only minor cost is that the parameter format is left unstated.

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

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

An output schema exists, so return values need not be explained, and the description still summarizes the payload. With one simple param and clear triggers, it is nearly complete — the gap is the undocumented 'mcu' value format.

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

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

Schema description coverage is 0% and the single required 'mcu' parameter has no documentation in the schema or the description. The text says '指定 MCU' but gives no format or naming convention, so an agent must guess the acceptable identifier.

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: outputs the raw pinmap JSON for a specified MCU, and enumerates the returned content (full pin mux map + caveats + common conflict hints). This clearly separates it from the sibling checkers (pin_check) and listers (pinmap_list).

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

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

Gives two explicit trigger conditions ('after pin_check reports an error', 'to show the user the mapping basis') and names the sibling pin_check as the alternative. No explicit 'when-not' clause, but the context is unambiguous.

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

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

No annotations are provided, so the description carries the full burden. It does not state that this is a read-only lookup with no side effects, nor whether the list is static or reflects a live/local index. For a zero-parameter enumeration tool the behavior is largely self-evident, but the disclosure is thin.

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

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

Two short sentences, front-loaded with what is listed and followed by the practical usage cue. No redundant restatement of the title or schema, and nothing filler.

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

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

An output schema exists, so return values need no explanation, and with zero parameters the description is nearly sufficient for correct invocation. The one gap is the unspecified relationship to pinmap_get for retrieving details on a listed model.

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

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

The tool takes no parameters, so there is nothing to document and the schema imposes no ambiguity; a baseline 4 applies. The description adds no parameter-related content, but none is needed.

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 clear verb+resource: lists the MCU models contained in the pin knowledge base. An agent can tell it apart from generic list tools like board_list or component_list, but it never contrasts itself with the closest sibling, pinmap_get, which presumably retrieves the pin map for one model.

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 positions the tool relative to a named sibling: use it before pin_check to verify whether a model is supported. That is real when-to-use guidance, though it gives no when-not condition or mention of pinmap_get as the follow-up step.

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

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

No annotations are supplied, so the description carries the full behavioral burden. It does disclose a real operational trait — an optional pyocd dependency — which is genuinely useful, but it says nothing about whether the probe is a read-only enumeration, whether the call can hang on missing hardware, or what happens when no probe is attached.

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

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

Two short sentences plus a dependency note; the capability is stated first and the usage trigger second. Nothing is padded, though the dependency clause is appended rather than integrated.

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

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

An output schema exists, so return values need no explanation, and with zero parameters the only real gaps are behavioral (failure modes, hardware prerequisites). The description covers purpose, a usage trigger, and a dependency, which is nearly sufficient for this simple enumeration tool.

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

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

The tool takes zero parameters, so the baseline of 4 applies: there is no parameter semantics to explain, and the description correctly adds none.

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 (probe/探测) plus two concrete resources: connected debug probes (DAPLink/ST-Link/J-Link) and the target chip, which is more specific than a generic 'list probes'. It does not, however, distinguish itself from overlapping siblings such as flash_tool_detect or chip_info, so it falls short of a 5.

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

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

Gives an explicit triggering condition: call this first when flashing fails or the target chip cannot be found. That is a clear and actionable 'when to use', but no exclusive condition or named alternative (e.g. flash_tool_detect) is offered for the non-failure path.

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

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

With no annotations, the description carries the full burden and does well: it discloses the detection mechanism, the scope limit ('只探一层，不递归'), and what it returns conceptually (构建方式与常见坑). It does not discuss permissions or failure modes when no marker file matches, which keeps it short of a 5.

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

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

Three tight clauses: what it does and how, when to run it, and its scope boundary. Front-loaded, no filler, and the non-recursion limitation is placed right where an agent would look for 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?

Return values need not be spelled out since an output schema exists, and the description still sketches them. Covers mechanism, ordering, and scope. The only real gap is the undocumented 'path' parameter.

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

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

The single 'path' parameter has 0% schema description coverage and the description never mentions it — no statement that it defaults to '.', nor whether it accepts relative or absolute paths. With low coverage the description needed to compensate and does not.

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 (识别/identify) and resource (工程目录归属生态) and even enumerates the exact marker files it keys on, which pins down the mechanism. This clearly distinguishes it from siblings like ecosystem_list and ecosystem_get, which enumerate ecosystems rather than detecting one from a directory.

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 triggering condition ('拿到别人的工程压缩包、或不知道从哪下手时先跑这个'), which is strong routing guidance. It stops short of naming an alternative tool or a when-not-to-use case, so it is clear context without 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?

With no annotations, the description carries the full burden and largely meets it: it discloses the default drop location (<数据根>/reports/), a no-clobber policy, and the exact escape hatch (overwrite=True + confirm=True). It does not mention permissions, error conditions, or size limits, but the safety-relevant write behavior is well covered.

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 core purpose in a bolded first line, then layers data-source and overwrite rules in short paragraphs. Every sentence carries information; the only mild redundancy is restating the value proposition ('毕设报告、工单、给同事看').

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

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

An output schema exists, so return-value explanation is unnecessary, and the description still covers data sources, output location, and overwrite semantics. The undocumented tail_lines parameter and absent error/edge-case notes keep it from being fully complete.

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

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

Schema coverage is 0%, so the description must compensate. It explains fname (from sessions_list), handle (active session), the mutual default behavior, out_path (default report dir), and the overwrite/confirm pairing. Only tail_lines is left undocumented, a small remaining gap.

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

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

States a specific verb (导出/export) and resource (串口会话/serial session) plus the concrete artifact produced (Markdown 交付报告 with 故障分析 + raw log). This clearly separates it from siblings like serial_session_log (logging) and analyze_log (analysis-only).

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 ('调完一次问题' – after completing a debugging session) and enumerates data-source selection rules (handle vs fname vs auto-pick single log). It does not explicitly state when to prefer a sibling tool over this one, 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?

With no annotations, the description carries the full burden and does so richly: it explains that RCC_RSR flags are cumulative (only cleared by RMVF or power loss), warns against misreading simultaneous bits, discloses that clear_flags is irreversible/destructive and gated by an isolation layer requiring confirm=True, and lists which connection actions self-set flags to distinguish real resets from read noise.

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?

Content is front-loaded with purpose before the ★ behavioral sections, and every section earns its place given the tool's complexity. It is long and somewhat repetitive in the flag-action examples, but the length is largely justified by the operational subtleties.

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

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

An output schema exists so return-value explanation is unnecessary; the description fully covers purpose, usage routing, the destructive/irreversible nature of clear_flags, the confirm gating, and the cumulative-flag caveat. Nothing essential for a correct invocation is missing.

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

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

Schema coverage is 0%, so the description must compensate. It richly documents clear_flags (irreversible, needs confirm), then_reset (only meaningful when clear_flags=True, default True), and confirm, but never explains the 'sn' parameter. Three of four parameters get strong semantics, which is substantial compensation.

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

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

The description states a specific verb and resource ('读复位原因（RCC_RSR 标志）与内核运行状态') and immediately scopes it ('走 hotplug：不复位、不停内核'), which distinguishes it from reset/flash siblings. An agent can tell exactly what it does without opening the schema.

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

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

It names the concrete question this answers ('板子为什么自己重启了', watchdog issues) and gives an explicit when-not/alternative path: it explains that 'normal' connection resets the target and halts the kernel, so hotplug is mandatory. The clear-then-reproduce-then-read workflow is spelled out.

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

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

With no annotations, the description carries the full burden and does a good job: it discloses the critical behavioral limitation that a successful send only confirms bytes left the bridge, not that the peer received them, and warns the message prints in output. It does not cover error behavior, baudrate effects, or DE timing failures, 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?

Front-loads the action in the first sentence, then uses a clear boundary section. It is a bit verbose with emoji/markdown emphasis and a note that the limitation is printed in output, which overlaps with output schema, but overall structured and not wasteful.

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

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

An output schema exists, so return values need not be explained, and the description adds the key caveat about verification limits. It is missing preconditions and parameter guidance, but for a tool whose parameter names are mostly self-explanatory (data, baudrate) and with an output schema, the main completeness gap is moderate.

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

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

Schema description coverage is 0% and there are 6 parameters (bus, data, port, de_ms, newline, baudrate). The description mentions 'bytes' and DE direction timing but does not document what any parameter means, defaults, or formats. This leaves an agent unable to correctly populate parameters such as de_ms or newline.

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 (send bytes) and a specific resource/mechanism (the bridge's RS485 transceiver), and clarifies the bridge handles DE direction timing. This is clearly distinguished from serial_send (generic serial) by the RS485-specific framing.

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 explains a capability boundary and hints that link verification requires the peer to respond (read via serial_read) or scope inspection. However, it does not explicitly state when to choose rs485_send over serial_send, nor any preconditions (e.g., must serial_open first, bus/port 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses experimental status (⚠ 实验性), the firmware prerequisite, and that failures return troubleshooting guidance, but says nothing about blocking behavior, expected duration, or permissions. Adequate but not rich.

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

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

Front-loads the purpose and experimental warning, then covers prerequisites, parameters, and failure behavior in a compact block. Each sentence carries information; only minor tightening is possible.

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

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

An output schema exists so return-format explanation is unnecessary, and prerequisites/usage are covered. However, for a 3-parameter tool at 0% schema coverage, leaving 'seconds' undocumented means an agent cannot learn the read duration semantics from anywhere.

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

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

Schema description coverage is 0%, so the description must compensate. It explains cbuffer (control block index, default reads all channels) and probe_serial (specify when multiple debuggers), adding real meaning, but the third parameter 'seconds' is left entirely undocumented in both schema and description.

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

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

States a specific verb+resource ('通过 pyocd 的 RTT 通道读目标板调试日志') and adds differentiating scope: faster than UART and does not occupy the serial peripheral, which distinguishes it from serial_read siblings. An agent can tell what this does and how it differs without opening the schema.

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

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

Gives a clear prerequisite (firmware must integrate a SEGGER RTT control block) and a next-step routing hint ('建议先 probe_list 确认调试器'), plus an implicit contrast with UART. It stops short of stating explicit when-not-to-use conditions or naming a specific alternative tool for the fallback case.

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

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

No annotations are provided, so the description carries the full behavioral burden for a state-mutating tool. It notes the port is released, but says nothing about whether the handle becomes invalid, whether close is idempotent, what happens to in-flight reads/writes, or what error surfaces for a bad handle.

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

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

Two short sentences, action first, rationale second — front-loaded and waste-free. Slightly terse for a mutation tool, but nothing is 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?

An output schema exists, so return values need not be explained, and the description covers the basic purpose and resource-release benefit. However, with zero annotations and an undocumented parameter, it leaves the mutation semantics and handle provenance under-specified.

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

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

Schema description coverage is 0% and the single 'handle' parameter is undocumented in the schema. The description never explains which handle value is expected (e.g., one returned by serial_open), so it fails to compensate for the coverage gap.

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

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

States a specific verb and resource (close the serial port handle), which is unambiguous and clearly the inverse of the sibling serial_open. It does not explicitly name the sibling, so differentiation comes from the verb rather than routing language.

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

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

Gives a clear usage context — close after debugging finishes so the port is released — which tells the agent when this tool is appropriate. It stops short of naming alternatives or stating what happens if the handle is left open, but the intended timing is explicit.

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

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

No annotations are provided, so the description carries the burden — and it discloses non-obvious behavior: the tool not only enumerates ports but also probes chip identity and emits driver recommendations. It is implicitly a non-destructive read, though that is never stated outright.

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 compact sentences, front-loaded with what it lists, then the value-add, then the call trigger. 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?

Zero parameters, an output schema that covers return values, and a simple read operation — the description supplies exactly what an agent needs to select and invoke it correctly, with the extra chip/driver detail as a bonus.

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

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

The tool takes zero parameters, so there is nothing to misinterpret; baseline 4 applies. Schema coverage is 100% and no parameter semantics are needed.

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 (列出系统可用串口) and then extends it with concrete added capability — recognizing CH340/CP2102/FT232 USB-serial chips and suggesting drivers. This cleanly distinguishes it from sibling read/write tools like serial_open, serial_read, and driver_list.

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

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

Gives an explicit trigger scenario: 'when the board is not visible in the serial port list, call this first.' That is a real when-to-use cue, but no alternatives or exclusions are named (e.g., when to prefer driver_list or probe_list instead).

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