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

Beyond the readOnly/openWorld annotations, it discloses three non-obvious behaviors: no hardware is touched, the fallback rendering path returns the candidate list as text to relay, and the agent must call `open` itself afterward. This is exactly the kind of control-flow context annotations cannot carry.

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 sentences, each load-bearing: the action, the host-dependent fallback, the selection criterion, and the follow-up call. Scoping and the alternative are 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 two-param tool with no output schema and full annotation coverage, this covers purpose, fallback behavior, decision criteria, and the required next step. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and both parameters are documented there; the description adds no per-parameter syntax or format detail. Baseline 3 is appropriate when 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?

States a specific verb and resource ('ask the user which serial port to use') and immediately distinguishes itself from list_ports, so an agent can route between them 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?

Explicit when-to-use ('when several ports could plausibly be the device and the choice is the user's to make') and explicit when-not ('not for your own discovery, which is what list_ports is for'), naming the alternative tool 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?

Goes well beyond the readOnly/non-destructive annotations: it discloses pagination (cursor/max_frames), that idle-gap boundaries mirror a live session, that framing is required and never assumed, and that oversized JSON is offloaded to .openbaud/out/ with a summary plus full_result path. It also declares the view:{kind:"capture"} routing for show_result.

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?

Dense but front-loaded, leading with the core operation before constraints. Every sentence carries information (framing requirement, no hardware, timestamp-driven boundaries, view routing), though the density borders on terse for an 8-parameter tool.

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

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

For a nested-object, 8-param tool with no output schema, the description covers the key return behaviors (paginated timestamped frames, offload-to-file summaries, view hint) and the framing resolution rule. A little more on the shape of each frame could help, but the essential calling context is present.

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 88% schema coverage the baseline is 3, but the description adds real value: the framing-overrides-device precedence, the idle-gap/timestamp semantics that drive from_ms/to_ms boundaries, and the cursor-based pagination intent. These clarify how the documented params interact rather than merely restating them.

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: re-framing a recorded capture's byte stream into timestamped frames, split by tx and rx. This clearly distinguishes it from capture_start/capture_stop (live capture) and diagnose_frame (single frame analysis). An agent knows exactly what operation this is.

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 strong context: it reads captures/<file>.obcap with no hardware, and requires either an explicit framing object or a named device profile ('one of the two is required, nothing is assumed'). This tells the agent when it applies (post-capture, file-based) but stops short of explicitly naming which sibling to use instead for live capture.

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

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

Annotations declare it is a non-readonly, non-destructive, closed-world operation, but the description adds real substance: capture is lossless and timestamped, covers all rx/tx, writes JSONL into captures/*.obcap, and returns both a workspace-relative and absolute path. It still doesn't say how the capture terminates or any storage/overhead implications, so it is good but not exhaustive.

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

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

Two dense sentences with no filler, behavior front-loaded and return/chaining details second. The parenthetical path-routing list is compact but slightly crammed, keeping it just under ideal.

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?

There is no output schema, so the description correctly carries the return payload (relative path + abs_path). For a stateful capture-start tool it covers what is captured and how to consume the result, but omits parameter meaning and the lifecycle relationship with capture_stop.

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 both parameters, and the description never explains session_id (only alludes to 'a session') or the optional note field. With two undocumented parameters, the description fails to compensate for the schema 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 (Start) and resource (lossless timestamped capture of all rx/tx on a session), names the output artifact (captures/*.obcap, JSONL), and is clearly distinguishable from siblings capture_stop and capture_frames.

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

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

It gives concrete downstream usage — pass the returned path verbatim to capture_frames, session_timeline, or replay:<path> — which orients the agent on when this tool fits in a workflow. It stops short of stating when NOT to use it or explicitly contrasting with capture_stop/other starting points, so it lacks full alternative routing.

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

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

Annotations already establish the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real post-condition context that annotations lack: it returns stats plus a workspace-relative path and abs_path, and confirms the captured artifact persists and is reusable by other tools.

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

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

One front-loaded sentence; the core action leads and the return-value detail follows. The nested parenthetical with three tool names is dense but every clause carries usable 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?

With no output schema, the description correctly carries the return-value burden, describing stats and both path forms. Annotations cover safety, so the only gap is not stating the precondition failure mode when no capture is active.

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 for the single session_id parameter. It only says 'on a session' and never names or qualifies session_id (e.g., that it is the id from capture_start), so it adds little beyond the schema's type declaration.

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 ('Stop') and resource ('the active capture on a session'), which cleanly distinguishes it from the sibling capture_start. An agent can tell what it does without opening the schema.

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

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

Usage is clearly implied by 'the active capture' (i.e., use after capture_start while a capture is running), and the description routes the agent downstream by naming capture_frames, session_timeline, and replay:<path>. It does not state what happens if no capture is active, so no explicit exclusions 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?

Annotations already declare destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description usefully adds that the port is released, a real side effect not visible in annotations, but says nothing about whether session data persists, whether closing an already-closed session errors, or what the result looks like.

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 sentence, front-loaded with the action and resource, with the side effect following. 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?

For a minimal one-parameter tool with no output schema this is close to adequate, but it omits the error/edge behavior (double close, invalid id) and any indication of what the caller should do after closing, leaving gaps for an agent sequencing sessions.

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

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

Schema description coverage is 0% and the single session_id parameter has no schema documentation. The description implicitly identifies which session is affected ('a session'), which is self-evident for a one-parameter close tool, but adds no format, source, or validity details.

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 (session) plus the side effect of releasing the port. It is clearly the counterpart to the 'open' sibling, but it never names or contrasts with that sibling 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 when-to-use or when-not-to-use guidance, no prerequisites, and no mention of alternatives such as leaving a session open or reusing it. Usage is only implied by the word 'close'.

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 cover the safety profile (readOnly, non-destructive, closed-world), and the description adds substantial semantics beyond them: what each checksum_matrix row contains, why a row may omit `at`, and a crucial warning that `parsed: true` only means structural decodability at a mutually exclusive hypothesis offset. This directly prevents misreading the output.

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

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

Front-loads the core purpose and constraint, then layers the output semantics in one dense but purposeful paragraph. Some nested parentheticals (stored_len computation) are heavy, but no sentence is filler.

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

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

With no output schema, the description carries the burden and does it well: it names the result sections (checksum_matrix, parse_attempts), the row fields, and the view declaration for show_result. Only a few edge details (frame size limits, error result shape) are left implicit.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by spelling out how `expected:{device,command}` behaves (response.parse attempted at byte offsets -2..=+2) and by explaining the hex-frame coming from the byte offsets rather than the schema's example.

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?

Opens with a specific verb+resource ('Diagnose one raw frame') and immediately scopes it against the hardware-touching siblings ('pure computation — no hardware, no audit entry'). An agent can tell this apart from send/capture_start/capture_frames without opening another 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?

Clearly establishes the use context (offline, no hardware, no audit entry) and explains when to supply `expected` (to trigger parse_attempts for off-by-N framing). It does not explicitly name alternative siblings to use instead, but the contrast with hardware tools makes the routing condition inferable.

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=true, so the safety profile is covered. The description adds real but modest behavioral context: returned results include USB metadata and always contain the mock:echo loopback entry. It says nothing about ordering, sampling, or what happens if no hardware is present.

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

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

A single front-loaded sentence with no filler; the resource is stated first and the two payload caveats follow. Nothing is wasted and nothing important 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?

For a zero-parameter read tool with no output schema and annotations covering safety, the description supplies what an agent needs: what is listed, that USB metadata comes along, and that the mock loopback is guaranteed. Minor gaps remain (no detail on the metadata fields or ordering), but nothing blocks 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?

The tool takes zero parameters, which is the baseline-4 case. The description correctly implies a no-argument, ambient-environment call rather than inviting parameters that do not exist.

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

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

Clear specific verb+resource: 'List serial ports'. It even scopes the payload ('USB metadata included') and calls out the always-present mock:echo loopback. It does not name or differentiate itself from likely siblings such as open or ask_port, so it falls short of a 5.

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

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

Usage is only implied: a list-ports tool is obviously a discovery step before opening a connection, and mentioning the always-available mock:echo loopback suggests a no-hardware test path. But there is no explicit when-to-use, when-not-to-use, or named alternative.

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 not-read-only, open-world, non-destructive, so the bar is lower; the description still adds genuine context — profile defaults vs explicit overrides, the exactly-one-live-match constraint for selectors, workspace-relative replay paths, and the session_id return. It omits that the returned session is a stateful handle needing `close`, which keeps it from 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-loaded with the core action, then three dense sentences covering override semantics, selector matching, and replay. No filler, though the selector clause is packed enough to slow parsing slightly.

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 no output schema, the description correctly states the return value (session_id) and covers the three distinct invocation modes. Missing only failure behavior when no selector match exists and whether channel settings are mandatory without a device profile.

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

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

Schema description coverage is only 43% (baud, parity, data_bits, stop_bits are undocumented), so the description has to compensate. It does: the profile-supplies-defaults/arguments-override rule explains every optional parameter, and the selector and replay notations add meaning beyond the schema for `port`.

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

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

States a specific verb and resource ('Open a serial port session'), which unambiguously separates it from close/send/list_ports. It never names a sibling or explicitly contrasts itself, so it lands at clear-but-undifferentiated rather than a 5.

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

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

Gives real conditional guidance: `device` supplies defaults, explicit args override, `port` may be omitted only when the profile declares a selector, and `replay:<capture path>` triggers replay mode. It stops short of stating when-not-to-use or naming alternatives (e.g. close/read), so no 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?

Annotations already cover the safety profile (readOnly, non-destructive, open-world). The description adds genuinely new behavior: it blocks up to timeout_ms for the first frame, and it surfaces dropped_bytes when the buffer overflows. These are non-obvious traits an agent needs. It stops short of describing frame ordering or what happens on a fully empty buffer.

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 tight sentence with the core behavior front-loaded, followed by the blocking-wait parenthetical and the overflow-report clause. Every clause carries 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?

There is no output schema, so the description should carry more of the return shape. It names dropped_bytes but does not describe what a frame contains or how the .openbaud/out full_result fallback (documented only in the schema) interacts with reads. Adequate for invocation, thin for interpreting results.

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 only 25% (only max_inline_bytes is documented in the schema). The description partially compensates by explaining timeout_ms's wait semantics and implying frame-count returns, and the overflow reporting relates to buffer behavior. However max_frames and session_id carry no added meaning, so the compensation is incomplete.

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 with scope: 'returns frames received since your previous read', plus the cursor-based semantics. This is much more than a restatement of the name 'read'. It does not, however, explicitly contrast itself with siblings like stream_poll or capture_frames, so an agent must infer the difference.

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

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

Usage is implied by the cursor semantics ('since your previous read') and the blocking behavior, which tells the agent this is the incremental-consumption tool. But no when/when-not guidance or named alternative (stream_poll, capture_frames) is given, leaving the selection between the several polling/reading siblings to inference.

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

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

Annotations already declare this is a destructive, open-world write operation, so the safety profile is covered. The description adds that calls are "audited" and precisely defines completion semantics via `match`, but says nothing about what state `send` mutates, whether it blocks session use, or what happens on timeout.

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

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

Two tight sentences, front-loaded with the core action and followed by the one parameter that genuinely needed prose. No filler, though the match syntax is dense enough that it reads as terse rather than optimally structured.

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 6-parameter mutation tool with no output schema and low schema coverage, the definition covers the trickiest parameter but omits the return shape, timeout behavior, and the hex/text distinction. The `max_inline_bytes` note about .openbaud/out/ partially compensates on result handling.

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 17%, so the description must carry weight. It does an excellent job decoding the undocumented `match` object with three concrete forms and a stated default, but leaves `hex` vs `text` selection, `session_id`, and `timeout_ms` unexplained despite being key to correct 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?

The description names a specific verb and resource ("Send bytes and await the response"), making the blocking-call nature clear. However, it does not differentiate itself from close siblings like `send` or `ask_port`, leaving the agent to guess which one is intended for a request/response exchange.

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

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

There is no explicit when-to-use guidance, no exclusions, and no mention of when to prefer this over `send`, `ask_port`, or `read`. The only usage hint is the parenthetical "(audited)", which is stated without explaining its consequences.

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 only declare non-readOnly/destructive/openWorld; the description goes well beyond by enumerating the outcome taxonomy (normal | exception | silence | timeout | checksum_error | malformed), explaining `expect` auditing and that unmet expectations return an error with full result JSON, and disclosing the risk gate (acknowledge_risk=true for risk=danger). That is substantive behavioral context an agent cannot get from 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?

Front-loaded with the action, and every clause carries information about outcomes, session model, or risk gating. The middle sentence packs session_id, port, selector omission, and replay syntax into one long clause chain, which is dense though not wasteful.

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

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

For a destructive, open-world tool with 7 params, a nested object, no output schema, and low schema coverage, the description supplies the outcome model, audit/error semantics, session-vs-ephemeral choice, and the risk acknowledgement gate. It stops short of describing how per-command `params` are shaped or how results are summarized by max_inline_bytes beyond the schema's own note.

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 29%, so the description has to compensate, and it largely does: session_id vs port semantics, the selector-based port omission rule, the replay:<capture path> syntax, and the acknowledge_risk requirement are all description-only. The nested `params` object and `device`/`command` remain only lightly characterized ('typed params'), leaving one meaningful gap.

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

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

States a specific verb and resource ('Execute a named command from devices/<device>/commands/') and immediately explains the mechanism (builds the frame, awaits response, classifies outcome). This is clearly distinct from lower-level siblings like send/request or the orchestration tool run_workflow, even though no sibling is named.

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 real usage context: use session_id for an existing session, or port for an ephemeral transport, with port optionally omitted when the profile declares a selector, and replay:<capture path> accepted. It does not, however, tell the agent when to prefer this over alternatives such as run_workflow or send, so there is no explicit 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 declare destructiveHint=true and openWorldHint=true, but the description adds far more: ordered execution, first-failure skips remaining steps, every `finally` step is still attempted, the exact return shape {ok, steps, finally, skipped}, ok=false meaning an error carrying the full result JSON, risk being the max of constituent commands, and the acknowledge_risk gate. This is well beyond annotation coverage.

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?

Execution semantics, failure handling, return shape, and risk gating are front-loaded in a tight sequence with no filler. It is a dense single block, and the session-resolution clause is appended rather than integrated, but every sentence carries information an agent needs.

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

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

For a destructive, multi-step executor with no output schema, the description supplies the return shape, the error convention, the finally-step guarantee, and the risk-acknowledgment requirement. Nothing essential to correct invocation is missing.

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

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

Schema coverage is only 33%, so the description must compensate, and it does for the risky params: acknowledge_risk semantics (danger requires true) and session resolution via session_id, port, or device profile selector. It implies device and workflow meaning via the path 'devices/<device>/workflows/', though it doesn't explicitly define the workflow identifier format.

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

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

States a specific verb and resource — execute a workflow located at devices/<device>/workflows/ — and immediately distinguishes the behavior from a plain command run by describing ordered steps on one session. An agent can tell what this does without opening the schema.

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

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

Gives clear conditions: workflows are execution units whose step params override command defaults, and danger-level workflows require acknowledge_risk=true. It also anchors session resolution to run_command (session_id, port, or profile selector), which is actionable routing guidance. It never explicitly says when to prefer run_command or a single command over a workflow, so it falls short of a 5.

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

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

Annotations already declare the safe read-only profile, so the description is not obligated to restate it. It adds genuinely useful behavioral context: the schema is generated from the actual parsing types and encodes semantic rules the grammar cannot express, which tells the agent this is authoritative rather than a hand-written reference.

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, front-loaded with what is returned and immediately followed by the trigger for calling it. Every clause — authority, generation source, semantic-rule coverage — earns its place; there is no 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?

With no output schema, the description correctly takes on the burden of describing returns (JSON Schema vs. annotated YAML example) and the safety profile is already carried by annotations. It is essentially complete; only minor details like schema size or versioning are absent, which are not needed to invoke it correctly.

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

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

Schema coverage is 50% — the 'kind' enum has no inline description, but the description names all three valid values in prose. 'example' is defined in the schema and the description reinforces its effect ('with example=true, an annotated YAML example'), so both parameters carry meaning beyond the raw types.

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 resource with scope: the authoritative JSON Schema for the three openbaud knowledge formats (profile, command, workflow), plus the example=true mode. Nothing in the sibling list (list_ports, run_workflow, capture_*) overlaps, so an agent can identify this tool immediately without opening the schema.

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

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

Gives an explicit trigger — 'Call this before writing or modifying any YAML under devices/' — plus the reason (it is generated from the exact types that parse those files). It does not name a when-not condition or an alternative, but no sibling competes for this role, so the missing exclusion is low-cost.

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, destructiveHint=true and openWorldHint=true, so the write/destructive profile is covered. The description adds one genuinely new trait, '(audited)', indicating the write is logged. It does not disclose return behavior, error handling, or whether the write is blocking.

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, no filler, with the core action front-loaded ahead of the input-format rules. Every clause earns its place; the examples are the minimum needed to convey format.

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 low-complexity 3-param tool with annotations covering the safety profile and no output schema, the description covers input format adequately. It is still missing sibling differentiation and any note on failure/return behavior, which an agent writing raw bytes would benefit from.

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

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

Schema coverage is 0%, so the description must carry the load, and it does for two of three params: it explains hex format ('01 A0 FF'), text semantics (control chars passed as-is, with an 'AT\r\n' example), and the mutual-exclusivity constraint that the schema does not encode. session_id remains undocumented.

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

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

States a specific verb+resource ('Write raw bytes'), which cleanly separates it from read/request siblings in the same family. It never says what it writes to (a session/serial port), relying on the session_id param and sibling context to imply the target.

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

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

Gives a parameter-selection rule ('exactly one of hex or text') but no guidance on when to use send versus request, run_command, or run_workflow. An agent gets no routing help for choosing this tool over its write-capable siblings.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. Beyond that, the description usefully discloses that counters are live, that the transport settings the port was opened with are included, and that the session error is surfaced when the port died — real behavioral context not present in structured fields.

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 long but front-loaded sentence: the resource and scope come first, the field enumeration second, and the session_id guidance last. It is dense but every clause names actual returned data, so little is wasted; a minor readability cost from the run-on list structure.

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?

There is no output schema, so the description must explain return values, and it does by enumerating the counters, capture info and error field. Combined with the default-scope rule and the annotations covering safety, an agent has enough to invoke it correctly; only the treatment of non-open/unknown sessions is left implicit.

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

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

The schema documents nothing for session_id (0% coverage), so the description carries the burden and does so: it states that passing session_id scopes to one session and that omitting it defaults to all sessions. That is exactly the semantics the agent needs, though it doesn't clarify id format or behavior for an unknown/closed id.

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

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

The description opens with a concrete noun phrase, 'Live counters for open sessions', and then enumerates exactly which counters are reported, so an agent knows precisely what this returns. It is distinguishable from sibling tools like session_timeline or list_ports, though it never explicitly names a sibling it is not.

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

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

The sentence 'Pass session_id for one session; default is all' gives clear operational context for scoping the call, which is genuine usage guidance. However, there is no when-to-use vs. when-not-to-use framing and no mention of the sibling tools (session_timeline, list_ports) that an agent might confuse it with.

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 closed-world, so safety is covered. The description adds real value beyond that: it names the exact files read (captures/<file>.obcap, .openbaud/audit.jsonl), confirms no hardware is touched, and discloses the view:{kind:"timeline"} output contract plus the show_result rendering path.

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 dense sentences, front-loaded with the core purpose, then inputs, then the output/rendering contract. Every sentence carries information, though the third sentence's phrasing is slightly convoluted.

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 no output schema present, the description usefully explains what the result declares (view.kind) and how it reaches the user via show_result, and it documents the two data sources. A mutation-heavy tool would need more, but for a read-only analysis tool this is close to complete.

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

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

Schema description coverage is 100%, so every parameter (path, from_ms, to_ms, buckets, max_inline_bytes) is already fully documented in the schema. The description mentions bucket folding and windowing only in passing and adds no syntax or format detail beyond the schema, so the 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 and resource: it lays a recorded capture out as a session timeline, combining rx/tx density buckets with audited operations as events. This is clearly distinguishable from sibling tools like session_stats or capture_frames, since it names both the input artifacts and the output shape.

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 clear context for use: it operates on an existing capture file plus the audit log and explicitly notes 'no hardware', which tells the agent this is an offline analysis tool rather than a live one. It does not, however, explicitly name when to prefer session_stats or diagnose_frame over this.

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 cover the read-only, non-destructive, closed-world profile, and the description adds real context: it notes the viewer reads the payload from disk so full data never enters the agent's context, and that rendering only happens on supporting hosts. It does not describe error behavior if the path is stale or the host lacks viewer support.

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 sentences, front-loaded with the action and rendering mode, then the data-flow rationale, then the charting condition, then the usage trigger. Dense but each sentence carries distinct information; only slightly verbose.

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

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

No output schema, but the description explains the rendering outcomes (polar plot vs field table) well enough that an agent knows what to expect. With 3 nested/optional params, coverage is adequate though it could note what happens with the `data` param for unspilled results.

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 genuine semantics: `path` is tied to an earlier full_result, and `encoding` overrides the result's own `view` when both exist and is only needed when no view is present. This is decision-relevant information beyond the schema text.

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 (show a saved tool result to the user) plus the rendering modes (polar plot vs field table). The final sentence distinguishes it from the read/session siblings by framing it as a display action rather than a data-retrieval one.

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 the user would rather see the data than read it") and implies the when-not by pointing to reading via its framing. It does not explicitly name the alternative tool (read/session_timeline) as the routing target, so it stops short of 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?

Annotations already declare readOnlyHint/destructiveHint/openWorld, but the description adds substantial behavior beyond them: at-least-once gap accounting (dropped_frames, dropped_chunks 'never silently'), idempotent redelivery via omitted since_seq, loud failure on a dead port, retention limit of 1024 frames, 8-subscription cap, 120 s idle sweep, and parse-error isolation per frame. This is unusually rich disclosure.

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

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

Front-loaded correctly with purpose before mechanism, and most sentences carry unique operational information. However, it is one ~450-word run-on paragraph with deeply nested parentheticals and some restatement of schema-level details (parse, max_inline_bytes), making it dense to parse where sub-structuring would help.

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 no output schema, the description carries the full burden of explaining return values and does so thoroughly: subscription_id, frames with monotonic seq, next_seq, page_bytes, oversized_frame, dropped_frames/dropped_chunks, stats counters, and parsed/parse_error. For a 7-parameter nested-schema tool this leaves nothing an agent needs 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 86%, so the baseline is 3, but the description genuinely adds meaning: why to ack with 'last delivered frame's seq + 1, not next_seq' (next_seq can run ahead of a max_frames-capped page) and how max_inline_bytes is metered. The only real gap is max_frames, which is never explained in prose and has no schema description.

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

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

States a specific verb and resource ('per-consumer incremental frame poll on an open session') and immediately distinguishes itself from the sibling read tool ('fully independent of `read` (the two never steal frames from each other)'). An agent can select this over read/capture_frames 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?

Spells out the two call modes ('Call with session_id to create a subscription' vs 'Call with that subscription_id to fetch what arrived since'), when close:true applies, and exactly when parse is legal ('when CREATING a subscription ... never on a follow-up poll — that is a loud error'). Alternatives and exclusions are explicit rather than implied.

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