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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description only needs to add context beyond that. It adds the local-scope detail 'on this machine' but does not disclose return contents, behavior when no ports exist, or whether virtual/composite ports are included. Consistent with annotations, but limited added context.

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

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

A single seven-word sentence with the action verb front-loaded and zero filler. Every word earns its place; nothing is redundant or extraneous.

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

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

For a zero-parameter read-only tool with full annotation coverage, the description is largely complete. The only gap is the absence of an output schema and no note on what the returned port identifiers look like (e.g., COM3 or /dev/ttyUSB0) or that they can be passed to serial_open — useful for an agent consuming the result.

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

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

With zero parameters and 100% schema coverage, the baseline of 4 applies. There is no parameter information for the description to compensate for, and describing the tool as a parameterless query is accurate.

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 ('List') with a specific resource ('available serial ports on this machine'), making the operation unambiguous. It naturally distinguishes itself from all sibling serial_* operation tools, and the 'on this machine' qualifier clarifies local scope.

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

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

No explicit when-to-use guidance, alternatives, or exclusions are given. The intended usage (discover ports before opening one via serial_open or checking serial_status) is implied by the purpose but never stated, so the agent has to infer context from the 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?

The annotations already cover read-only, idempotent, non-destructive behavior; the description adds the useful offline/no-device-connection trait. It does not disclose error behavior, how input_file vs raw_hex is resolved, or output shape, though with safe annotations this is acceptable but not rich.

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

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

A single front-loaded sentence with no filler. Every phrase adds semantic value, and the important 'offline' context is placed in parentheses without bloating the text.

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

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

The schema has four undocumented parameters and no output schema, and the description leaves input_file unaddressed and never states what result is returned. For an agent to invoke it correctly, it needs to know whether it must pass raw_hex or input_file and what the parsed output looks like.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It clarifies raw_hex as the hex response and protocol/action as selecting a YAML definition/action, but it does not explain input_file's role or the relationship between raw_hex and input_file. Meaning is partial.

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

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

The description names a specific operation (Parse), a concrete input (raw HEX response), and a resource (YAML protocol action definition), with the 'offline' qualifier distinguishing it from the live serial siblings. An agent can tell what this tool does without opening the schema.

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

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

'Offline' implies it is for parsing captured data rather than live serial traffic, but there is no explicit when-to-use/when-not-to-use wording and no named alternative tools. Usage context is present but left to inference.

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

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

Annotations already mark destructiveHint true, and the description adds precise behavioral context: the buffer is dropped, the read cursor resets, and log files are preserved. This tells an agent exactly what side effects to expect beyond the generic destructive flag.

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 tightly worded sentence front-loads the action, then clarifies a critical non-goal. There is no filler, repetition, or unnecessary information.

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

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

For a one-parameter destructive utility with no output schema, the description adequately covers what happens and what is preserved. It could be slightly more complete by noting any return value or whether the port must already be open, but these are minor gaps for such a simple operation.

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

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

Schema description coverage is 100%, and the port parameter is fully self-documented in the schema. The description adds no additional parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Drop buffered lines and reset the read cursor.' It clearly names the tool's core action and distinguishes it from read/write/log-retrieval siblings, and the added 'log files are kept' prevents confusion with any log-destructive operation.

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

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

The purpose statement makes the usage scenario inferable: call this when you need to discard buffered serial lines before continued reading. However, it does not explicitly state when to prefer this over siblings, name alternatives, or give any preconditions such as requiring an open port.

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

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

Beyond the annotations, the description discloses meaningful behavioral details: it stops the reader thread and releases the port. This gives the agent a concrete sense of side effects. It does not mention handling of buffered data or errors, but the idempotentHint annotation covers repeat-call safety, and no contradiction exists.

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

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

The description is a single tight sentence with no filler. The primary action is front-loaded, and the two subordinate effects are listed compactly. Every word contributes.

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

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

For a simple one-parameter close operation, the description combined with the schema and annotations covers what an agent needs: the action, the parameter, and the idempotence safety. It could be slightly richer around return behavior, but no output schema exists and the operation is straightforward.

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

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

Schema coverage is 100%, so the single 'port' parameter is already fully documented with a description and example. The tool description adds no additional parameter context, which is acceptable given the high schema coverage.

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 clear verb and resource: 'Close a capture session', and further specifies what that entails by stopping the reader thread and releasing the port. This clearly distinguishes serial_close from siblings like serial_open, serial_read, and serial_status.

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

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

The description implies usage: you would call this when you want to end a capture session and free the port. However, it does not explicitly say when to use it relative to alternatives like serial_open, nor does it mention prerequisites such as having an active session.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds scoping to a single day and offset-based traversal, but it does not disclose line ordering, behavior at the end of the file, or how to interpret the returned lines.

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 a single 11-word sentence with no filler, front-loading the action and resource. It earns its place and does not duplicate schema content.

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 low-complexity and the schema covers all parameters and defaults. The main gap is that, with no output schema, the description does not explicitly state the return format, though 'page through' strongly implies a list of raw log lines.

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?

All four parameters are fully described in the schema, so the baseline applies. The description's 'one day's' and 'line offset' only echo the date and offset parameters without adding new format, constraint, or interplay information.

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

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

The description uses a specific verb ('Page through'), a concrete resource ('one day's raw log file'), and a clear mechanism ('by line offset'). This makes it easy to distinguish from siblings like serial_get_recent or serial_read without opening the schema.

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

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

The paging and raw-log phrasing imply this is for reviewing historical log data, especially when older lines are needed. However, the description does not explicitly state when not to use it or name any alternative such as serial_get_recent for tail-style retrieval.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description is consistent with these. It adds behavioral context by specifying that the operation ignores the read cursor, implying it does not advance it. This is useful beyond the annotations.

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

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

The description is a single sentence, front-loaded with the primary action, and contains no redundant words. It is optimally concise.

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 tool with no output schema and rich annotations, the description covers the core behavior and the key cursor detail. It does not specify return format, but that is not required given the simplicity and no output schema. It is complete enough for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, with both port and lines having descriptive text. The tool description's mention of 'N buffered lines' maps to the lines parameter, but it adds no new semantics beyond the schema. The parameter descriptions are sufficient on their own.

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 clear verb and resource: 'Return the most recent N buffered lines'. It adds a crucial qualifier 'regardless of read cursor' which distinguishes it from other serial read operations. This is unambiguous and specific.

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 does not explicitly name alternative tools or conditions for when to use this vs. others. However, the phrase 'regardless of read cursor' implies it is appropriate when the caller does not want to disturb the read cursor, which is a clear contextual cue. But it lacks explicit exclusions or comparisons to siblings like serial_read or serial_get_log.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context beyond annotations: it discloses that a background reader is started, that data is continuously captured into a ring buffer and a daily log file, and that this is an initialization call. This is meaningful behavioral disclosure (side effects, background process) that the annotations alone do not convey. It does not mention potential failure modes or resource cleanup, but the added context is substantial.

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 with zero waste. The first sentence packs the core action and its behavioral consequences; the second sentence is a crisp, front-loaded usage directive. Every word earns its place.

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

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

For an initialization tool with 7 parameters fully documented in the schema, no output schema, and annotations covering safety/idempotency, the description is nearly complete. It explains the background reader, ring buffer, and log file, and tells the agent to call it first. The only minor gap is that it doesn't describe what the return value or success/failure signal looks like, but since there is no output schema and the tool is an open/init action, this is a small omission.

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

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

Schema description coverage is 100%, so the schema already documents all 7 parameters with descriptions and defaults. The description does not add parameter-level meaning beyond the schema, but it does not need to. Baseline 3 is correct when the schema carries the full 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?

The description states a specific verb ('Open'), a specific resource ('a serial port'), and a distinctive behavioral scope: it starts a background reader that captures incoming lines into a ring buffer and a daily log file. It also explicitly says 'Call this first,' which distinguishes it from sibling tools like serial_read or serial_status. This is a clear, non-tautological purpose statement.

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

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

The description gives explicit usage guidance: 'Call this first.' This tells the agent this is the initialization step before other serial operations. It does not explicitly name alternatives or when-not-to-use, but the sibling list (serial_close, serial_read, etc.) and the 'first' instruction make the usage context clear. A 4 is appropriate because it provides clear context but no explicit exclusions.

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

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

Annotations already communicate readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the description does not need to re-state basic risk. It adds the meaningful 'one-shot write-then-read' behavior, but it does not disclose side effects beyond the write, when the operation returns, whether it clears or consumes buffered data, or whether it leaves the port in a particular state.

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

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

The description is a single, front-loaded sentence with no filler. It states the core behavior first and then the input alternatives, making it easy to scan and parse.

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?

Despite 100% per-parameter schema coverage, this is a complex 11-parameter, destructive tool with no output schema and no return-value information. The description does not clarify relationships between parameters, how response reading terminates, what the function returns, or the constraints around using protocol versus hex. An agent would likely need additional inference or documentation 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 100%, so the baseline is 3. The description adds value beyond the schema by clarifying that the tool accepts either a hex payload or a protocol file plus action, which implies two mutually exclusive invocation modes. This is important semantic information the schema does not directly express.

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

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

The description states a specific action ('one-shot write-then-read exchange') and the two supported input styles ('hex or protocol+action from a YAML protocol file'). This makes the tool's purpose identifiable, but it does not explicitly contrast it with siblings like serial_send, serial_read, or serial_shell, so it loses the last 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?

The 'one-shot write-then-read' phrasing implies a combined query operation, and the two input modes are stated. However, there is no explicit when-to-use versus alternative tools, no statement about when hex should be preferred over protocol+action, and no mention of prerequisites such as an already-open serial port.

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?

The description states 'tail-follow semantics' and 'since the previous serial_read', implying a stateful, non-idempotent operation. However, annotations declare idempotentHint: true, which contradicts this behavior. This is a direct conflict, so the score is 1 per the contradiction rule.

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 a single, front-loaded sentence that delivers the core behavior (tail-follow) and the wait logic immediately. No fluff or redundant information; it is concise and to the point.

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

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

For a simple read tool, the description covers the essential behavior: what is returned, the tail-follow semantics, and the waiting behavior. It does not explicitly mention max_lines or what happens after a wait with no data, but these are covered by the schema. The main gap is the contradiction with idempotentHint, which is an annotation issue rather than a description completeness issue.

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 schema has 100% coverage with descriptive parameter definitions. The description adds minimal extra meaning, mostly reinforcing the wait_ms behavior ('Waits up to wait_ms for fresh data'), but does not add significant new semantic detail beyond the schema.

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

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

The description clearly states the action (return lines) and the resource (lines captured since previous call), with explicit 'tail-follow semantics' that distinguishes it from sibling read tools like serial_get_recent or serial_wait_for. The verb and resource are specific, and the stateful nature is evident.

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 to use it (to read new lines incrementally) but does not explicitly contrast with alternatives or state when not to use it. It mentions tail-follow, which hints at usage, but lacks explicit exclusions or conditions compared to other read tools in the sibling list.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful scope context — it searches 'captured history (daily log files)' rather than a live buffer — but it does not disclose details like result limiting, regex flavor, or whether matching is case-sensitive. This is comparable to a filtered-list tool where annotations carry the safety burden.

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 focused sentence with an example. The core action 'Regex-search' is front-loaded, and there is no filler or repetition of schema fields.

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

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

All five parameters are documented by the schema, annotations cover safety, and the description gives the key scope ('full captured history'). There is no output schema, so a little more detail about return shape would be helpful, and the description does not mention how the events preset parameter relates to pattern. Still, an agent has enough to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's example hints at using pattern and since_minutes together, but it does not add parameter-level meaning beyond what the input schema already provides.

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

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

The description states a specific verb and resource: 'Regex-search the full captured history (daily log files)'. The example 'find every HardFault in the past hour' makes the purpose concrete and distinguishes it from sibling serial_get_recent and serial_get_log tools, which are about retrieving logs rather than regex-searching captured history.

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 clearly implies when to use it: when the agent needs to pattern-match across persisted log history rather than inspect live or recent serial output. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a full usage guide.

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

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

The description adds meaningful behavior beyond the annotations: it explicitly discloses that the port is opened and closed on each call. It also implies no response capturing occurs by directing capturing use cases to serial_write. Annotations already signal mutation and non-idempotency, so the added port-management detail is good context.

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

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

One concise sentence carries the core behavior, the port lifecycle, and a routing hint to an alternative. Every word contributes, and the most important qualifier ('one-shot') is front-loaded.

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 tool with full schema coverage and annotations covering safety, the description adds the key missing context: port open/close behavior and when to prefer serial_write. It does not describe the return value or failure behavior, and with no output schema, that slight gap prevents 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?

Schema description coverage is 100%, so all seven parameters are already documented with types/defaults/meaning. The description adds no new parameter-level semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description names a specific action ('transmit'), a specific resource (serial port), and a specific format ('raw HEX'), while 'one-shot' clearly defines the scope. It also distinguishes itself from serial_write by noting the port is opened and closed, so an agent can tell them apart.

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 parenthetical 'use serial_write when capturing' gives an explicit alternative with a clear selection condition. The 'one-shot' phrasing further communicates this tool is for a single transmission rather than streaming or interactive sessions.

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?

The annotations already flag destructiveHint=true and readOnlyHint=false, so the description is not contradicting them. It adds the useful context that the tool runs a sequence and collects a transcript, but it does not disclose connection lifecycle, side-effect risks, or what happens on partial command 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 description is a single front-loaded sentence with no wasted words. It is concise, but the brevity comes at the cost of important context, making it slightly too sparse for a tool with 11 parameters.

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

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

Given 11 parameters, no output schema, and many similar sibling tools, a one-sentence description is insufficient. It omits usage guidance, return format, connection behavior, and meaning of several key parameters, leaving substantial gaps for an agent trying to call the tool correctly.

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

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

Schema coverage is only 55%, with several parameters lacking descriptions: commands, encoding, line_ending, startup_wait, and inter_command_delay. The description does not compensate for these gaps; it only hints at the purpose of commands via 'command sequence' and says nothing about the other under-documented parameters.

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

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

The description states a specific action: execute a one-shot command sequence over a shell-like device and collect a transcript. This distinguishes it from simpler siblings like serial_write or serial_read, though 'shell-like device' is somewhat vague.

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

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

There is no guidance about when to use this tool versus alternatives such as serial_send, serial_query, or serial_wait_for. The description implies a batch/transcript use case, but never states exclusions or when another tool would be more appropriate.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds useful context about the exact fields shown and the optional port filtering behavior. It does not contradict the annotations and goes beyond them by clarifying the output content, which is valuable for an agent deciding whether to invoke it.

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

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

The description is two sentences with zero fluff. The primary purpose is front-loaded, and the parameter usage note is concise and actionable. Every word contributes to understanding the tool's function and invocation, making it a model of efficiency.

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

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

Given the tool's simplicity (one optional parameter, no output schema, and annotations covering safety), the description is fully sufficient. It states what the tool does, the exact data returned, and how to filter. No critical information is missing for an agent to call it correctly, especially since the output format is implicitly described by listing the fields.

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 fully describes the 'port' parameter with an example. The description adds semantics by explaining that omitting the parameter lists all sessions, which is not explicitly stated in the schema. Since schema coverage is 100%, the baseline is 3, but the description enhances understanding of the parameter's optionality and behavior, earning a 4.

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

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

The description clearly states the tool's action ('Show every capture session') and specifies the data returned (state, uptime, counters, unread lines, log file path). It also implies the ability to filter by port, distinguishing it from sibling tools like serial_get_log or serial_get_recent that target specific aspects. The verb and resource are precise, making the purpose unambiguous.

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

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

The description gives a usage hint ('Omit ‘port’ to list all sessions') but does not explicitly explain when to use this tool over its siblings. With many serial-related tools available, it would benefit from stating that it provides a summary of all capture sessions, whereas other tools like serial_get_log retrieve specific logs or serial_get_recent fetch recent data. The omission of alternatives leaves the decision partly to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful behavioral details beyond those annotations: it blocks until a match, returns only once, and includes preceding context. This is relevant context that helps an agent understand execution semantics, especially the blocking and one-shot return 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?

The description is two sentences with no redundant phrases. It front-loads the primary purpose (blocking) and then succinctly lists the two matching modes and a typical use case. Every sentence earns its place and is directly informative.

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 blocking read tool with 5 optional parameters and no output schema, the description covers the essential behavior (blocking, one-shot return, context lines) and typical use case (watching boot logs). It does not explicitly describe the return format structure or behavior on timeout, but the timeout parameter is documented in the schema. The definition is sufficient for an agent to decide when and how to call it correctly.

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

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

Schema description coverage is 100% for all 5 parameters, so the schema already documents each parameter's meaning. The description mentions 'pattern' and 'events' with brief explanations, but does not add meaningful semantics beyond what the schema provides. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description states a specific verb and resource: 'Block until a line matches...' and explicitly distinguishes itself from polling alternatives with 'without polling.' It also names the two matching mechanisms (custom regex and built-in event presets), making it clear what the tool does and how it differs from the sibling serial_read/serial_search 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?

The phrase 'Ideal for watching boot logs without polling' gives a clear context for when to use this tool versus polling with other serial tools. However, it does not explicitly name alternatives or state when NOT to use it, leaving some inference to the agent. The guidance is present but not exhaustive.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the write/mutation nature is covered. The description adds the 'open capture session' context, which is useful but not elaborated. It does not mention what happens if the port is closed, if both text and hex are provided (schema enforces exactly one), or any side effects beyond writing. Given the annotations cover the destructive aspect, the description adds limited but non-contradictory value.

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 concise and front-loaded with the action. It states the purpose without redundancy. Every word earns its place; 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?

The description is minimal but covers the core action. However, it does not differentiate from the similar serial_send tool, and it omits explicit mention of the requirement that exactly one of text/hex must be provided (though schema covers this). With four parameters, no output schema, and a sibling that overlaps in functionality, the description is slightly under-specified for confident selection. It is adequate but leaves room for ambiguity.

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

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

Schema description coverage is 100%, so all four parameters (hex, port, text, line_ending) are fully documented in the schema. The description adds no additional parameter-level meaning, such as format expectations or relationships. Baseline 3 is appropriate because the schema carries the parameter semantics.

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

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

The description states a clear verb 'Write' and resource 'port' with specific data formats (text or HEX). It implies a capture session context but does not distinguish itself from the sibling serial_send, which likely performs a similar write operation. Without differentiation, an agent may not know which to choose.

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 is given on when to use this tool versus serial_send or other siblings. It does not mention prerequisites beyond an 'open capture session' (which is implied but not explicit), nor does it provide any exclusion criteria. An agent is left to infer appropriate usage from the name and context.

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