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

Annotations already establish this as a safe read, so the description's job is to add context, which it does: it discloses the precondition that the device profile must declare boot_stages and that it reports none otherwise, plus the stall-detection behavior. That is meaningful disclosure 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?

Two tight sentences: the return content is front-loaded, followed by the precondition and the usage/routing guidance. No filler.

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

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

With an output schema present, return values need not be restated, and the description still covers the precondition, the trigger condition, and the fallback sibling. Nothing needed 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to clarify, and it correctly avoids inventing parameter semantics.

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

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

States a specific verb and resource ('Report cold-boot progress') and enumerates exactly what it returns: stages reached, furthest stage, and stall status. This is clearly distinguishable from siblings like serial_read or serial_port_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?

Gives an explicit trigger ('Use after a reset or power cycle') and routes the agent to serial_get_incidents when the boot is stalled. It stops short of stating when not to use it, but the context and alternative are concrete.

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 openWorldHint=false, so the safety profile is covered. The description adds value beyond them by disclosing the return format (Markdown) and the aggregated content, which matters since there is no output schema.

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

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

Two tight sentences with no filler. The deliverable is front-loaded and the routing rule follows, so an agent can act after one read.

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 zero parameters and no output schema, the description carries the return-value burden and largely meets it by naming the sections in the summary. It stops short of stating size, format details, or how it relates to serial_monitor, but nothing needed to call it is missing.

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

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

The tool takes zero parameters, so the baseline is 4 and there is no parameter syntax to explain. The description correctly implies a no-argument, whole-snapshot call rather than leaving the agent hunting for a target selector.

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 output artifact (a Markdown summary) and enumerates its contents: device profile, port status, and incidents. That differentiates it from the single-fact siblings in spirit, though it refers to them only generically as 'the single-purpose tool' rather than naming any of the eight.

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

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

Gives explicit when-to-use ('open a debugging session or hand a human a snapshot') and a when-not-to-use rule ('for one fact, call the single-purpose tool'). The exclusion is directional but unnamed, so the agent must infer which sibling covers a given fact.

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 openWorldHint=false, so safety is covered. The description adds meaningful behavior beyond that: it specifies the detector's classification taxonomy and that each result carries the match plus pre-context, which tells the agent what a returned incident contains. It does not disclose limits on the detection window or buffering, keeping it short of a 5.

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

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

Two sentences with no filler: the first front-loads what is detected and what each result includes, the second front-loads when to use it and what to pair it with. Every clause earns its place by aiding selection or interpretation.

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 formatting need not be explained, and the description still covers detection scope, trigger conditions, and sibling pairing. For a single-optional-parameter read tool, nothing an agent needs to select or invoke it correctly is missing.

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

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

Schema description coverage is 100% and there is only one optional parameter ('seconds'), which the schema already documents fully. The description adds no extra syntax, default, or format detail about that parameter, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List anomalies the broker detected in output') and enumerates exactly what counts as an anomaly (kernel panic, oops, hard fault, assert, watchdog, brownout, ESP resets, profile patterns). It also distinguishes itself from the sibling serial_output_history by framing that tool as the source of surrounding log context.

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 triggering conditions ('when a boot stalls, a wait aborts, or output looks like a crash') and explicitly routes the agent to pair with serial_output_history for surrounding logs. The when-to-use condition and the relationship to the alternative are both stated directly.

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, openWorldHint=false, so safety is covered. The description still adds real behavioral context beyond them: no broker dependency required, and the caveat that bridge chips report the adapter rather than the MCU, which materially affects how an agent interprets the returned names.

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

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

Three short sentences with no filler: purpose and return content first, then usage triggers, then the interpretive caveat. Every clause earns its place and nothing is 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 there are no parameters to document. Purpose, invocation timing, and the interpretation caveat are all present, leaving no material gap for an agent deciding to call 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 no parameters, so there is nothing to disambiguate; the description instead spends its words on the returned fields (by-id path, VID/PID), which is the right allocation. Baseline of 4 applies for a zero-parameter tool.

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

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

Specific verb+resource ('List serial ports on this host') plus the exact payload returned (by-id paths, USB VID/PID), which cleanly separates it from siblings like serial_port_status or serial_read. The parenthetical '(works without a broker)' further scopes it as a standalone discovery 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?

Gives two concrete triggering conditions: before starting a broker, and when output is garbage due to a wrong port. No sibling tool is named as an alternative, and there is no explicit 'when not to use', so it falls short of the 5-level routing guidance.

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

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

With annotations already declaring readOnlyHint, openWorldHint=false, and destructiveHint=false, the description adds valuable behavioral context: the default and maximum listening duration, and that it returns both raw output and anomalies. It doesn't cover potential blocking behavior or output format details, but the added context is meaningful.

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

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

Two tightly written sentences with no waste. The core purpose and duration constraints are front-loaded, followed immediately by the usage rule and alternative.

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), the description provides everything an agent needs: what it does, when to use it, how long it runs, and what it returns. Annotations already cover safety, so no critical gaps remain.

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 single parameter is fully documented in the schema. The description repeats the default (30 s) and max (300 s) without adding new syntax or format details beyond what the schema provides, which is the baseline 3.

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

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

The description states a specific verb (listen), resource (device output and anomalies), and scope (fixed time window), clearly distinguishing it from serial_wait_for. It also implicitly differentiates from read-once siblings like serial_read by emphasizing monitoring over a duration.

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 explicitly states when to use this tool ('when you do not know what to expect') and names the alternative serial_wait_for for when you do know what to expect. This is a textbook when/when-not/alternative guidance.

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

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

Annotations cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), but the description adds the non-obvious behavioral fact that reads do NOT consume the buffer, and exposes paging state (dropped, has_more). It omits error conditions and cursor expiry, so not a full 5.

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

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

Three tight sentences with no filler; the core non-consuming read behavior leads, followed by the paging recipe and the fallback, then the sibling contrast. 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 needn't be explained, yet the description still surfaces the meaningful response fields (cursor, dropped, has_more). For a 4-param, all-optional read tool this is complete enough to invoke correctly on the first try.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics the schema does not: since_seq must start at 0, the returned cursor must be passed back, and dropped/has_more must be checked. The seconds/last_bytes fallback condition is also stated in 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 and resource ('Read past output from the broker's shared history') plus the differentiating trait 'without consuming it'. It explicitly contrasts itself with serial_read, which is described as drain-only, so an agent can pick between the two without opening schemas.

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

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

Gives explicit when-to-use routing: use since_seq paging 'for anything you must not miss' with start-at-0 and cursor-passback instructions, and fall back to seconds/last_bytes when since_seq is absent. It also names the alternative (serial_read) and its exclusive behavior (drain-only).

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

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

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the actual inspection surface, including contested state like write-control ownership and identity strength, which tells an agent what diagnostic questions this call can answer. It does not mention latency or caching, which keeps it short of a 5.

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

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

Front-loads the imperative use case, then compresses the reported fields into one scannable list, then closes with two sibling redirects. Every clause carries selection or invocation value; nothing is restated from the title or schema.

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

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

An output schema exists, so return values need no explanation, and annotations carry the safety profile. What remains for the description, namely when to call this versus the boot/incident siblings, is fully covered, so an agent has everything needed 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The listed output fields could be mistaken for inputs, but the schema is empty and the description's framing ('check') makes the direction of data clear.

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

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

States a specific action ('Check the link') and enumerates exactly what the tool reports: port, baud, connected/suspended, by-id identity, pins, write-control ownership, and connected clients. That enumeration makes it unmistakably distinct from siblings like serial_read and serial_monitor without opening any schema.

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

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

Gives two explicit trigger conditions ('before sending' and 'when output looks wrong') and routes two adjacent needs to named alternatives ('Boot progress: serial_boot_status', 'Crashes: serial_get_incidents'). Nothing about when-to-use or when-to-defer is left to inference.

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

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

Annotations cover the safety profile (readOnly, non-destructive, closed-world), and the description adds genuinely non-obvious behavior beyond them: it consumes/drains the buffer, is lossy across turns, and does not transmit on the port. It omits return formatting and empty-buffer behavior, which is why it is not a 5.

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

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

Three tight clauses, zero filler, and the core action plus its main caveat ('lossy across turns') are front-loaded before the alternative-tool pointers.

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

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

For a no-param, fully annotated read tool with no output schema, the description covers purpose, consumption semantics, and alternatives. Only minor operational details (empty-buffer result, encoding/format of drained output) are absent.

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

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

The tool takes zero parameters, so the baseline of 4 applies and there is no schema coverage gap to compensate for. The description adds no parameter detail, but none is needed.

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

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

States a specific verb and resource ('drain the output this MCP session buffered since the last read') plus the critical scope qualifier 'without sending'. It immediately differentiates itself from siblings by naming what it is not (lossless history, text-waiting).

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

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

Gives explicit when-to-use ('Quick look after your own command'), an explicit limitation ('lossy across turns'), and routes to the two correct alternatives by name with the parameter that selects them ('serial_output_history with since_seq', 'serial_wait_for'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: it transmits nothing ('no TX', 'Works for observers') and terminates early on a critical anomaly ('[ABORTED anomaly:...]'). It does not describe the return value on a normal timeout, which keeps it short of a 5.

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

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

Four compact sentences, front-loaded with the core action, then usage, then behavior, then alternatives. No filler or restatement of the tool name.

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

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

No output schema exists, so the description carries the return-shape burden; it partially covers this by noting early termination on anomalies, and the timeout semantics live in the schema. The only gap is what a successful match returns to 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 100% and both parameters are fully documented in the schema, including the default and clamp range for timeout_ms. The description adds no syntax or format detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb ('wait for') and resource ('a regex in serial output') plus a distinguishing constraint ('without sending'), which separates it from siblings like serial_read and serial_monitor. The parenthetical examples (prompt, login:, log line) make the trigger condition concrete.

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

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

Explicitly says when to use it ('when you know the text to expect') and routes two named alternatives: 'Open-ended listening: serial_monitor' and 'Output that already arrived: serial_output_history.' Both siblings exist in the tool list, so the routing is actionable.

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