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

No annotations are supplied, so the description carries the full burden. It usefully discloses mode routing, the 20s default timeout, and multi-device targeting, but says nothing about the risk profile of arbitrary command execution (installs, keyevents, process kills), permission/prerequisite requirements, or what happens on timeout.

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

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

Front-loaded one-line summary followed by an args list that is easy to scan, with no filler. The Args formatting is somewhat verbose relative to the content but every entry adds usable detail.

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

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

An output schema exists, so return values needn't be explained, and all parameters plus both execution modes are covered. Given this is an unrestricted command-execution tool with no annotations, the missing risk and prerequisite context is the main 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%, yet the description documents all four parameters with concrete example values and clarifies that device_serial should be sourced from adb_list_devices. It stops short of describing timeout-expiry behavior or output capture for the command itself.

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

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

States a specific verb and resource: execute an ADB shell command or host ADB operation on a connected device. It also disambiguates from the sibling adb_list_devices by explaining where device_serial comes from, so an agent can place it among the adb/serial/toolchain tools.

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

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

Gives clear selection logic between the two modes: is_shell=True runs `adb shell <command>` and False runs `adb <command>`, each with concrete example commands. It explains when device_serial matters (multiple devices connected) but offers no when-not guidance or explicit alternatives among siblings.

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

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

No annotations are provided, so the description carries the full burden. 'List' reasonably conveys a read-only, non-destructive operation, but the description says nothing about failure modes (no devices, adb daemon not running) or permission/auth requirements.

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

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

A single front-loaded sentence with no filler; the resource enumeration is the only elaboration and it is useful for distinguishing device classes.

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 a parameterless discovery tool is simple. Only the lack of preconditions and failure behavior keeps it from full marks.

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 schema has nothing to document and the baseline is 4. The description adds no parameter detail, which is appropriate here.

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

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

The description states a specific verb ('List') and resource ('connected Android phones, tablets, or embedded Android boards via ADB'), which is unambiguous. It implicitly separates itself from the generic adb_command sibling by being a discovery-only operation, though it never names the alternative.

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

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

Usage is only implied: an agent can infer this is the discovery step before issuing adb_command calls. There is no explicit statement of when to prefer this over adb_command or what prerequisites (USB debugging enabled, adb server running) must hold.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the core side effect ('connect'), but says nothing about whether the connection is torn down afterwards, whether pairing/bonding is required, what happens on timeout, or what platform permissions (e.g. Linux bluez) are needed. For a tool that opens a live radio connection, that leaves significant gaps.

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

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

One front-loaded purpose sentence followed by a tight per-argument block. Every line adds information; there is no restatement of the tool name, no filler, and the highest-value fact (what gets listed) is first.

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

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

Because an output schema exists, the return shape need not be explained, and the two parameters are well covered. What remains missing is the behavioral envelope an agent needs before calling a connection-opening tool: pairing state, disconnect semantics, and failure/timeout behavior.

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

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

Schema description coverage is 0%, but the description fully compensates for both parameters: 'address' is explained as a MAC (Linux/Windows) or a UUID (macOS) with an example, and 'timeout_sec' is framed as a connection timeout with its 10.0 default. This is exactly the OS-dependency detail the bare schema cannot convey. Only minor edge cases (invalid address, timeout bounds) are unmentioned.

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

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

The description gives a specific verb and resource pair: 'Connect to a BLE device and list all GATT Services, Characteristics, and their properties.' That is clearly distinct from ble_scan_devices (discovery) and ble_read_write_characteristic (value I/O). It does not explicitly name or rule out those siblings, 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?

Usage is only implied: the agent must infer that this is the inspection step before ble_read_write_characteristic. There is no statement about when to prefer this over ble_scan_devices, no prerequisite that the device be advertising or already known, and no exclusion 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 supplied, the description carries the full burden and does meaningful work: it explains write-with-response vs write-without-response, read-back-after-write behavior, and the read-only mode when write_data is None. It omits failure modes, permission/pairing requirements, and whether a write is persistent or reversible on the peripheral, which matter for a mutating operation.

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

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

The purpose sentence is front-loaded and the per-argument list is compact with no filler. The structure is scannable, though the 'Args:' block format is slightly verbose relative to what a one-line-per-param summary would need.

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 correctly omitted, and the description covers mode selection, encoding, and timing for a seven-parameter tool. What remains missing is operational context for a write-capable BLE tool: error behavior, characteristic-writability requirements, and connection lifecycle 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, and it documents all seven parameters with meaning beyond bare titles: address accepts a MAC or UUID, encoding lists accepted values and a hex example ('01 FF 0A'), and the boolean flags are explained semantically rather than restated. Minor gap: no indication of whether characteristic_uuid accepts short-form handles or only full 128-bit UUIDs.

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 resource: 'Read from and/or write to a GATT Characteristic on a BLE peripheral.' An agent can distinguish this from ble_scan_devices and ble_inspect_gatt by the read/write action. It stops short of naming those siblings or explicitly excluding inspection/discovery use.

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

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

Usage is implied by the write_data semantics ('If None, performs a read-only operation'), which effectively describes two modes of invocation. However, there is no explicit when-to-use guidance, no mention of prerequisites (pairing, characteristic writability), and no routing to ble_inspect_gatt when the characteristic UUID 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 supplied, so the description carries the full behavioral burden. It discloses the scan duration window (1.0–20.0s) and the case-insensitive substring matching behavior, which is useful, but says nothing about adapter/permission prerequisites, whether the call blocks for the full timeout, or what happens when no devices are found.

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

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

One front-loaded purpose sentence followed by a compact Args block; nothing is padded or repeated. The docstring-style parameter list is slightly redundant in formatting but each line adds information not present in the schema.

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

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

An output schema exists, so return values need not be explained, and both parameters are covered. However, for a hardware-dependent scan with no annotations, the description omits operating prerequisites (BLE adapter present/enabled, permissions) and blocking semantics, which are exactly what an agent needs to call it confidently.

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 largely does: timeout_sec is given a range and default, and name_filter is explained as a case-insensitive substring matched against either device name or address — details absent from the bare 'string'/'number' schema. Minor gaps remain on out-of-range timeout handling and filter-no-match behavior.

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

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

States a specific verb and resource ('Scan for nearby Bluetooth Low Energy (BLE) devices') and even enumerates target device classes (ESP32, nRF52, sensors, beacons). It does not explicitly distinguish itself from sibling BLE tools such as ble_inspect_gatt or ble_read_write_characteristic, so the agent must infer that this is the discovery entry 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?

Usage is only implied: scanning is obviously the discovery step before GATT inspection, but no when-to-use or when-not-to-use statement is given, and no sibling tool is named as the alternative. The only real guidance is that name_filter narrows results, which hints at the broad-scan-then-narrow pattern without stating 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 supplied, so the description carries the full burden. It usefully explains the warm-up rationale (auto-exposure settling), but omits important behavior: whether the image is returned inline when output_path is null, whether the device can be busy, or what permissions are needed.

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

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

Front-loads the one-line purpose, then a short use-case sentence, then an Args block. Every sentence carries information and nothing is padded.

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

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

Solid for a four-parameter capture tool with no annotations; since an output schema exists, return values don't need explaining. The one missing piece is the relationship between output_path being null and how the image reaches the caller.

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 for all four params: the Linux /dev/videoN path form, the PNG output file, the 'WxH' resolution format with examples, and the purpose of the default warm-up frame count.

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+resource ('Capture a photo from a connected Webcam or USB Microscope') and immediately frames the target domain ('inspect physical hardware'), which separates it from screen-oriented siblings such as take_screenshot and list_media_devices.

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?

Names three specific situations to use it: verifying an LED, reading an OLED/LCD, and inspecting solder joints and jumpers. It gives clear positive guidance but never states exclusions or points at an alternative (e.g. use any other tool for screen capture).

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

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

With no annotations, the description must carry the behavioral burden, and it does list the exact checks performed plus the intent of returning install hints and recommendations. It never states that the tool is read-only/non-mutating, whether it requires no elevated privileges, or how slow a full host sweep may be — meaningful gaps for a tool that shells out to many utilities.

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

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

The purpose is front-loaded in the first sentence and the remaining detail is a numbered list of exactly what is checked, with no filler. The parenthetical utility and group names are high-value specifics rather than padding.

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

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

For a zero-parameter diagnostic with an output schema (so return shape needn't be explained), the description covers scope and intent well. The only missing piece an agent would want is the safety/cost profile — that it makes no changes and may take a while — plus a note on how it relates to check_toolchains.

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 and the schema is empty, so there is no parameter meaning to add; baseline 4 applies. The description correctly offers no parameter discussion and instead describes the fixed set of checks.

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 scope ('Run a full host readiness & prerequisite check for hardware tooling') and enumerates the three inspection areas, so the agent knows exactly what the tool does. It does not, however, distinguish itself from the sibling check_toolchains, which clearly overlaps with check area #2 (embedded toolchains).

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

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

Usage is only implied: the closing line about returning 'actionable recommendations so the AI can guide the user if anything is missing' suggests diagnostic/troubleshooting use. There is no explicit when-to-use statement, no when-not-to-use, and no pointer to check_toolchains for a narrower toolchain-only check.

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 establishes the read-only, inspection nature of the call and the exact set of toolchains probed, but it does not say whether missing toolchains cause an error or a negative result, whether detection is PATH-based, or whether the call is slow (it may spawn several subprocesses). An output schema exists, so return shape need not be described.

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

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

Two sentences: the purpose statement is front-loaded, and the enumeration of arduino-cli, pio, idf.py, esptool, openocd, dfu-util, avrdude, and picotool is high-value content rather than filler. Nothing is redundant.

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

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

For a parameterless read-only probe with a defined output schema, the description supplies nearly everything an agent needs: what is checked and which binaries count. It stops short of stating failure semantics and how results relate to the related prerequisites/compile tools, so it is not fully complete, but it is adequate for the tool's complexity.

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. The description correctly implies no arguments are needed, and the enumerated toolchain list helps the agent interpret what will be reported without adding parameter detail that does not exist.

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

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

The description gives a specific verb ('Check availability and versions') and a specific resource ('embedded toolchains on the host machine'), then enumerates the exact binaries inspected. It is clear about scope, but it does not explicitly differentiate itself from the sibling check_prerequisites, which an agent could plausibly pick instead.

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

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

Usage is only implied: the word 'Check' and 'on the host machine' suggest a pre-flight diagnostic before compiling or flashing, but no when-to-use condition, prerequisite, or alternative tool is named. The presence of check_prerequisites and run_custom_toolchain among the siblings makes the absence of routing guidance a real gap.

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

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

No annotations are supplied, so the description carries the full disclosure burden, and it omits the traits that matter most: the schema default action is 'compile_and_upload', meaning a bare call physically rewrites device firmware, yet nothing warns that this is a mutating, hardware-altering operation. It also says nothing about serial-port contention (relevant to find_port_occupiers/free_serial_port), what happens on compile failure, or whether aborting is possible. Only the 300s default timeout and extra_args pass-through are disclosed.

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

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

The purpose is front-loaded in one sentence, followed by a clean per-argument list that is justified given the total absence of schema descriptions. No filler or restated boilerplate, though the multi-line nested bullet for board_fqbn_or_env is slightly heavier than needed.

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 argument documentation is thorough for a 7-parameter tool. But for a hardware-mutating operation with zero annotations, the definition should say more about risk, required port for upload, and failure behavior; as written an agent could trigger a flash unintentionally via the default action.

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 Args block does real work: it explains that project_path may be a directory or a sketch file, that toolchain accepts 'auto' with concrete detection sources, and that board_fqbn_or_env is interpreted differently per toolchain (FQBN vs -e env vs target chip). The gap is interaction semantics — whether port is mandatory for 'upload' and how action and toolchain constrain one another are left implicit.

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

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

The opening sentence names a specific action ('Compile and/or flash firmware') and resource ('to a microcontroller'), and enumerates the three supported toolchains (Arduino CLI, PlatformIO, ESP-IDF). That is far more specific than the sibling names alone, though it does not explicitly distinguish itself from run_custom_toolchain or esptool_command, which cover adjacent ground.

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

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

Usage is implied through the 'action' values and the documented 'auto' detection logic (looks for platformio.ini, CMakeLists.txt, or .ino files), which helps an agent pick a toolchain. However, it never says when to prefer this over run_custom_toolchain, esptool_command, check_toolchains, or check_prerequisites, nor does it state prerequisites such as requiring the port before an upload.

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 disclosure burden; it does surface that this tool can erase flash and write raw firmware, which signals destructive capability. It says nothing about irreversibility of erase, permission/driver requirements, serial-port exclusivity (relevant given siblings like free_serial_port and find_port_occupiers), or whether chip='auto' performs detection.

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

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

A single front-loaded capability sentence followed by a compact Args block maps directly onto the parameters; each line earns its place. The baudrate line mostly repeats the schema default, a small redundancy, but overall there is no filler.

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

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

An output schema exists, so return values need not be explained. For a seven-parameter tool with destructive operations and zero annotations, the definition is only partly complete: it lacks prerequisite/safety context (port availability, chip auto-detection behavior, consequences of erase_flash) that an agent needs before invoking it.

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

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

Schema description coverage is 0%, and the description compensates well by documenting all seven parameters, including conditional semantics for flash_offset and binary_path and example values ('/dev/ttyUSB0', '0x10000'). It is not perfect: the chip argument's valid values are left open with 'etc.', and the operation list omits stating that the schema default is 'chip_id'.

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

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

The first sentence states a specific verb (run esptool) plus the resource and enumerates concrete capabilities: chip inspection, MAC read, flash erase, raw binary write. It is clear what the tool does, though it never names the closest sibling (compile_and_flash) to distinguish this raw-tool escape hatch from the higher-level flashing workflow.

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

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

Usage is implied by the operation list and by conditional notes (flash_offset and binary_path apply only when operation='write_flash'), which is genuinely helpful. However, there is no explicit statement of when to pick this over compile_and_flash, no prerequisites such as the port being free or a driver being installed, and no warning about which operations are risky.

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 supplied, the description carries the full burden. The word 'Check' implies a read-only inspection, but it never explicitly states that it is non-destructive, nor whether elevated privileges (lsof/fuser often need root) are required. It does add helpful context about the error conditions that motivate the call.

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, zero waste, with the core purpose front-loaded and the usage trigger immediately after. Nothing is redundant or padded.

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

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

An output schema exists, so return values need not be explained, and for a one-parameter diagnostic the description covers purpose and trigger adequately. The remaining gaps are permission requirements and the natural follow-up tool, which are minor but notable for a troubleshooting utility.

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 required 'port' parameter, so the description must compensate. The example '/dev/ttyUSB0' does convey the expected path format, which is meaningful added value, but nothing is said about accepted path variants or whether a short name like 'ttyUSB0' works.

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 pair ('Check which processes are currently locking/using a serial port') and gives a concrete example path. It is clearly distinct from list_serial_ports (enumeration) and free_serial_port (remediation), 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?

It gives an explicit triggering condition: use it when seeing 'Port busy' or 'Resource temporarily unavailable' errors. It does not mention what to do next (e.g. free_serial_port) or when this is unnecessary, so the routing guidance is clear but not complete.

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

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

With no annotations, the description must carry the safety burden. It usefully discloses the SIGTERM versus SIGKILL behavior via force, but it does not mention permissions, irreversibility, process-state loss, or what happens when no locking processes exist.

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

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

The description is front-loaded with the action and purpose, followed by a compact Args block. Every sentence carries useful information with no waste.

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

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

The description covers the action and both parameters, and the output schema handles return values. For a destructive process-termination tool with no annotations, it still omits safety prerequisites and permissions, leaving a meaningful completeness 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 explain both parameters. It does: port is defined with device-path examples, and force is defined by the exact signal change from SIGTERM to SIGKILL.

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: terminating processes that lock a serial port, with the intended outcome of flashing or monitoring. It is clearly distinct from generic process tools, but it does not explicitly position itself against siblings such as find_port_occupiers or kill_process.

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 context for use: freeing a serial port for flashing or monitoring. However, it does not say when not to use it, whether to check occupiers first, or how it relates to the sibling tools find_port_occupiers and kill_process.

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

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

With no annotations, the description carries the full burden. It does disclose a useful behavioral trait ('Always reads back current pin states') and explains the read-vs-write relationship, but it omits critical behaviors: what happens when writing while bits are set to input, whether pin state persists after the call, error modes for invalid URLs, and whether the FTDI device is locked during the 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?

The core read/write purpose is front-loaded in the first sentence, and the Args block is tightly scoped to one line per parameter. Minor redundancy exists where defaults are restated in both prose and schema, but nothing is wasted.

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

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

An output schema exists, so return values need no explanation, and parameter meaning is well covered. However, for a tool that directly mutates hardware pin states with zero annotations, the missing disclosure of side effects, device exclusivity, and failure modes leaves a meaningful gap.

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

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

Schema coverage is 0%, so the description must compensate, and it largely does: it explains ftdi_url's PyFtdi URL format and default, decodes direction_mask as an 8-bit bitmask with 1=Output/0=Input and worked examples (0xFF, 0x01), and gives write_value's range and optionality. It falls short only on edge cases such as an output bit with a null write_value or out-of-range integers.

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

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

The first sentence names a specific verb pair and resource: reading or writing GPIO pins on an FTDI USB bridge, with concrete chip examples (FT232H, FT2232H). This clearly separates it from sibling transfer tools like ftdi_spi_transfer and ftdi_i2c_transfer without requiring the schema to be opened.

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

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

Usage is implied by the functional description of GPIO access, but it never states when to choose this over sibling tools such as ftdi_spi_transfer or toggle_dtr_rts, nor does it state prerequisites like exclusive device access. The agent must infer the use case from the tool's name and purpose 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 supplied, so the description carries the full burden; it does disclose the required hardware class and that the operation probes for addresses, implying a non-destructive read, but it never states that explicitly, nor whether the bus is left in a particular state, how long a scan takes, or what happens when no devices respond.

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

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

One front-loaded purpose sentence followed by a compact Args block; every line carries information. Only minor redundancy in restating a default the schema already declares.

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 no explanation, and both optional parameters are documented with examples and defaults. Only edge-case behavior (empty scan results, timing, bus error handling) is left unaddressed, which is acceptable for a tool this simple.

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 supply parameter meaning and it does: ftdi_url is explained as a PyFtdi URL with a concrete example ('ftdi:///1'), and frequency_hz is given units plus the 100kHz standard-mode framing of the default. It would rate higher if it warned about invalid frequencies or URL forms.

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 and resource ('Scan an I2C bus ... for active slave addresses') and identifies the required hardware (FT232H/FT2232H MPSSE bridge), which plainly separates it from ftdi_i2c_transfer. It stops short of naming that sibling explicitly, so the distinction must be inferred from the verb.

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?

A bus scan is a recognizable discovery step, so its usage is implied, but the description never states when to use it versus ftdi_i2c_transfer or scan_hardware_bridges, nor does it mention prerequisites such as an attached bridge or that the bus should be idle.

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

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

With no annotations at all, the description carries the full behavioral burden, and it does disclose useful traits: the write-only mode via read_length=0, the clock-speed knob, and default FTDI URL. It does not describe failure behavior (NACK, missing bridge, wrong address) or whether a combined write_hex+read_length call performs a repeated-start write-then-read, which is the key operational ambiguity for an I2C transfer.

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

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

The purpose is front-loaded in one sentence, followed by a scannable Args block with no filler. The Args list duplicates schema field names on purpose (needed given 0% schema coverage), so it earns its space, though it could be tightened.

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 parameter surface is well covered. However, for a hardware-touching I2C transfer tool with zero annotations, the definition omits the transfer semantics (combined write-then-read) and any expected failure modes, leaving the agent to guess on non-trivial invocations.

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 largely does: every one of the six parameters is explained with format hints (7-bit address, 8-bit register, hex byte string '01 FF', default URL and frequency). The remaining gap is the interaction between register_addr, write_hex, and read_length — the description lists them but does not spell out the sequencing when all three are supplied.

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

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

The first sentence names a specific verb pair (read and/or write), the resource (registers on an I2C slave device), and the transport path (FT232H/FTDI bridge). It is clearly distinguishable from ftdi_spi_transfer, but it never names ftdi_i2c_scan, so the agent must infer that scanning is a separate tool.

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

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

Usage is only implied: 'read and/or write' plus 'read_length: 0 for write-only' tells the agent how to configure a read vs. a write, but there is no statement of when to prefer this tool over ftdi_i2c_scan or when a transfer is inappropriate. No prerequisites (device present on bus, FTDI driver, permissions) are mentioned.

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

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

With no annotations at all, the description carries the full behavioral burden and leaves key traits unstated: it never says combatting-safety is not the issue but whether the call opens/claims the device, whether CS is asserted/released automatically, what happens on device-not-found or bus error, or whether a write-only call (read_length=0) is the norm. The MOSI/MISO semantics are useful, but operational behavior around hardware contention and failure is undisclosed.

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 one-line purpose is front-loaded and the Args list is terse and scannable, with no filler prose. The example embedded in the write_hex line does double duty without adding bulk.

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 all six parameters are addressed. However, for a hardware-mutating transfer tool with zero annotations, an agent still cannot tell from the description whether the call claims/releases the FTDI device, how CS behaves, or how errors surface, which is meaningful missing context.

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% (only titles and defaults), and the Args block compensates well: it defines write_hex as a hex byte string with a concrete example, explains read_length as MISO bytes read after the write, constrains cs to 0..3 and mode to 0-3, and gives units/defaults for freq_hz. Only minor gaps remain, such as the expected hex format edge cases (spaces, '0x' prefix, odd length).

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 and resource ('SPI exchange/transfer') and the exact hardware path ('FT232H/FTDI MPSSE bridge'), which cleanly separates it from the ftdi_i2c_* and ftdi_gpio_control siblings. It stops short of naming an alternative outright, so it is clear but not perfectly differentiated.

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

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

There is no explicit statement of when to use this versus ftdi_i2c_transfer or the serial tools, and no prerequisites (device must be enumerated, MPSSE mode required, bus wiring) are mentioned. The only usage signal is the parenthetical example of reading JEDEC Flash ID, which implies a context rather than stating one.

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

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

With no annotations, the description carries the full disclosure burden. It usefully explains the signal semantics (SIGKILL vs graceful SIGTERM), which is real behavioral value, but omits the destructive and irreversible nature of the operation, permission requirements, what happens if a process_name matches multiple processes, and whether child processes are affected.

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

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

Front-loaded one-line purpose followed by a compact Args block; every line carries information. The doubled verb 'Stop/terminate' is minor redundancy but the structure is easy to scan.

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, but for an unannotated destructive process-killing tool the definition should state safety implications and name-matching behavior. Those omissions leave it adequate but not complete for its risk level.

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 supply all parameter meaning, and it defines each of the three: pid, process_name (used when pid is absent), and force as SIGKILL vs SIGTERM. Gaps remain around what happens if both or neither of pid/process_name are supplied and how name matching is resolved, which keeps it below a 5.

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

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

States a specific verb and resource (stop/terminate a running process) plus the two selection modes, PID or process name, so the agent knows exactly what the tool acts on. It never contrasts itself with siblings such as list_processes, start_process, or free_serial_port, so the differentiation must be inferred from the name alone.

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

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

There is no when-to-use guidance, no mention of alternatives (e.g. free_serial_port for port occupiers, list_processes to find a PID first), and no stated preconditions such as needing the PID to exist. The only selection hint is the parenthetical that process_name applies if pid is not specified, which is parameter routing rather than usage 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 disclosure burden, yet it only restates the output contents. It does not say whether enumeration is a passive read, whether the OS may prompt for media permission, or whether the list reflects only currently connected devices. For a hardware-scanning tool this leaves real behavioral gaps.

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

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

A single front-loaded sentence that identifies the action and the scope immediately, with the parenthetical examples earning their place by clarifying what counts as an audio device. No filler or redundancy.

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

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

An output schema exists, so return structure need not be described, and a zero-parameter read tool has little surface area to cover. The one thing an agent might want — permission behavior or whether devices must be active to appear — is unaddressed, keeping it short of a 5.

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 clarify; the baseline of 4 applies. No parameter detail is needed or missing.

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

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

States a specific verb ('List') and resource ('connected audio input/output devices ... and video/webcam devices'), and enumerates the device classes (microphones, speakers, webcams). That enumeration distinguishes it from the other list/scan siblings such as list_serial_ports, ble_scan_devices, and sigrok_scan_devices without needing 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 says what is returned but never states when to call it, e.g. as a discovery step before record_audio_sample or capture_camera_snapshot. No alternatives or exclusions are named, so the agent must infer that this is the enumeration tool for media hardware.

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 results are capped by a default limit of 50, which is genuinely useful, but never states that this is a read-only/non-destructive operation and doesn't flag that hitting the limit silently truncates 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?

Purpose is front-loaded in one sentence, followed by a short use-case line and a compact Args block. The Args section slightly duplicates the schema's defaults but earns its place by adding the case-insensitive/substring semantics.

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 description isn't needed, and both parameters are explained despite 0% schema coverage. Given the tool's simplicity and the absence of side effects, 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 coverage is 0%, so the description must compensate, and it largely does: filter_name is documented as a case-insensitive substring matched against either process name or cmdline, and limit as a maximum with a stated default. Only the boundary behavior of limit (truncation, not error) is left implicit.

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

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

States a specific verb and resource ('List running OS processes') plus the optional filtering dimension. An agent can immediately distinguish it from mutation siblings like start_process and kill_process 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 concrete motivating scenarios (checking for IDE serial monitors, minicom, screen, openocd, gdb, emulators), which is real when-to-use guidance. It stops short of naming alternatives — notably find_port_occupiers, which overlaps for the serial-port case — and offers no 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 must carry the behavioral load. It does disclose the substantive behavior — passive scanning plus classification of attached devices and chip hints — but never states that the operation is read-only/non-mutating, whether it requires serial-port permissions or group membership, or whether the scan is slow. Useful context, but incomplete for a no-annotation tool.

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

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

Front-loaded with the core action in the first sentence, followed by output detail and then a compact Args block. Every line carries information; the only minor redundancy is restating parameter names already present in the schema, which is justified because the schema lacks descriptions.

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 both parameters are documented in the description. What remains missing is environmental framing — cross-platform behavior and permission requirements — which matters for a hardware-scanning tool but is a moderate rather than fatal 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 has to compensate, and it does: both booleans are explained in the Args block, including the non-obvious meaning of hide_phantom_ttys (unpopulated Linux /dev/ttyS* ports with 'n/a' hwid) and the default of True. Actual path formatting or symlink semantics could go further, but this is well above the bare schema.

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

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

States a specific verb and resource — 'Scan and list all USB/Serial ports connected to the computer' — and goes on to enumerate what the listing surfaces (VID/PID, manufacturer, serial number, board/UART chip hints). This is clearly distinguishable from siblings such as find_port_occupiers or scan_hardware_bridges, which address different concerns.

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

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

Usage is only implied: the mention of board/chip hints ('ESP32, Arduino, Pico, FTDI') suggests this is a discovery step before flashing or connecting, but the description never says when to call it or when to prefer an alternative. No exclusions or prerequisites are given.

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

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

No annotations are supplied, so the description carries the full behavioral burden. It discloses the output target (host speakers, not the MCU) and the duration range, but says nothing about whether the call blocks for the tone's duration, whether it can be interrupted, or what happens if no audio device is available.

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 use case are front-loaded in the first sentence, with parameter detail following in a conventional Args block. Every line carries information, though the docstring-style formatting is slightly more verbose than a single tight sentence would be.

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

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

For a simple two-parameter, zero-required-parameter tool with an output schema, the description covers purpose, use case, units, defaults, and one bound. What remains missing is invocation timing (blocking vs. fire-and-forget), which matters somewhat given durations up to 10 seconds.

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 largely does: frequency is defined in Hz with a default of 440 (A4) and duration is given an explicit valid range of 0.5 to 10.0 seconds with a default of 2.0. The only gap is the absence of a permitted frequency range.

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 ("Play a pure sine wave test tone on the host speakers") and immediately scopes it with the concrete use case of testing I2S/ADC mic sensors on an MCU. That parenthetical also distinguishes it from neighboring audio tools like set_audio_volume and record_audio_sample.

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 when-to-use condition: verifying that an MCU mic/sensor path is actually capturing audio. It stops short of naming alternatives or stating when not to use it (e.g., instead of set_audio_volume for real playback), 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 zero annotations, the description carries the full behavioral burden and does reasonable work: it discloses the hard timeout ceiling (max 60.0), default durations, the specific crash signatures it recognizes, and the side effect of pulsing DTR/RTS to reset the board. It does not cover what happens when the port is already occupied, whether the port is released afterward, or permission/error behavior.

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

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

Front-loaded summary followed by a clean per-argument list; every sentence is functional. Minor redundancy between the crash-dump sentence in the summary and the stop_on_crash_dump argument text, but nothing wasteful enough to hurt usability.

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

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

For a 7-parameter read tool with an output schema (so return values need not be described) and no annotations, the description covers behavior, limits, and side effects adequately. The remaining gap is failure modes—busy port, missing device, permission errors—which matter given the presence of free_serial_port and find_port_occupiers siblings.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: all seven parameters are explained with concrete port path examples, the default baud rate, the timeout max, regex-or-substring semantics for stop_on_pattern, and what stop_on_crash_dump and reset_before_read actually do. This adds substantial meaning the bare schema lacks.

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

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

The description opens with a concrete verb+resource+scope: 'Open a serial port and read stdout/logs for timeout_sec seconds', and adds a distinct secondary capability ('Automatically detects MCU crash dumps'). It is clearly separable from siblings like send_serial_command and list_serial_ports without needing their schemas.

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

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

Usage is implied by the crash-dump framing (use this to capture boot/crash output), but the description never states when to prefer it over send_serial_command or how it relates to list_serial_ports / free_serial_port. No exclusion or prerequisite guidance is given, so the agent must infer 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 reasonably well: it discloses that recording blocks for the requested duration, that the .wav defaults to a temporary file, that the return includes a signal-level analysis (RMS/dBFS), and how to pick an ALSA device. It omits failure behavior when no capture device exists and any permission/device-busy caveats, which matters for a hardware-touching 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?

It is front-loaded with the verb, resource, and output format, then follows with a scoped Args block, so the agent can stop reading once it has what it needs. The usage-suitability sentence sits between the summary and the args, which is slightly better placed at the end, but nothing is genuinely wasted.

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

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

For a 5-parameter, zero-annotation hardware tool, the definition covers purpose, every parameter's semantics and defaults, and the analysis it returns, with no output-schema gap to fill. The remaining hole is operational: no stated behavior on a missing or busy capture device, and no note on whether the recording can be interrupted.

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 fully compensate, and it does: it gives the duration range (1 to 30, default 5.0), the unit for sample_rate (Hz, default 16000), the mono/stereo meaning of channels, the temp-file default for output_path, and concrete ALSA device string examples ('default', 'hw:0,0', 'plughw:1,0'). This is meaning well beyond the bare schema titles and defaults.

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

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

The description gives a specific verb and resource — record microphone audio for `duration_sec` seconds and analyze RMS/dBFS — plus a concrete framing ('verifying hardware audio output (speaker -> host mic)') that separates it from siblings like play_test_tone or set_audio_volume. An agent can identify this as the capture/analysis tool without inspecting 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 supplies clear usage contexts (speaker-to-mic loopback verification, testing a USB microphone), which is genuine when-to-use guidance. It stops short of explicit exclusions or naming alternatives such as play_test_tone or list_media_devices, so routing between the audio siblings still requires 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 are provided, so the description carries full behavioral burden, yet it never says whether the command runs through a shell, whether execution is blocking, what happens on timeout or non-zero exit, whether output is captured, or what privileges/working state it mutates. For a tool that executes arbitrary CLI commands, these omissions are significant. The only behavioral hint is the default 300-second timeout, which merely restates the schema.

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

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

The purpose sentence is front-loaded and the examples earn their place by making the tool's scope concrete. The Args block largely re-lists schema fields and the trailing whitespace/newlines are wasted, but overall the text is short and scannable.

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

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

An output schema exists, so return values need not be explained, but for a command-execution tool with zero annotations the description should still cover shell semantics, exit-code/timeout behavior, and side effects. Those gaps, plus the unresolved overlap with sibling build/flash tools, leave the definition under-specified for its risk profile.

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 is the only source of parameter meaning, and it does at least gloss all three parameters (full command string, execution directory, timeout default 300). But it adds little beyond the schema titles and defaults: it never explains what a null working_directory resolves to, whether relative paths are allowed, or what timeout expiry does to the running process.

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

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

The description opens with a specific verb+resource ("Run a custom build/flash CLI command") and backs it with concrete examples (make flash, west build, cargo embed, openocd), so an agent immediately knows the tool's domain. It does not distinguish itself from closely related siblings such as compile_and_flash, esptool_command, adb_command, or start_process, leaving overlap unresolved.

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 examples implicitly signal when this tool applies (custom or unsupported build/flash toolchains), which is adequate implied usage. However, there is no explicit when-to-use/when-not-to-use statement and no pointer to the alternative siblings that do similar things, so the agent must infer boundaries on its own.

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 supplied, the description carries the disclosure burden. It helpfully states the concrete return artifacts (FTDI URLs like 'ftdi://ftdi:232h/1' and /dev/i2c-*, /dev/spidev*, /dev/gpiochip* nodes), which signals a read-only enumeration. However, it omits whether the scan enumerates from sysfs or actively probes hardware, whether root/udev permissions are needed to see /dev nodes, and what happens when nothing is found.

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

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

Two sentences, both earning their place: the first establishes scope and supported chips, the second lists return formats. Purpose is front-loaded and the return examples are compact rather than verbose.

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 is not obligated to explain return values, yet it still enumerates the key ones, which is a bonus for a discovery tool. The remaining gap is environmental context (driver/permission prerequisites, empty-result behavior) rather than missing core information.

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 declares zero parameters (100% coverage), so there is nothing for the description to disambiguate. The baseline for a 0-parameter tool is 4, and nothing in the text confuses or overstates the argument surface.

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 ("Discover") with a concrete resource: connected USB-to-GPIO/I2C/SPI bridges, naming the exact chip families (FT232H, FT2232H, CH341) and Linux bus device classes. It is clear what the tool does, but it never names distinguishing boundaries against siblings like sigrok_scan_devices or list_serial_ports, so an agent must infer the split.

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

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

Usage is only implied: an agent can reason that this is a discovery step preceding ftdi_* or serial calls, and that it covers a broader device set than list_serial_ports. There is no explicit when-to-use statement, no exclusion of the overlapping sigrok_scan_devices / adb_list_devices tools, and no prerequisites such as driver or udev requirements.

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 usefully explains that window_title focuses a target window before sending and that delay_ms controls inter-key timing, but it does not disclose failure behavior, permission or accessibility requirements, or what happens if the window title is not found.

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

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

The definition is front-loaded with the purpose and then cleanly lists the three arguments. Every sentence is relevant, and the Args structure makes the parameter details easy to scan without unnecessary 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?

For a three-parameter keyboard automation tool with an output schema already present, the description covers the essential call semantics: target window, focus behavior, key syntax examples, and timing. The main remaining gap is behavioral safety and failure-mode context, which is notable because no annotations are supplied.

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 supply parameter meaning, which it does well. It gives key-combination examples for keys, explains that window_title is an optional substring used for focusing, and clarifies that delay_ms is the delay between key events with a default of 50.

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: send keyboard shortcuts or keystrokes. It also specifies the target scope, the active window or a named application window, which clearly distinguishes it from the serial, process, BLE, and hardware-control siblings.

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

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

The description implies when the tool is useful by saying it sends hotkeys to the active window or a specified window. However, it gives no explicit when-to-use guidance, exclusions, or alternatives, so the agent must infer the appropriate context.

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

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

With no annotations, the description carries the full burden; it does disclose the key behavioral traits of a hardware write tool, namely that data is transmitted, a line ending is appended, and an optional timed listen follows with a default of 1.5s and 0 to skip. It omits operationally important context such as exclusive port access/port-busy handling (relevant given the find_port_occupiers and free_serial_port siblings), whether the port is opened and closed per call, and what happens on write failure.

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

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

The purpose is front-loaded in a single sentence and the parameter detail is organized as a clean Args list, so each line earns its place. Minor verbosity in restating defaults already present in the schema, but nothing is wasted or buried.

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 transmission semantics and all parameter interactions well. The remaining gap is environmental: no mention of port exclusivity or contention behavior, which matters for a tool sitting alongside port-occupier helpers.

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%, yet the Args block documents all six parameters with meaning, defaults, and concrete examples ('/dev/ttyUSB0', 'AA 55 01 FF', 115200). It also supplies the enum-like value sets the schema lacks ('utf-8', 'ascii', 'hex' for encoding; '\n', '\r\n', '\r', '' for line_ending) and the cross-parameter rule that line_ending is ignored when encoding='hex', which is meaning the schema cannot convey.

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

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

The first sentence gives a specific verb and resource ('Send a command string or raw hex bytes to a serial port') plus the optional read behavior, so an agent immediately knows this is an outbound write to a serial device rather than a log reader like read_serial_logs. It does not explicitly name that sibling or state how it differs from read_serial_logs, so it falls short of full sibling differentiation.

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

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

Usage is implied rather than stated: the text mentions 'optionally read the response' and documents read_response_sec as '0 to skip reading', which tells the agent how to control the read side. There is no explicit when-to-use/when-not guidance nor any named alternative (e.g., use read_serial_logs for passive monitoring, free_serial_port when the port is busy).

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 the volume range 0–150, the tri-state mute semantics (True/False/None), and default target/device behavior, but it omits side effects such as whether setting volume unmutes, permission requirements, or reversibility.

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 in the first sentence, then uses a compact Args list. Every line maps to a parameter or scope detail, with no redundant prose.

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

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

The tool is simple with four optional parameters and an output schema present, and the description covers parameter semantics and defaults. It could be stronger by noting prerequisites or failure behavior, but it is complete enough to invoke correctly.

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

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

Schema description coverage is 0%, so the description is the only source of parameter meaning. It documents all four parameters: target values, volume percentage range and example, mute three-state semantics, and optional device_id default, adding substantial meaning 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?

States a specific verb and resource: set volume or mute state for speaker/sink or microphone/source. It is clear enough to identify the action, though it does not explicitly distinguish itself from neighboring media tools such as play_test_tone or record_audio_sample.

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 identifies the two target types and the default device behavior, implying when to use sink vs source. It does not state when to use this tool versus other media tools or mention prerequisites such as PipeWire/PulseAudio availability, leaving usage guidance 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?

No annotations are supplied, so the description carries the full burden. It does disclose one genuinely useful behavioral rule — 'samples ... Ignored if `time_ms` is set' and 'Overrides `samples` if provided' — which the schema cannot express. But it never mentions hardware prerequisites, whether the call blocks for the capture duration, exclusive device access, or that output_file writes to disk.

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

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

The core purpose sentence is front-loaded and the Args block is ordered sensibly with the mutually exclusive samples/time_ms pair adjacent. It reads as a docstring lifted wholesale, repeating parameter names the schema already lists, but given 0% schema coverage that repetition is largely load-bearing rather than waste.

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

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

An output schema exists, so return values need not be described. For a 7-parameter hardware tool with zero annotations, however, the definition leaves out prerequisites (driver availability, prior device scan), expected capture latency, and error modes such as a busy or missing analyzer — all information an agent needs before invoking it.

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 argument block is doing real work: it gives samplerate as a Sigrok-style string with concrete examples ('1m', '4m', '24m'), the driver default and its hardware meaning ('fx2lafw' for 8-ch 24MHz analyzers), channel syntax ('D0=sda,D1=scl'), and full protocol_decoder spec strings for uart/i2c/spi. This meaningfully exceeds the bare schema types. A point is withheld because decoder parameter vocabulary is only shown by example, not enumerated.

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

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

The description opens with a specific verb and resource: 'Capture digital signal pulses from a Logic Analyzer and optionally decode protocols (UART, I2C, SPI, PWM)'. That clearly separates it from the scan-only sibling sigrok_scan_devices and from the FTDI serial/I2C tools. It stops short of explicitly naming an alternative, but the capture-plus-decode scope is unmistakable.

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

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

There is no when-to-use guidance: nothing says to run sigrok_scan_devices first, nothing states that sigrok-cli and a compatible driver must be installed, and nothing warns that the analyzer is exclusively held during capture. The only conditional logic given is argument precedence (time_ms overrides samples), which is parameter behavior, not tool-selection 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 load: it discloses that it shells out to sigrok-cli and enumerates supported driver families, which is useful context. It does not state what a failed/empty scan looks like, whether it can hang waiting on USB enumeration, or that it requires the sigrok-cli binary present.

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

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

Two short sentences, front-loaded with the action and target device classes, followed by the concrete driver coverage. No filler or restated 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?

A zero-parameter discovery tool with an output schema does not need return-value documentation, so the description is nearly sufficient as-is. The only meaningful gap is the missing prerequisite that sigrok-cli must be installed and the implied handoff to sigrok_capture_and_decode.

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 clarify beyond the schema; the baseline for a parameterless tool applies. The driver list is informative context rather than parameter documentation.

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

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

States a specific verb (scan) plus the resource (connected Logic Analyzers, Oscilloscopes, Multimeters) and names the underlying mechanism (sigrok-cli). This clearly separates it from siblings like ble_scan_devices, scan_hardware_bridges, and sigrok_capture_and_decode.

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 purpose implies this is a discovery step preceding sigrok_capture_and_decode, but the description never states that relationship or when-not to use it. No alternatives or prerequisites (e.g. needing sigrok-cli installed) are named, so the agent must infer the workflow.

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

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

With no annotations at all, the description carries the full burden, and it does disclose the key async behavior: background=True returns a PID immediately while background=False blocks up to timeout_sec. It does not mention that this executes arbitrary code on the host, what permissions or environment the child inherits, or whether the process survives the session — meaningful omissions for an unrestricted execution 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?

The purpose is front-loaded in one sentence, followed by a compact per-parameter list with no filler. The Args block is repetitive in form but each line earns its place by adding constraints the schema lacks.

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 parameter behavior is well covered. However, for a host-level process launcher with zero annotations, the description should say more about the risk/permission model and the lifecycle of the spawned process than it does.

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

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

Schema description coverage is 0%, so the description must compensate, and it documents all five parameters. It adds real meaning beyond the schema types: 'command' may be a bare executable name or a full command line, 'args' is only needed if not already in command, and 'timeout_sec' applies only when background is False. Only cwd is described minimally.

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

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

The first sentence states a concrete verb and resource (start a process/CLI utility) and adds the scope qualifier 'on the host machine'. It is clear what the tool does, but it never distinguishes itself from siblings like run_custom_toolchain, esptool_command, or adb_command, which could also launch executables, leaving ambiguity for an agent choosing between them.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative. The only usage-adjacent information is embedded in the parameter docs (background vs. foreground with timeout), which describes how to call it rather than when to prefer it over run_custom_toolchain or the vendor-specific command tools.

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

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

With no annotations supplied, the description must cover behavior itself, and it does disclose the output format (PNG) and the default temp-file behavior for output_path. It says nothing about screen-recording permissions, multi-monitor selection, or what happens for an invalid or out-of-bounds region, which are real failure modes for a capture 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?

The opening sentence is front-loaded with the core capability and the region format, and the use-case sentence earns its place by grounding when to invoke it. The Args block is slightly redundant in restating parameter names but adds real meaning beyond the bare 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 two-parameter, zero-annotation tool with an output schema covering return values, this is nearly sufficient: capture modes, use cases, both parameter formats, and the default output location are all present. The remaining gap is environmental context such as permission requirements or monitor targeting.

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

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

Schema description coverage is 0%, so the description carries the parameter burden, and it does document both arguments: region syntax with a concrete example ('0,0,800,600') and output_path semantics including the temp-file default. It stops short of stating whether parent directories are created or how negative or oversized regions are handled.

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 and resource ('Capture a screenshot') and distinguishes two modes: full screen versus a specific region with the x,y,width,height format. It does not differentiate itself from the sibling capture_camera_snapshot, which an agent could easily confuse with it.

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 concrete use contexts ('inspect application windows, error dialogs, or logic analyzer/oscilloscope GUIs'), which tells the agent when this tool is the right choice. It offers no exclusions or contrast with the closest sibling, capture_camera_snapshot, so the selection guidance is incomplete 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?

No annotations are provided, so the description carries the full burden. It does disclose the important physical side effect (pulsing DTR/RTS hard-resets the microcontroller) and that pulses have a configurable duration, which is real behavioral value. It does not state whether the serial port is opened/exclusively locked, what happens if the port is busy or missing, whether the line states are left asserted after the call, or whether the reset is disruptive to an active session.

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

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

The structure is well front-loaded: one sentence of purpose followed by a compact per-argument list, with the mode semantics nested under 'mode'. It is appropriately sized for a five-parameter hardware tool. Minor waste: 'default 100ms' restates schema information already present.

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

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

With five parameters, no annotations, and an output schema that covers return values, the description supplies what the structured fields cannot: the mode vocabulary and the physical consequence of each mode. It is nearly complete; the missing pieces are port-exclusivity/prerequisite notes and error-condition behavior, which matter for a tool that manipulates a live hardware port.

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

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

Schema description coverage is 0% and the schema carries only bare titles, so the description must compensate — and it largely does, documenting all five parameters and, critically, supplying the enumerated mode values that the schema declares only as a free-form string with a default. Gaps remain: no valid range or constraints for pulse_ms, and no statement that dtr/rts are ignored outside 'custom' mode.

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

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

The opening sentence names a concrete verb and resource ('Control DTR and RTS lines on a serial port') plus the two concrete intents (board reset, bootloader entry). It implicitly separates this from data-oriented siblings like send_serial_command or esptool_command, but never names an alternative, so sibling differentiation is left to inference.

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

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

Usage guidance exists at the mode level: each of 'reset', 'esp32_bootloader', and 'custom' is explained with the condition that selects it, which is genuinely useful. However there is no guidance on when to choose this tool over siblings such as esptool_command, send_serial_command, or ftdi_gpio_control, and no stated prerequisites (e.g. the port must not be held by another process, despite a free_serial_port sibling existing).

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