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

With no annotations provided, the description carries the full behavioral burden and does so well: it discloses that existing files are appended to, that 'raw' includes echoed received bytes, that 'annotated' adds TX/RX timestamps, and how path resolution works. This goes well beyond the schema.

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

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

The description is tightly structured: one succinct purpose sentence followed by a compact Args section. Every sentence adds needed information—no filler, repetition, or vague phrasing.

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 fully covers what the tool does, how to invoke it, what side effects occur (appending to files), and the key parameter semantics. The presence of an output schema means return-value details are not required here. Nothing essential is missing for correct invocation.

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

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

Schema coverage is 0%, so the description must fully compensate, and it does. It explains the path default, bare-name versus absolute-path behavior, append semantics, the meaning of each format enum value, and the default for connection. Every parameter is meaningfully documented.

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

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

The description opens with a specific verb-resource pair: 'Start writing this connection's traffic to a file until capture_stop.' This clearly distinguishes it from siblings like capture_stop, get_transcript, and send_text, and names the exact resource affected.

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 makes clear that this is the tool to begin a capture session and implicitly identifies capture_stop as the paired termination tool. It does not explicitly enumerate when not to use it, but the context is clear enough for an agent to select it correctly.

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

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

No annotations are provided, so the description carries the full burden. It discloses the action (stop capture) and the return (file and size), which is useful. However, it doesn't mention side effects (e.g., whether the capture is saved or deleted), error conditions if no capture is active, or whether the operation is reversible. The return format is partly covered by the output schema, but behavioral caveats are missing.

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 one concise sentence that front-loads the core action and result. It contains no fluff and communicates everything needed for the tool's primary function efficiently.

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

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

The tool is simple with one optional parameter and an output schema, which covers return values. The description explains the main use case and pairing with capture_start. However, it lacks any detail about the connection parameter, error handling, or edge cases (e.g., calling it without an active capture). Given the tool's simplicity, this is a moderate gap.

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

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

Schema description coverage is 0%, and the description makes no mention of the single 'connection' parameter. The parameter is optional with a default, but the description adds no meaning about what it should contain or how it affects the operation. The description entirely 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?

The description clearly states a specific verb ('Stop') and resource ('the capture started by capture_start'), and it mentions the output ('report the file and size'). It distinguishes itself from sibling tools by pairing with capture_start, making its 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 implies the tool is used after capture_start by referencing it, giving clear context. It doesn't explicitly list alternatives or exclusions, but the sibling set includes capture_start, and this tool's purpose is obvious. Slight gap: no mention of prerequisites or when not to use it.

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

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

With no annotations, the description carries the full behavioral burden and does a solid job: it discloses the ';' terminator, the line_ending='NONE' usage, the empty-value-means-read convention, and family-specific frequency formatting (11 vs 9 digits). It does not cover edge cases like unknown commands, but the key formatting behaviors are clearly exposed.

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 well organized: purpose in the first sentence, a helpful common-command reference, then a clean Args section. Nothing feels redundant, and the most important information is front-loaded before the parameter details.

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 4-parameter builder with no schema descriptions, the description is nearly complete: it covers all inputs, the output terminator, family variants, and how to pair it with query_text/send_text. The only minor gap is not explicitly listing alternatives/exclusions, but the parameter coverage and usage context are strong enough for correct invocation.

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

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

Schema description coverage is 0%, so the description must fully compensate, and it does. It explains all four parameters: command is two letters, value is an empty-read or set-append, frequency_mhz is formatted per family, and flavor is the convention choice with defaults. The MD2 example adds useful concrete meaning beyond the bare schema.

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

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

The description opens with a specific verb and resource: "Build a ';'-terminated text CAT command" for Kenwood, Elecraft, and Yaesu rigs. It also clarifies the relationship to companion tools by saying the result is for query_text or send_text, distinguishing it from parsing or CIV-building siblings.

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

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

The description clearly implies when to use the tool: when constructing a CAT text command to pass to query_text or send_text. However, it never explicitly states when not to use it or names alternatives such as civ_build or cat_parse, so the agent must infer the boundary from siblings and context.

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

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

No annotations are provided, so the description carries the burden. It discloses that the tool parses specific formats and handles error answers (?; E; O), which is a behavioral trait – users know it can return errors. It doesn't mention side effects (likely none), but for a decode tool this is sufficient. It does not contradict annotations (none exist), so no contradiction 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?

The description is a single sentence, efficient and front-loaded with the main verb and object. It lists details (FA/FB to MHz, MD to mode name) that are useful but could be considered slightly dense. It earns its place with no fluff, though the parameter details could be trimmed. It is appropriately sized for the complexity.

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 moderate complexity with 2 params and an output schema exists. The description covers what the tool does and where the input comes from. It doesn't fully explain the flavor parameter's effect on parsing, but with the output schema present, return values are covered. The main gap is the flavor semantics, so a 4 is suitable.

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. It explains the 'reply' parameter implicitly: it is the text returned by query_text, which gives semantic meaning beyond the schema's bare 'string' type. However, the 'flavor' parameter is not explained in the description (though the schema has an enum), so there is a small gap. This is otherwise good compensation.

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 has a specific verb and resource: 'Decode ';'-terminated text CAT replies.' It lists what the tool parses (rig id, FA/FB to MHz, etc.) and the answer types, clearly distinguishing it from siblings like 'civ_parse' and 'rotator_parse'. It is not a tautology and provides concrete details.

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

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

The description says to pass 'the text returned by query_text', which gives a clear caller context. It implies this is the decode step for text CAT replies but does not explicitly say 'when not to use' it or mention alternatives like 'civ_parse' for binary protocols. Still, the explicit connection to query_text provides good guidance.

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

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

No annotations are provided, so the description carries the behavioral burden. It clearly frames this as a pure construction operation that produces hex and does not send it. It does not discuss error handling or validation, but for a simple frame builder this is a minor omission rather than a misleading gap.

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

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

The description is front-loaded with a one-line purpose and then uses a compact argument list. Every sentence adds practical value, and the examples are dense but not padded.

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

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

For a 4-parameter tool with no annotation coverage and no schema descriptions, this definition is complete: all parameters are covered, the output's intended consumer is named, and the relationship to civ_freq is explained. The exact CI-V frame framing is not spelled out, but the 'ready for send_hex' contract makes that unnecessary.

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 0% schema description coverage, the description fully compensates by explaining every parameter with concrete hex examples, domain conventions, and defaults. The command examples, BCD frequency example, rig address table, and controller default give an agent everything needed to fill the arguments correctly.

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 ('Build'), a specific resource ('Icom CI-V frame'), and the exact output form ('as hex, ready for send_hex'). This clearly differentiates it from siblings like send_hex (which sends), civ_parse (which parses), and cat_build/rotator_build (which build other protocols).

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 establishes the intended pipeline: build a frame, then pass it to send_hex. It also gives an explicit alternative for frequency conversion ('For frequencies use civ_freq'). It does not explicitly enumerate when not to use cat_build or rotator_build, but the CI-V-specific framing makes the use case clear.

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

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

With no annotations, the description carries the behavioral disclosure burden. It transparently explains the conversion direction, the exact byte count (5), and the command context (set-frequency command 05). It doesn't cover edge cases like both parameters being provided, but for a pure conversion tool this is sufficient.

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 compact, front-loaded with the main purpose, and every sentence earns its place. It avoids boilerplate and directly explains the two usage modes in just a few lines.

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?

This is a simple two-parameter conversion tool with an output schema present. The description covers both parameters, the exact conversion behavior, and the byte counts, so an agent has enough to select and invoke the tool correctly. Nothing critical 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 0%, so the description must compensate. It does by explaining that mhz is the frequency input and bcd_hex is the 5-byte reply data, adding meaning beyond the bare property names and types. It stops short of specifying the exact hex string format for bcd_hex, but the core semantics are 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?

The description uses a specific verb ('Convert') and clearly identifies the resource: frequency in MHz and CI-V BCD data bytes. It also distinguishes this tool from siblings like civ_build and civ_parse by framing it as the frequency-to-BCD conversion utility.

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 instructions for both directions: supply mhz to get bytes, or supply bcd_hex to get frequency. It doesn't explicitly mention when not to use this tool or name alternatives, but the usage context is clear for a simple converter.

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

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

With no annotations provided, the description carries the full burden, and it does well: it discloses that it splits bytes into frames, disambiguates the tool's own echoed command from the rig's reply, and decodes BCD frequencies, modes, OK/NG and PTT state. It omits error behavior for malformed frames, but the core operational traits are disclosed.

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

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

Two tight paragraphs, zero filler. The purpose line is front-loaded with verb, resource and input source, and the second paragraph lists behaviors in a compact bullet-like flow. Every sentence 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?

The output schema exists, so return format is covered externally, and the description handles the core decode behaviors and input origin. The gap is the undocumented controller parameter and the absence of any note on malformed input handling — noticeable but not crippling for a decode tool with a defined output schema.

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. It covers hex_bytes implicitly ('from hex') but never explains the controller parameter (default 'E0') — its meaning, when to override it, or how it relates to the echoed-command disambiguation the description mentions. Half the parameter surface is left 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 (Decode) plus a concrete resource (Icom CI-V frames) and names the input source (hex as returned by read_available). It differentiates from sibling parsers (cat_parse, rotator_parse) by being explicitly CI-V protocol scoped, and from civ_build by being the decode/inverse 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 phrase 'as returned by read_available' gives the agent a clear pipeline signal: feed this tool the output of read_available. This routes usage without opening the schema. It doesn't explicitly name when-not-to-use it or mention civ_build as the encode alternative, so it stops 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?

With no annotations, the description carries the full burden of alerting the agent that this is a data-destructive operation: it discards received data and drops old echo, prior output, or syslog noise. It also clarifies the expected consequence for subsequent reads. Minor gaps remain around irreversibility and whether the operation applies globally or per connection.

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 the action front-loaded first; every clause adds useful context and 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?

For a simple utility, the core behavior and recommended placement in a workflow are clear. However, the optional connection parameter is undocumented, and the description doesn't explain how buffer/connection addressing works, so an agent with multiple connections could invoke it incorrectly. The existence of an output schema covers return values in principle.

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 sole parameter, 'connection,' has no schema description (0% coverage), and the tool description never mentions it or explains how it selects the buffer to clear. The word 'any' even creates ambiguity about whether the buffer is global or connection-specific.

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: 'Discard any buffered received data.' It also distinguishes itself from read/send siblings by explaining the side effect of clearing stale data, so the agent knows exactly what this tool does.

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 explicit timing: 'handy right before sending a command,' and explains why—so the next read starts clean and drops old echo/output/noise. It does not name alternative tools or state when not to use it, so it stops 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?

With no annotations, the description carries the full behavioral burden, and it is exceptionally transparent: it discloses the background reader, default serial settings, multiple concurrent connections, MRU selection, flow-control caveats (e.g., XON/XOFF swallowing 0x11/0x13 bytes), and detailed terminal emulation behaviors.

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?

Although long, the length is justified by 15 parameters and complex serial semantics. The description front-loads the core action and defaults, then organizes parameters in a clear Args list where each sentence adds practical value.

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 tool with this many parameters and no annotations, the description is complete: it covers defaults, parameter interdependencies, related tools, behavioral effects, and how connections are referenced later. Nothing an agent needs to open a port 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 0%, but the description documents every parameter with concrete values, defaults, platform examples, and caveats. For example, port names for Windows/macOS/Linux, common baud rates, and the semantics of terminal modes go far beyond the bare schema.

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

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

The opening sentence states a specific verb and resource: 'Open a serial port and start its background reader.' It also distinguishes itself from sibling tools by explaining that this is the setup step for later send/read tools, and it explicitly broadens scope beyond telecom gear.

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 concrete when-to-use guidance: get exact port names from list_serial_ports, load device settings via preset from list_presets, and use detect_baud when baud is unknown. It also explains how to choose terminal mode based on what the device prints, and how connection naming affects subsequent tools.

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

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

With zero annotations, the description carries the full burden and does well: it discloses the DTR side effect ('opening a port resets many Arduinos'), the scoring heuristic (share of printable text), that candidates are opened briefly, and that wrong rates yield garbage or nothing. Minor gaps remain — it never explicitly states the port is closed afterward or what happens when no rate succeeds — but the truly hazardous behavior is surfaced.

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

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

The structure is well front-loaded: purpose sentence, then mechanics, then caveats, then a compact arg list. It is on the longer side, but nearly every sentence earns its place — the Arduino reset and CAT caveats are non-obvious and critical. Only slight redundancy (the default rates are stated in prose and implied by the schema's null default) keeps it from a 5.

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-shape documentation is not required, and the description covers purpose, side effects, parameter semantics, and defaults thoroughly. The main omissions are failure behavior (what happens if no candidate produces readable text) and worst-case runtime (settle × candidate count), which an agent scheduling a call might want to know. For a 5-parameter tool with no annotations, this is still a strong, near-complete definition.

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

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

Schema description coverage is 0%, so the description must compensate — and it does for all five parameters. It adds the crucial 'must not be open here' precondition to port, clarifies probe's empty-sends-line-ending behavior, explains the enum values' purpose ('NONE' for CAT), and enumerates the actual default candidate rates, which the schema hides behind null. Every parameter gains meaning beyond the raw 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 first sentence names a specific verb/resource/outcome — 'try common baud rates on a closed port and rank them by how readable the reply is.' This clearly separates it from all 28 siblings, none of which perform baud detection, so an agent can select it unambiguously.

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

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

It gives an explicit trigger condition: 'Use when the user doesn't know the device's rate.' It also adds a strong precondition ('port must not be open here') and device-specific usage advice (Kenwood CAT needs probe="ID;" with probe_line_ending="NONE"). It doesn't name alternatives, but no sibling covers this function, so exclusions are unnecessary.

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

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

With no annotations provided, the description carries the full burden for behavioral disclosure. It mentions that closing frees the port for other programs, but it does not disclose side effects such as terminating ongoing communication, whether the action is reversible, or what happens if no connection exists. This is minimal for a mutation-like operation.

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

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

The description is succinct and well-structured. The main purpose is stated upfront, and the argument explanations are concise with no filler or redundant 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 description covers the parameters and the primary effect, but it lacks usage guidance and behavioral nuance. It doesn't mention error conditions or how to recover, though the output schema exists so return values aren't needed. For a simple disconnect operation, it is adequate but not comprehensive given the absence of annotations.

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 zero per-parameter descriptions, so the tool description must compensate. It clearly explains both parameters: 'connection' identifies the specific connection and defaults to the current one, and 'all_connections' closes every open port. This adds meaningful semantics beyond the schema's bare properties.

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 and resource: 'Close a serial port and free it for other programs.' This is specific and distinguishes the tool from siblings like 'clear_buffer' (which clears data) and 'connect' (which opens a port).

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 state when to use this tool versus alternatives. It only implies usage when you want to close a port, but it lacks conditions, prerequisites, or guidance on when not to use it. No alternative tools are mentioned.

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

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

With no annotations, the description carries the behavioral disclosure burden. It explains what each step does, that each step's output is returned, how no-send/no-expect steps behave, and what auto_reply and stop_on_timeout do. It does not cover failure/error behavior or side-effect safety, but the core interaction model is transparent.

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 well-structured and economical: purpose first, a compact illustrative example, then clear imperative notes on step semantics followed by an Args list. Every sentence adds useful information without repetition.

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

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

The description covers the main usage scenario, step structure, parameter semantics, and defaults, while the schema handles nested field details and an output schema exists for return values. Minor gaps remain: behavior when stop_on_timeout is false and how failures are surfaced to the agent.

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?

Top-level schema coverage is 0%, and the description compensates by explaining all four top-level parameters, including defaults and a concrete JSON example. Nested step fields are left to the schema, which already provides descriptions for 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?

The description states a specific verb and resource: 'Run a scripted sequence of send-and-wait steps in one call.' It also distinguishes the tool from one-call-per-line approaches and from siblings like send_text/read_until_prompt by framing it as a batched, scripted flow.

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 explicitly says to use this for 'login flows and multi-step commands instead of one tool call per line,' which gives clear context for when it applies. It does not name alternative sibling tools explicitly or state when not to use it, so it stops short of full exclusion guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the tool is a non-destructive, rolling 256 KB record, and that it does not consume data (unlike read tools). It also notes the resource alias. It doesn't mention side effects, permissions, or error behavior, but the core behavior is well disclosed.

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

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

The description is two short paragraphs, with the primary purpose front-loaded. It provides necessary detail about the rolling buffer and the alternative resource without redundancy. It could be slightly more compact, but it is efficient and well organized.

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 explains the tool's behavior and use case well, but it omits parameter semantics and any prerequisites (e.g., a connection must exist). An output schema exists, so return format is covered, but the missing parameter documentation leaves the tool incomplete for an agent to call correctly without additional inference.

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. It does not explain what 'connection' refers to (e.g., the connection name from connect) or how 'last_bytes' relates to the returned tail. The description implies a tail but leaves the parameters ambiguous. This is a significant gap given no schema-level 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 ('Return') and resource ('tail of everything received on a connection'), and clearly differentiates itself from read tools by highlighting the rolling buffer that persists regardless of consumption. This distinguishes it from siblings like read_available and read_until_prompt without needing to name them.

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

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

The description explains the primary use case: re-reading output that was already consumed or arrived between calls. It contrasts with 'read tools' generically but doesn't explicitly name alternatives or provide exclusion conditions. It also mentions an alternative access method via a resource, which adds useful context. However, it could be more explicit about when to use this over specific 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?

With no annotations, the description carries the behavioral disclosure burden. It explains what a preset includes, that explicit connect arguments override presets, and which device families are covered. It does not explicitly state side-effect-free behavior, but 'Show' plus the detailed contents sufficiently indicates a read-only listing.

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

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

The description is front-loaded with the core purpose and then adds concise supporting detail about preset contents, override behavior, and supported families. Every sentence earns its place, and there is no redundant repetition of the tool name 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?

For a zero-parameter listing tool with an output schema, the description is complete: it explains what presets are, what settings they supply, how connect interacts with them, and what families are available. No critical context is missing for selecting and invoking this tool.

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 has zero parameters and the schema shows an empty object, so there is no parameter semantics to document. The description instead adds value by explaining what the returned preset data contains and how it relates to connect, which is appropriate for a no-argument 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?

States a specific verb and resource: "Show the device presets `connect(preset=...)` understands, with their settings." The description distinguishes it from other tools by focusing on presets and explicitly relating them to connect. This is unambiguous and not a tautology of the tool name.

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: this tool is meant to reveal what presets connect accepts and what each preset configures. It does not explicitly state when not to use it or name alternatives, but the relationship to connect and the list of families makes the intended use obvious.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses what the tool returns—system name, human description, USB hardware id—and that already-open ports are marked. This goes well beyond the tool name and gives the agent useful expectations about the output and how to interpret 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 compact and front-loaded with the core action, followed by usage guidance and output details. Every sentence adds value, and there is no redundant or filler content. It is appropriately sized for the simplicity of the 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?

Given the zero-parameter interface, the available output schema, and the presence of sibling tools, the description provides everything needed to select and invoke the tool correctly. It explains when to call it, what it returns, and how to interpret the results. Nothing critical 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 has zero parameters, so the baseline is 4; the description accurately reflects that no arguments are needed. It adds context about how the returned values are meant to be used, such as passing the system name to `connect`. No parameter-level documentation is needed here.

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

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

The description states a specific verb and resource: 'List every serial port the computer can currently see.' It also differentiates the tool from sibling tools like connect and status by defining its role as the first step before connecting. The purpose is immediately understandable.

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 when-to-use guidance: 'Call this FIRST whenever the user wants to connect to a device but hasn't given an exact port name, or when a connection fails.' It also explains how the returned data supports the next step, making the tool's place in the workflow unambiguous.

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

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

With no annotations, the description carries the burden. It usefully reveals that it relies on lsof and that Windows does not support the underlying introspection, but it does not mention potential permission issues, behavior when no process holds the port, or whether the command has side effects. It is adequate but not fully transparent.

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 with no wasted words. The core purpose is front-loaded, usage guidance follows, and the Windows caveat is concise. Every sentence 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?

The tool is simple, has one required parameter, and an output schema is present, so return-value documentation is not the description's responsibility. The missing port-format guidance is a minor gap; overall the context is sufficient for an agent to invoke the tool appropriately.

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

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

Schema description coverage is 0%, and the description only clarifies that the argument is a serial port. It does not provide expected port formats (e.g., /dev/ttyUSB0) or connect it to the output of list_serial_ports. The description adds only marginal meaning beyond the schema's 'Port' title.

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 ('Report which program currently holds a serial port') with a clear resource and platform scope ('macOS/Linux, via lsof'). This is immediately distinguishable from sibling tools like list_serial_ports or connect.

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 says when to use it: 'Use when connect says the port is in use, or before asking the user to close something.' This is clear contextual guidance, though it does not name alternative tools or explicitly state when not to use the tool.

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?

There are no annotations, so the description must disclose behavior on its own. It explicitly states that the line is always restored even if interrupted and that the tool is refused in read-only mode, which are important side-effect and safety details. It does not cover connection-related behavior, but the core behavioral contract is clear.

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 compact and front-loaded: the core behavior appears in the first sentence, followed by practical uses and important caveats. Every sentence adds value and 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?

With an output schema present, the lack of return-value detail is acceptable. The main gap is the undocumented connection parameter, but the description otherwise provides enough operational context for an agent to select and 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 0%, yet the description explains line, level, and ms in context: DTR/RTS choices, boolean level, and millisecond duration. The connection parameter is not explained, so the parameter semantics are strong but 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?

The first sentence states a precise operation: drive DTR or RTS to a level for a specified duration, then restore it. This clearly distinguishes pulse_line from siblings like set_lines or send_break, which involve sustained or different line manipulation.

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 Uses section gives concrete scenarios (Arduino reset, bootloader entry, PTT timing) and even suggests typical parameters such as DTR and 100 ms. It does not explicitly say when not to use the tool or name alternatives, so it stops 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?

With no annotations, the description carries the full burden and does well: it discloses that the buffer is cleared first, that reads continue until a prompt or idle period, and the special behavior when prompt is empty or no prompt exists. It does not describe timeout/error behavior, but the output schema likely covers the 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?

The description is front-loaded with a one-line summary, then a concise use-case paragraph, then a tight Args list. Every sentence adds operational detail and no filler is present.

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

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

Given five parameters and a convenience composition, the description explains the workflow, parameter semantics, and edge cases thoroughly. It leaves timeout behavior and return formatting to the output schema, which is acceptable.

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%, but the Args section documents every parameter with type, defaults, examples, and special values (e.g., prompt='' forces idle-terminated read). It even clarifies line_ending choices and connection default, fully compensating for the schema's bare titles.

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?

Description opens with a precise three-step verb sequence—clear buffer, send ASCII command, and read reply—and names itself a convenience wrapper. This clearly separates it from siblings like send_text, clear_buffer, and read_until_prompt, which each handle only part of the workflow.

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

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

It explicitly scopes the tool to the common 'ask the device something and read its answer' case and explains when idle-terminated reading is best. It does not enumerate exclusions or name alternative tools for non-convenience cases, though the 'see send_text' reference hints at related primitives.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses that nothing is transmitted, that it waits up to read_timeout for first bytes, that it settles briefly to capture a full chunk, and that it returns data as both text and hex. This gives an agent a solid model of runtime 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?

Three sentences, tightly packed, with the core behavior front-loaded and no filler. Every sentence earns its place: what it does, when to use it, and how it behaves.

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 strong for a no-annotation tool: it covers purpose, use cases, timeout behavior, and return format, and an output schema exists to detail the response. The main gap is the unexplained connection parameter and the lack of explicit exclusions versus related tools, but these are minor and do not prevent correct invocation for the stated use cases.

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. It adds real meaning for read_timeout ('Waits up to read_timeout for the first bytes'), but the connection parameter is never explained and is only represented by its name and default. This is a partial, not complete, semantic contribution.

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

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

The description opens with a specific verb and resource: 'Drain and return whatever the device has sent, without transmitting anything.' It clearly distinguishes this read-only drain operation from sibling send/query/expect tools, and gives concrete example uses like syslog, GPS, sensors, and binary replies after send_hex.

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 states explicit use cases: unsolicited/streaming output and grabbing a binary reply after send_hex. It does not explicitly list when not to use it or name alternatives like read_until_prompt, but the guidance is clear enough for an agent to select it appropriately.

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

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

With no annotations provided, the description carries the full burden. It explains buffer behavior (returns up to and including the prompt, leaves the rest), continuous reading for full multi-page capture, and auto_reply handling. It also details prompt matching semantics, including the literal-match default and echo caveat. This is comprehensive for a non-annotated tool.

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

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

The description is well-structured: opens with the core function, then adds context, then a typical flow, then per-parameter details. Every sentence adds value, no fluff. The length is justified by the tool's complexity, and the most important usage guidance 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?

Given the tool's complexity (5 optional parameters, auto_reply dict, connection handling) and no annotations, the description covers all necessary aspects: what it returns, buffer semantics, timeout, prompt matching details, and auto_reply. An agent has enough to invoke it correctly without external context. The presence of an output schema further reduces the need to describe return structure.

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

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

Schema description coverage is 0%, so the description must fully document parameters. It explains prompt (with examples and default behavior), timeout (seconds), regex (with example), auto_reply (with trigger examples), and connection (with default). Each parameter gains meaning beyond the bare schema type, making this a model of 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 opens with a specific verb and resource: 'Read accumulated output until a prompt appears, or until timeout.' It then specifies it's for interactive CLI sessions, which distinguishes it from sibling tools like send_text, read_available, or expect. The purpose is unambiguous and not a tautology.

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 explicitly says 'This is the right tool for interactive CLI sessions (routers, switches, shells)' and provides a typical flow with send_text. However, it does not name specific alternative tools or state when NOT to use it, leaving some inference to the agent. Still, the context is clear enough for correct selection.

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

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

With no annotations, the description carries the full burden. It transparently explains that connections are remembered across sessions, that no name reopens the most recent, and that it advises using 'connect' when no remembered connection exists. It does not cover edge cases like port unavailability, but the core behavior is well disclosed.

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

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

The description is concise, with the main purpose front-loaded. Every sentence adds value: the core action, the memory feature, the optional name behavior, the typical use case, and the fallback. No redundancy or unnecessary detail.

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

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

For a tool with one optional parameter and no annotations, the description fully covers when to use it, what it does, and how it behaves in edge cases. The output schema is present, so return values are presumably documented elsewhere. Nothing essential is missing for correct invocation.

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

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

The single parameter 'name' is fully explained: with no name, it reopens the most recent connection. This goes beyond the schema's default value and gives the agent clear meaning for the parameter, compensating for the 0% schema description 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 clearly states the tool reconnects to a remembered port with the same settings, using a specific verb ('reconnect') and resource ('remembered port'). It also differentiates from sibling 'connect' by explaining the fallback when nothing is remembered, making its purpose distinct.

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 guidance is provided: it is handy at the start of a chat to avoid repeating port and baud settings, and if nothing is remembered, it directs the user to use 'connect' instead. This clearly states when to use this tool versus the 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?

With no annotations provided, the description carries the full behavioral burden, and it delivers: it explains that read actions return replies immediately, move actions return nothing, and that the agent should confirm by reading position afterward. It also frames the tool as a command builder rather than an executor, which sets correct expectations.

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 compact, front-loaded with the core purpose, and every sentence adds operational value. The action list is dense but efficiently encodes command syntax and reply behavior without unnecessary prose.

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

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

For a builder tool with four parameters and no annotations, the description covers purpose, action semantics, protocol commands, and response expectations. It could add explicit ranges for azimuth/elevation, but the provided protocol syntax and output schema presence make it sufficiently complete for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It maps action enum values to their wire commands (C, C2, B, M<az>, W<az> <el>, X1..X4), thereby giving meaning to azimuth, elevation, and speed parameters. It does not formally describe parameter ranges, but the protocol syntax is sufficiently illustrative.

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

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

The description opens with a specific verb and resource: 'Build a Yaesu GS-232A/B rotator command' for send_text or query_text. The action list with protocol codes makes it immediately distinguishable from sibling builders like civ_build and cat_build.

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 clearly states the target functions (send_text with CR, query_text) and gives practical guidance, such as reading position after move actions because moves reply nothing. It does not explicitly name alternatives or exclusion conditions, but the context is clear enough for an agent to select this tool appropriately.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It states accepted reply formats and the rejection signal, but does not describe exact return shape, handling of unrecognized input, or normalization. The output schema may help, but behavioral details are minimal.

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 focused sentence with substantive examples and no filler. It is concise and front-loaded, though the example formats could have been more clearly separated for readability.

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 parser with an output schema, the description covers the important input formats and the rejection case. It lacks explicit edge-case guidance, but nothing essential is missing for selecting and calling the tool.

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 provides no parameter description beyond the name 'reply', so the description compensates by listing concrete valid formats: '+0180', '+0180+0045', and 'AZ=180 EL=045'. This gives meaningful guidance for constructing a valid reply string, though whitespace or trimming rules are not specified.

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 identifies a specific verb ('decode'), a resource ('GS-232 reply'), and the output ('azimuth/elevation degrees' or rejection). The included format examples make it easy to distinguish from sibling parsers like civ_parse and cat_parse.

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 intended context is implied by the GS-232 protocol mention, but there is no explicit when-to-use guidance or comparison with alternatives such as cat_parse or civ_parse. An agent must infer that other parse tools handle different protocols.

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

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

With no annotations, the description carries the behavioral burden. It discloses that the tool returns a row-of-text representation with cursor position, and that reset clears the screen model after garbage or resize. This gives an agent a good sense of side effects and state, though it does not discuss connection-level effects or failure modes.

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 compact and well-structured: main purpose first, then use-case context, then parameter explanations. Every sentence contributes useful information, with no 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?

The tool has an output schema, so return-value details are already covered. The description supplies the necessary behavioral context, usage pattern, and parameter semantics, making it complete for an agent to select and 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 0%, so the description must compensate. It does: reset is explained as clearing the screen model after garbage or resize, and connection is explained as an open connection name with a default. This adds meaningful semantics beyond the raw boolean/string 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?

Description states a specific verb ('Show') and resource ('current terminal screen of a vt100/xterm connection'), and adds concrete detail about what is displayed (rows of text, cursor position). It clearly distinguishes the tool from siblings like read_available or status by framing it as the way to read full-screen interfaces.

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 explicitly says this is how to read full-screen interfaces and gives a concrete usage pattern: press keys with send_keys, then look at the screen again. It does not explicitly compare against alternatives, but the guidance is clear enough to know when to use screen versus simpler text-reading tools.

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

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

The description discloses the physical behavior (TX held low), the duration parameter, and the read-only mode refusal. Since no annotations are provided, the description carries the full burden, and it does so well. It doesn't mention side effects like whether the connection must be active or what happens if ms is 0, but the core behavioral traits are covered.

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 compact and front-loaded: the first sentence states the action and key parameter, the second provides usage context, and the third states a critical constraint. Every sentence earns its place with no redundancy.

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

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

For a simple two-parameter tool with an output schema, the description covers the essential behavioral context, usage scenarios, and a key restriction. The only notable gap is the undocumented 'connection' parameter, but the tool's simplicity and the output schema reduce the need for more detail.

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. It explains 'ms' as the duration in milliseconds, which adds meaning beyond the schema's bare integer type. However, it doesn't explain the 'connection' parameter at all, leaving the agent to infer that it identifies which serial connection to use. The description partially compensates but leaves a 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?

The description states a specific verb ('Send') and resource ('BREAK condition (TX held low)') and explains the purpose with concrete examples (ROMMON, attention signal). It clearly distinguishes this from sibling tools like send_text, send_hex, and pulse_line by focusing on the BREAK condition.

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 when to use it ('Some consoles use BREAK to enter ROMMON or interrupt boot; some serial devices use it as an attention signal') and explicitly states a key exclusion: 'Refused in read-only mode.' It doesn't name alternative tools, but the context is sufficient for an agent to decide when this is the right tool.

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

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

With no annotations, the description carries the full burden. It discloses key behavioral traits: 'Writes to TX only; does NOT read', spaces in hex are ignored, and clear_buffer_first discards buffered RX. This goes well beyond the schema. It stops short of stating behavior on invalid hex or whether the call blocks, but the core behaviors an agent needs are transparent.

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

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

The description is front-loaded with the core behavior and uses a compact paragraph for context followed by a clean bullet-style Args list. Every sentence serves a purpose: scope, example, usage guidance, parameter explanations. No filler or redundancy.

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

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

Despite the tool's complexity (binary protocol handling), the description gives an agent everything needed to invoke it correctly: input format, connection default, buffer-clearing behavior, and the recommended read path. The output schema exists to explain return values, so the description's omission of that is acceptable. Even without annotations, the instructions are complete for correct use.

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 all three parameters. It does: hex_bytes format with an example, clear_buffer_first meaning ('Discard buffered RX before sending'), and connection semantics ('Which open connection (name). Default: the current one.'). This fully bridges 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 the action as 'Send raw bytes given as hex' and immediately notes 'Writes to TX only; does NOT read,' which distinguishes it from read tools. The mention of binary protocols and Icom CI-V differentiates it from send_text and other text-oriented siblings. It is specific, unambiguous, and an agent can select it 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?

Explicitly says 'Use for binary protocols — notably Icom CI-V', gives an example, and contrasts with read_until_prompt: 'binary replies rarely have a text prompt, so read_until_prompt usually isn't the right tool for these.' It also recommends the correct follow-up pair (read_available + civ_parse), giving clear when-to-use and when-not-to-use direction.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool only sends keys and does not read any output ('Nothing is read'), which is a critical behavioral trait. It also hints at the encoding format. While it doesn't mention permissions or rate limits, these are less relevant for a terminal key sender, and the key behavioral aspect (non-reading) is clearly stated.

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

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

The description is front-loaded with the core purpose and then provides essential examples and usage details. Every sentence adds value: the encoding note, the use cases, the list of valid key names, and the post-action guidance. It is appropriately sized for a tool with a rich input format, and the structure is logical.

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 complete for an agent to use the tool correctly. It covers the key input format, the types of keys, the encoding, and the fact that it doesn't read output. It also mentions follow-up actions and distinguishes from send_text. The output schema exists (though not shown) so return values need not be described. The only minor omission is the 'connection' parameter, but it is optional and likely clear from context.

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

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

The schema has only a generic array of strings for 'keys', but the description extensively explains the allowed values: key names ('ctrl-c', 'esc', 'tab', etc.), single characters, and 'text:...' for literal runs. This adds significant semantic meaning beyond the schema. The 'connection' parameter is not explained, but it is optional and likely self-explanatory, so the main parameter is well covered.

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 a specific verb ('Press keys') with a precise resource ('keys by name') and encoding standard ('VT100/xterm terminal'). It explicitly distinguishes itself from send_text by listing what send_text cannot type, which differentiates it from sibling tools like send_text and send_hex.

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 when-to-use guidance: 'Use it for what send_text can't type' and provides concrete examples (Ctrl-C, Ctrl-Z, Esc, Tab, arrows, etc.). It also mentions what to do after ('Nothing is read; follow with read_until_prompt, read_available, or screen'), which clarifies the workflow and alternative tools.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly. It discloses TX-only behavior, device echo behavior, stale-buffer handling, non-ASCII replacement with '?', default connection line ending, and default connection selection.

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 detailed but every sentence earns its place: purpose, behavioral notes, then a clearly structured Args section. It front-loads the most important distinction (TX only, does not read) and keeps parameter explanations compact.

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 complete for an agent to invoke this tool correctly. It covers all four parameters, the read-after-send workflow, the sibling tool to use for raw bytes, and buffer-clearing behavior; the existing output schema covers return-value expectations.

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

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

The schema provides 0% description coverage, so the description must compensate, and it does. It explains data with concrete examples, defines each line_ending value including default behavior, clarifies clear_buffer_first semantics, and states the connection default.

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

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

The description opens with a specific verb and resource: 'Send an ASCII command to the device' and immediately distinguishes itself from read operations with 'Writes to TX only; does NOT read.' This clearly differentiates it from siblings like read_until_prompt, read_available, and send_hex.

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: after sending, call read_until_prompt or read_available to see output, use clear_buffer_first=True to discard stale output, and use send_hex for raw bytes or non-ASCII data. These are concrete when-to-use and when-not-to-use instructions referencing sibling tools.

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

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

With no annotations provided, the description carries the full behavioral burden and does so well: it discloses that the lines are held, that None leaves a line unchanged, that True/False drive the output, and that the tool is refused in read-only mode. This goes beyond the bare schema and gives the agent accurate state-change expectations.

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 main action is front-loaded in a single sentence, followed by compact use cases and caveats. Every sentence adds information; 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?

For a three-optional-parameter tool with an output schema, the description is nearly complete: intent, dtr/rts semantics, safety guidance, and read-only behavior are all covered. The only notable gap is the connection parameter, which is left to be inferred rather than explained.

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 description compensates for zero schema-description coverage by explaining dtr and rts semantics ('set it True to transmit, False to stop', 'DTR False' for reset, None to keep unchanged). However, the connection parameter is never explained, so a third of the parameters still lack semantic guidance.

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: 'Set the DTR and/or RTS output lines and hold them.' It also distinguishes itself from pulse_line by noting that pulse_line is safer for keying a transmitter, so the agent can tell it apart from a sibling 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?

It gives concrete when-to-use scenarios: keying a PTT wired to RTS/DTR, holding an Arduino in reset, and signaling a modem. It also gives an exclusion by recommending pulse_line as safer for PTT use, and explicitly warns 'Refused in read-only mode.'

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

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

With no annotations provided, the description carries full behavioral burden and largely succeeds: it discloses the comprehensive read-only scope across ALL open ports, the specific state domains covered, and the empty-state behavior. It stops short of explicitly confirming non-mutation or data freshness, but the verb 'Report' plus the disclosed edge case gives solid coverage for a status tool.

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

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

Two sentences with zero waste. The core verb-action is front-loaded ('Report every open port'), the content enumeration is compact yet informative, and the edge-case sentence earns its place by covering the nothing-open scenario. Every clause adds 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?

Complete for a no-argument diagnostic tool. Zero parameters remove the parameter-documentation burden, an output schema exists to cover return values, and the description handles every remaining question an agent could have: what is reported, over what scope, and what happens with no open ports. 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?

Zero parameters, so the baseline is 4. The description reinforces the no-argument global-report nature ('every open port') consistent with the empty input schema, and adds that no target/port selection is needed. There is nothing more the description could meaningfully add about 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?

Specific verb 'Report' plus resource 'every open port', followed by an enumerated list of content categories (settings, reader state, buffered bytes, control-line states, capture, current connection). The second sentence adds scope precision by describing the no-connection case. This clearly differentiates it from siblings like list_serial_ports (hardware discovery), connect/disconnect (lifecycle changes), and read_available (data reading) — it is unambiguously the connection-state reporting 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?

The diagnostic use case is implied rather than stated: 'Report every open port' signals this is the tool to call when you need current connection state, and the edge-case sentence tells the agent it still returns useful information when nothing is open. However, among 29 siblings, the description never explicitly names alternatives (e.g., screen, read_available, port_in_use_by) or states when NOT to use it, so routing 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.