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 destructive scope ('drop all captured lines') and a genuinely non-obvious invariant ('sequence numbers keep increasing'), which is useful. However, it says nothing about whether the port must be open, whether previously returned lines are invalidated, or any 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?

One tight, front-loaded sentence with no filler. The trailing sequence-number clause is terse to the point of being slightly cryptic, but it earns its place as behavioral information.

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

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

An output schema exists, so return values needn't be explained. For a destructive, unannotated buffer-clearing tool the description covers the essentials but omits port-open prerequisites and the effect on subsequent read_lines calls.

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 'port' parameter, so the description must compensate. It only says 'for a port' without clarifying whether this is a name from list_ports, a device path, or a handle, leaving the key ambiguity unresolved.

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

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

States a specific verb+resource: 'Drop all captured lines for a port.' An agent can distinguish this from read_lines or close_port. It stops short of explicitly naming the sibling it complements (read_lines), so it is clear but not fully 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?

No when-to-use or when-not-to-use guidance. The reader must infer from the name that this discards buffered data rather than closing or reading the port. Nothing warns about the interaction with read_lines or about when clearing is appropriate.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose the key side effect ('stop capturing'), which is genuine value beyond the schema, but it never covers permissions, reversibility, or error behavior when the port is not open or already closed.

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

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

One short, front-loaded sentence with no filler; the action and its prerequisite are both stated immediately. It is arguably too terse rather than padded, which is a completeness issue rather than a conciseness flaw.

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

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

An output schema exists, so return values need no explanation, and the one-parameter surface is small. What remains missing is the port identifier's expected form and failure behavior when no port is open; otherwise the definition is sufficient for correct invocation.

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

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

Schema description coverage is 0% for the single 'port' parameter, so the description must compensate. It implicitly establishes that the value is the identifier/handle returned by open_port, but adds no format, casing, or example detail, leaving the compensation partial.

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

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

States a specific verb (close) and resource (port) and ties it to its counterpart by name ('a port opened with open_port'), which lets an agent place it precisely in the port-lifecycle family without opening any schema. It is unambiguous against siblings like list_ports, read_lines, or reset_stm32.

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

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

The phrase 'opened with open_port' gives clear context for when this tool applies, i.e. after a successful open_port. It does not state exclusions (e.g. behavior when no port is open, or whether auto-closing on exit exists), so it stops short of the explicit when/when-not guidance needed for a 5.

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

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

With no annotations, the description carries the full burden. It does disclose a real side effect (closes any open session on the port first) and a safety gate (confirm=true), which is meaningful beyond the schema. However, it omits whether flash is erased, what happens on failure, and any timing or timeout expectations for a hardware write.

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 clauses with zero filler; the core action is front-loaded and the side effect and confirmation requirement follow compactly. 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 not be described. The description covers the operation, its destructive side effect, and the confirmation gate, which is most of what an agent needs. The gap is failure/erase semantics for a hardware write.

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

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

Schema description coverage is 0% across 6 parameters, so the description must compensate and only partly does: it implies firmware_path (.bin), port (open session on the port), and confirm=true. The baud, chip, and address parameters are left entirely unexplained in both schema and prose.

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 (Flash), resource (.bin firmware), and target (ESP32-family chip) plus the underlying tool (esptool). This cleanly distinguishes it from the sibling flash_stm32, so an agent can route by chip family without opening either schema.

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

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

The ESP32 scoping implies when this tool is appropriate versus flash_stm32, but there is no explicit when/when-not guidance, no mention of session state prerequisites beyond the internal close-session behavior, and no stated alternatives. Usage is inferable rather than stated.

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

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

No annotations exist, so the description carries the full burden, and it does disclose meaningful behavior: the backing tool (st-flash), a side effect (the target is reset afterward), and a safety gate (confirm=true, which the schema only defaults to false). It stops short of describing failure modes, whether the flash erases the chip, or permission 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?

Two sentences, zero filler, front-loaded with the action and followed by the two most operationally important facts (side effect and required flag).

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 destructive write operation with no annotations, the description covers the command, one side effect, and the confirmation requirement, but leaves the address parameter and error/recovery behavior undocumented.

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

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

Schema description coverage is 0%, so the description must compensate, and it only partially does: it implies firmware_path is a .bin and confirms the confirm=true value. The address parameter (default 0x08000000) and its format or purpose are never explained.

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

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

States a specific verb and resource (flash a .bin to an STM32 over ST-Link) and names the underlying command (st-flash). An agent can distinguish this from flash_esp32 and reset_stm32 from the description alone.

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

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

Usage context is implied by the description, and it states the confirm=true prerequisite. It never says when to prefer this over flash_esp32, nor does it mention prerequisites such as a probed/connected ST-Link via probe_stlink.

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

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

No annotations are provided, so the description carries the full disclosure burden. It does add one genuinely useful nuance — that the 'open' status reflects whether *this server* holds the port, not OS-level state — but it says nothing about error behavior, enumeration scope, or permission requirements for a listing call that an agent must treat as safe.

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 sentence that is front-loaded with the verb and resource and then lists the returned fields. Every clause earns its place with no filler.

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

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

An output schema exists, so the description needn't explain return values, yet it still enumerates the key fields to help selection. For a simple zero-parameter reader this is nearly complete; only the lack of annotations leaves safety/permission context unstated.

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

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

The tool takes no parameters (0 required, 0 total), so the schema is trivially complete and the description has nothing it must compensate for. Baseline for a zero-parameter tool applies.

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

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

States a specific verb (list) and resource (serial ports) and even names the attributes returned, so it is immediately distinguishable from mutation siblings like open_port/close_port. It does not explicitly name a sibling to contrast against, but the enumeration intent is unambiguous.

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

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

Usage is implied rather than stated: an agent can infer this is the discovery step before open_port/probe_stlink, but the description never says when to call it or what it replaces. 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?

With no annotations, the description carries the full disclosure burden. It usefully reveals that capture runs in the background (a persistent session that presumably lasts until close_port) and that pyserial-style URLs are accepted, but says nothing about exclusivity, resource locking, error behavior on an invalid or busy port, or permission 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 the core action first and the qualifier in a compact parenthesis. Every clause adds information; nothing is padding.

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

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

The presence of an output schema means return values need not be described, and the background-capture sentence covers the key state change. However, for a stateful connection-opening tool with zero annotation coverage, the description is thin on preconditions, failure modes, and lifecycle (when the capture stops).

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 only one of two parameters: it clarifies that 'port' accepts pyserial URLs such as loop://. Baud is untouched in the description (its schema entry has only a default of 115200), leaving half the parameter surface unexplained.

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

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

States a specific verb and resource (open a serial port) plus a distinguishing behavioral detail (starts capturing lines in the background). It clearly separates itself from close_port, list_ports, and probe_stlink by naming the open action, though it never explicitly names an 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?

No when-to-use guidance is given: the description does not say to call list_ports first to discover a valid port, does not explain what happens if the port is already open, and does not mention that read_lines/write_line depend on this call. Usage is only inferable from the tool name and sibling set.

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

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

No annotations are provided so the description carries the disclosure burden. It implies a read-only probing action and references the underlying st-info command, which adds some transparency. However, it does not state whether the probe requires an active connection, what happens if no target is attached, or the exact response shape.

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

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

Single sentence front-loading the action and enumerating the three returned fields; every clause earns its place.

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

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

An output schema exists, so return values need not be explained further. The description is complete enough for a zero-parameter probe, though it could mention connection prerequisites or error behavior for a fully self-contained definition.

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?

Zero parameters, so per the baseline this scores 4. The description correctly conveys a no-input invocation.

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

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

Clear verb+resource: 'Show the connected ST-Link target' with specific fields (chip id, flash, SRAM size). It also discloses the underlying command (st-info --probe), distinguishing it from siblings like flash_stm32, reset_stm32, or list_ports.

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 a read-only inspection use case and names the resets/flash siblings implicitly via context, but does not explicitly say when to use this versus reset_stm32 or flash_stm32. Usage is inferable but not stated.

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

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

With no annotations, the description must carry the full behavioral burden. It discloses ordering, sequence numbers, and that wait_seconds blocks briefly for fresh output (default non-blocking), which is useful. It omits critical traits: whether reading consumes/clears the captured buffer (directly relevant given the clear_buffer sibling), and how max_lines truncation behaves when the buffer holds more lines than requested.

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 return contract (what is returned, in what order) before parameter guidance, and the whole description is two short paragraphs with no filler. Slightly dense in the second sentence but every clause carries information.

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

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

An output schema exists, so return values need not be re-explained, which helps. Still, for a 5-parameter tool with no annotations and 0% schema coverage, the description leaves port and max_lines unexplained and never states whether reads are non-destructive or how they interact with the buffer's lifecycle.

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 5 parameters, so the description must compensate. It explains three of them well: grep as a regex filter with an example, after_seq as a cursor for newer output, and wait_seconds as a blocking window. The required 'port' and the impactful 'max_lines' are left undocumented, leaving a partial gap.

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

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

States a specific verb (Return) plus resource (captured lines) and adds ordering semantics (oldest first, newest last) with sequence numbers. This is clearly distinguishable from siblings like clear_buffer and write_line. It does not explicitly name an alternative, but the read semantics are unambiguous.

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

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

The second sentence gives real usage guidance for the parameters ('after_seq to fetch only output newer than your last read', 'wait_seconds to block briefly for fresh output after a command'), which implies when to use incremental reads. However, it never states when to use read_lines versus clear_buffer or how it relates to open_port, so tool-selection guidance is only implied.

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

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

With no annotations, the description carries the full disclosure burden. It usefully reveals the underlying mechanism (st-flash reset via ST-Link), implying hardware-level reset, but says nothing about side effects such as loss of running state, halting the core, or what happens if no probe is attached.

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

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

A single front-loaded sentence with no filler; the parenthetical implementation detail is compact and informative rather than redundant.

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

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

An output schema exists, so return values need not be explained. However, for a state-destroying reset operation with no annotations, the description omits prerequisites and side effects an agent would want 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?

The tool takes zero parameters, so the schema cannot be improved upon; the baseline of 4 applies. Nothing in the description needs to compensate for 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 (reset) and resource (STM32 target) plus the mechanism (ST-Link / st-flash reset). An agent can naturally distinguish this from siblings like flash_stm32 or probe_stlink, though no sibling is named 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?

No guidance on when to reset versus re-flashing, nor any stated prerequisites (e.g. that an ST-Link probe must already be connected and the target powered). Usage is only implied by the verb.

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 two useful behaviors — a newline is appended, and the port must already be open — but says nothing about whether the write blocks, what happens if the port is closed, whether output is buffered, or how errors surface.

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

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

A single front-loaded sentence with the verb first and the example trailing; nothing is wasted and the agent gets the core behavior immediately.

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

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

An output schema exists, so return values need not be explained. However, for a write tool with zero annotation coverage and zero schema description coverage, the definition omits the port identifier convention and failure behavior that an agent would need to call it reliably.

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

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

Schema description coverage is 0% across three parameters, so the description must compensate and largely does not. It clarifies that 'text' is combined with a newline, but 'port' is left entirely unexplained (port name from list_ports vs. a device path is ambiguous) and the newline parameter's configurable format is never mentioned.

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

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

States a specific verb and resource: 'Send text plus a newline to an open port'. The newline-appending behavior and the target (an open port) are both explicit, which distinguishes it from read_lines and clear_buffer. It stops short of naming a sibling tool directly, so sibling differentiation is only implicit.

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

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

Usage is implied rather than stated: describing the port as 'open' hints that open_port must run first, and the firmware-CLI example suggests a command-entry scenario. There is no explicit when-to-use guidance, no when-not-to-use, and no named alternative among the nine siblings.

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