Server Quality Checklist

Tool Scores

• lib_searchC
  2.7/5.0
  Behavior1/5

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

  The description is a single declarative sentence with no behavioral disclosure. It lacks any mention of side effects, return format, network requirements, or error behavior. Since annotations are missing altogether, the description carries the full burden, and it fails to provide even basic transparency beyond the tool's name.

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

  Conciseness3/5

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

  The description is extremely concise and front-loaded, but it is under-specified. While there is no verbosity, the brevity omits essential usage and behavior details. It earns a 3 rather than a higher score because conciseness alone is not sufficient if important information is missing.

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

  Completeness3/5

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

  Given the tool's simplicity (one parameter, no output schema), the description is minimally adequate for invoking it with the correct parameter. However, it does not convey what the search returns (e.g., list of libraries), which an agent would need to decide whether results are actionable. No annotations or output schema compensate, so a 3 is a fair assessment.

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

  Parameters3/5

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

  The input schema fully documents the single 'query' parameter with description and example, achieving 100% coverage. The tool description adds no additional semantics about the parameter, so it relies on the schema. Per the rubric, baseline is 3 when schema coverage is high, which is appropriate here.

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

  Purpose4/5

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

  The description clearly states the action ('Search') and the resource ('Arduino Library Manager'), with the specific mechanism (query string). It is unambiguous and distinct from sibling tools like lib_install or core_list. However, it could have explicitly contrasted with these to preempt ambiguity, so it falls short of a 5.

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

  Usage Guidelines2/5

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

  No information is provided about when to use this tool versus alternatives. The description does not mention that searching is a precursor to installing, nor does it explain any exclusions or conditions. An agent is left to infer from the name alone, which is insufficient.

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

• rattus_heartbeatC
  2.9/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden. It states 'Uses open serial port' but does not disclose potential side effects, prerequisites (like serial_open), or whether this is a read-only or mutating operation. The heartbeat streaming behavior is implied but not detailed.

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

  Conciseness4/5

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

  The description is a single concise sentence that is front-loaded with the core action, and the context is mentioned early. It is efficient, albeit slightly under-specified in detail.

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

  Completeness3/5

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

  Given the tool's moderate complexity (4 parameters, no output schema) and lack of annotations, the description is partially complete: it covers the purpose and main parameter semantics via schema defaults, but lacks behavioral context and usage guidance. It is a minimum viable description, not comprehensive.

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

  Parameters3/5

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

  Schema coverage is 50%, and the description only implies the timing (durationMs and periodMs) without explaining vMmS and omegaMradS. The schema provides descriptions for periodMs and durationMs, but the two velocity parameters remain undocumented, so the description adds minimal value beyond the schema.

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

  Purpose4/5

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

  The description states the specific action (send CMD_TWIST heartbeats at ~20 Hz) and the resource (serial port), which distinguishes it from simple command tools. However, it does not explicitly differentiate it from the sibling rattus_send_twist, which likely has a similar purpose.

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

  Usage Guidelines2/5

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

  The description mentions a specific context ('Phase 2.7 soak / link-up') but provides no guidance on when to use this tool instead of rattus_send_twist, nor any exclusion criteria. The agent is left to infer the appropriate usage context.

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

• list_portsB
  3.2/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full behavioral responsibility. It only says 'List' which implies a read-only snapshot, but it does not disclose whether the operation is guaranteed to be non-mutating, whether it may require specific system permissions, or what happens if no ports are found. This leaves the behavioral profile under-specified.

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

  Conciseness5/5

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

  Exactly one sentence, front-loaded with the actionable verb, and includes a short parenthetical with concrete examples. No wasted words or redundant detail.

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

  Completeness3/5

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

  The tool is very simple (no inputs, no documented output schema), so the description conveys the core purpose. However, it doesn't explicitly state the return format (e.g., list of port names strings) or any error conditions, leaving minor but relevant gaps.

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

  Parameters4/5

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

  There are zero parameters, so the description needs no parameter information. The baseline for zero-parameter tools is 4, and there is no parameter-related gap to address.

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

  Purpose4/5

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

  The description clearly states the verb 'List' and the resource 'serial ports detected by arduino-cli', with examples of port types. It is unambiguous and distinguishable from siblings like board_list or core_list, but it does not explicitly contrast itself with any alternative tool.

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

  Usage Guidelines2/5

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

  There is no guidance on when to use this tool versus alternatives. It doesn't mention scenarios where listing ports is appropriate (e.g., before upload) or any prerequisites. The agent is left to infer context from the description alone.

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

• lib_installB
  3.3/5.0
  Behavior2/5

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

  No annotations are provided, so the description alone must disclose behavioral traits. It only says 'Install' without mentioning potential side effects such as overwriting existing library versions, requiring network access, modifying global configuration, or what happens if a library is already installed.

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

  Conciseness5/5

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

  A single, direct sentence with no filler. The core action and target are clearly communicated in minimal words.

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

  Completeness3/5

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

  For a simple single-parameter install tool, the description covers the essential intent. However, it lacks any detail about return values, error conditions, or behavioral nuances (e.g., installing latest versions by default). Given the absence of an output schema and annotations, a bit more context would make it more complete.

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

  Parameters3/5

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

  Schema description coverage is 100%, with the schema stating 'Library names as known to Library Manager'. The description adds no extra semantic detail beyond the schema, but the schema adequately documents the single parameter, so a baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description states a specific verb ('Install'), a clear resource ('Arduino libraries'), and the source ('from Library Manager'). This distinguishes it from sibling tools like core_install (which installs cores) and lib_search (which searches libraries).

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

  Usage Guidelines2/5

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

  The description gives no guidance on when to use this tool versus alternatives such as lib_search or core_install. There is no mention of prerequisites, version selection, or when a different installation approach might be preferred.

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

• serial_closeB
  3.4/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full burden. It states the action (close) but does not disclose side effects, such as whether pending data is flushed, whether the port becomes available for other processes, or any error conditions. For a mutating operation, this is a notable gap.

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

  Conciseness5/5

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

  A single sentence with no wasted words. The action and target are both present, and it is appropriately sized for a tool with no parameters.

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

  Completeness3/5

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

  The tool is simple and parameterless, so the description covers the basic call. However, with no annotations and no output schema, details about return values (if any) or failure states are absent. An agent might need to know if closing fails, but for a straightforward close operation this is acceptable.

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

  Parameters4/5

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

  There are 0 parameters, so the schema provides no semantics to clarify. The description confirms no inputs are needed, and with no parameters there is nothing to compensate for. Baseline of 4 applies because the description is sufficient for a parameterless tool.

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

  Purpose4/5

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

  The description uses a specific verb 'Close' and resource 'currently open serial port session', clearly indicating the action and scope. It distinguishes from siblings like serial_open and serial_status, though it doesn't name them explicitly.

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

  Usage Guidelines3/5

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

  The description implies usage: it should be called after a session is open, but it does not state when not to use it or mention alternatives. The context is clear enough that an agent can infer it pairs with serial_open.

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

• core_installA
  3.6/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full responsibility for behavioral disclosure. It only states the installation action, without mentioning potential side effects like downloading files, requiring network access, modifying local storage, or prerequisites such as running core_list first. This is a significant gap 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.

  Conciseness5/5

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

  The description is one clear sentence followed by two illustrative examples. No filler words, front-loaded with the action, and every element contributes to understanding the tool's purpose.

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

  Completeness4/5

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

  For a simple tool with a single well-defined parameter and no output schema, the description is largely sufficient. The main missing context is behavioral (side effects), already penalized in behavioral_transparency. Given the low complexity, the description adequately covers the essential information needed to invoke the tool.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already fully documents the platformId parameter. The description adds value by providing concrete examples (arduino:avr, arduino:mbed_portenta), but this is supplementary rather than essential, keeping the score at the baseline.

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

  Purpose5/5

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

  The description uses a specific verb 'Install' with a resource 'Arduino core/platform by id' and provides concrete examples (arduino:avr, arduino:mbed_portenta). It clearly distinguishes this tool from siblings like core_list or lib_install by stating the action and target.

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

  Usage Guidelines3/5

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

  The description implies when to use it — when a specific core needs to be installed — and gives example IDs, but it does not explicitly state alternatives or conditions not to use it. Usage context is implied rather than fully articulated.

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

• compileA
  3.7/5.0
  Behavior2/5

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

  There are no annotations, so the description carries the full burden of behavioral disclosure. It states that compilation occurs, but does not mention side effects such as writing build artifacts, or what output or errors can be expected. As a build operation this is relatively benign, but the absence of any behavioral detail beyond the action itself leaves a clear gap.

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

  Conciseness5/5

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

  The description is two clean sentences with no filler. It front-loads the core purpose and immediately gives useful board mappings, so the structure is efficient and easy for an agent to parse.

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

  Completeness3/5

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

  Given no annotations and no output schema, the description is adequate to convey the command's purpose and required inputs, but it does not describe expected output, failure modes, or prerequisites like installed cores. For a moderately complex tool with six parameters, this is a noticeable but not critical gap.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3. The description does add a helpful FQBN example (arduino:mbed_portenta:envie_m7) that is not in the schema, but it does not add deeper meaning for sketchPath or the optional parameters, which are already well explained in the schema.

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

  Purpose5/5

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

  The description uses a specific verb and resource ('Compile a sketch for a board FQBN') and explicitly contrasts with uploading, making the tool's purpose clear and distinguishable from the sibling 'upload' tool. The concrete FQBN examples further reinforce what action is being described.

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

  Usage Guidelines4/5

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

  It clearly states the operation is 'without uploading', giving context that this tool is for compiling rather than flashing, and it provides example board names to indicate target platforms. However, it does not explicitly say when to prefer this tool over alternatives like 'upload' or 'core_install', relying mostly on inference.

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

• board_listA
  3.8/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. It discloses a key behavioral nuance ('when possible') regarding FQBN detection, which is useful. However, it does not state whether the operation is read-only, what happens on failure, or any system requirements, though these are less critical for a simple listing tool.

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

  Conciseness5/5

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

  The description is a single efficient sentence that front-loads the main action and resource, then adds a concise caveat and a sibling reference. There is no fluff or redundant information.

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

  Completeness4/5

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

  For a simple read-oriented tool with one optional parameter and no output schema, the description covers the core purpose, a limitation, and its relationship to a sibling. It does not explain return structure or edge cases, but these are secondary for this tool type.

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

  Parameters3/5

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

  The single parameter (discoveryTimeout) is fully described in the input schema (100% coverage), so the description does not need to add details. The description does not mention the parameter, but the schema already covers it adequately, matching the baseline.

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

  Purpose5/5

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

  The description uses a specific verb 'List' with a clear resource ('connected boards') and adds 'detected FQBN when possible' to specify the output detail. It immediately distinguishes itself from the sibling tool list_ports by calling itself a 'companion', making its scope clear.

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

  Usage Guidelines3/5

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

  The phrase 'Alias-friendly companion to list_ports' implies a complementary relationship and hints at alternative usage, but it does not explicitly state when to use board_list over list_ports or provide exclusion criteria. The guidance is present but left to inference.

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

• uploadA
  3.8/5.0
  Behavior2/5

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

  No annotations are available, so the description bears full responsibility. It describes the high-level action but says nothing about side effects (e.g., overwriting the board's current sketch), prerequisites beyond serial port, error handling, or the meaning of 'verify'. The only behavioral nuance offered is that upload does not accept --libraries.

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

  Conciseness5/5

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

  Two sentences with no redundant phrasing; the primary action is stated first, then the workflow note.

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

  Completeness2/5

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

  Given there is no output schema or annotations, and this is a flashing operation that can fail for many reasons (wrong port, missing bootloader, bad build), the description omits what the tool returns on success/failure and expected runtime behavior. The instruction to compile first is useful, but more could be added without bloating the text.

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

  Parameters3/5

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

  Schema already describes fqbn, port, verify, inputDir, and sketchPath; 83% coverage means the heavy lifting is done there. The description adds a helpful cross-reference between compile's buildPath and upload's inputDir but does not explain the other parameters.

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

  Purpose5/5

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

  States exactly what it does: 'Upload a sketch to a board on a serial port.' This uses a specific verb and resource, and distinguishes from siblings like compile (not compiling) and serial I/O tools (not just reading/writing chars).

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

  Usage Guidelines5/5

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

  Explicitly instructs to compile first and pass the same buildPath as inputDir, and notes that upload does not accept --libraries. This gives both the recommended workflow and an exclusion.

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

• rattus_send_twistA
  3.9/5.0
  Behavior3/5

  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 framing (CRC-8/MAXIM), the target (Uno USB), and the requirement for serial_open. It does not mention potential side effects, error handling, or whether the operation blocks, but for a low-level write operation the disclosed details are reasonably transparent.

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

  Conciseness4/5

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

  The description is a single sentence that packs the essential information: what it does, the protocol, the target, and the prerequisite. No redundant words, and the key action and requirement are front-loaded. Slightly terse but very efficient.

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

  Completeness4/5

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

  Given the tool's simplicity and 100% schema coverage, the description covers the critical context (frame type, CRC, target, precondition). There is no output schema, and it doesn't explain return values, but for a write-only operation this is acceptable. It gives enough for an agent to invoke it correctly after ensuring serial is open.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the parameters are fully documented in the schema itself. The description adds no extra semantic detail about the parameters beyond what the schema provides, so a baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description states a specific verb (pack and write) and a specific resource (a CMD_TWIST frame to the open serial port), and it distinguishes itself from sibling tools by specifying the exact protocol and target. The mention of 'phase 2.7' adds context but the core action is unambiguous.

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

  Usage Guidelines4/5

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

  It clearly states the precondition 'Requires serial_open first', which is essential usage guidance. It doesn't explicitly name alternative tools for when not to use this, but the specialized nature of the tool and the precondition provide enough context for an agent to decide when to invoke it.

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

• serial_openA
  3.9/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. It discloses exclusive access and the default baud rate, and hints that a previous session must be closed before calling. However, it omits important behaviors such as what happens if the port is already open or unavailable, whether the call blocks, and what it returns on success or failure.

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

  Conciseness5/5

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

  Two concise sentences with no filler. The core purpose is front-loaded, and the additional instruction about closing previous sessions is brief and critical. The mention of 'Ratchet UART' provides small but useful context without bloating the description.

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

  Completeness3/5

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

  For a tool with no output schema and no annotations, the description should explain the outcome and possible failure modes. It tells the agent what the tool does and a prerequisite, but not what it returns, how errors are signaled, or how the opened port is referenced by subsequent sibling calls. This leaves gaps for an agent that needs to chain actions.

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

  Parameters3/5

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

  The schema covers 100% of the parameters with meaningful descriptions ('Serial port path, e.g. COM3' and 'Baud rate (default 115200)'). The description adds no new parameter information beyond repeating the default baud, so it neither enhances nor detracts from the schema.

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

  Purpose5/5

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

  Clearly states the operation: 'Open a serial port exclusively for read/write.' This is a specific verb and resource, and it distinguishes itself from siblings like serial_read, serial_write, and serial_close by being the opening operation. The mention of exclusive access adds precision.

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

  Usage Guidelines4/5

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

  Provides a key prerequisite: 'Close any previous session first,' which tells the agent to use serial_close before opening if needed. It implies that only one session can be active at a time, but it does not explicitly contrast with alternatives or state when not to use this tool (e.g., if already open).

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

• rattus_crc_self_testA
  4/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full behavioral burden. It conveys a nondestructive verification operation and names the expected check vector, but it does not disclose how the result is returned, what failure looks like, or whether any firmware connection is required.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence with no filler. It efficiently includes the action, scope, algorithm, firmware counterpart, and expected result, with every element earning its place.

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

  Completeness4/5

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

  For a zero-parameter tool with no output schema, the description is nearly sufficient: it states the operation and the expected result. It does not explicitly explain pass/fail semantics or side effects, but these are relatively minor gaps for a diagnostic self-check utility.

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

  Parameters4/5

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

  The input schema is empty and schema description coverage is 100%, so there are no parameters the description must document. The expected check vector 0xA1 adds useful context about what the test validates without needing parameter-level detail.

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

  Purpose5/5

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

  The description states a specific action and resource: it verifies host-side CRC-8/MAXIM compatibility against firmware RattusUart. The expected check vector 0xA1 makes the purpose concrete and clearly separates it from the serial, compile, and board-management sibling tools.

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

  Usage Guidelines3/5

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

  The 'self-test' name and the 'Verify...' phrasing imply a diagnostic use case, but the description does not explicitly state when to run it or contrast it with alternatives. No prerequisites or exclusion criteria are given, so usage guidance is present only by implication.

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

• serial_readA
  4/5.0
  Behavior4/5

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

  With no annotations, the description carries the full behavioral burden. It usefully discloses the ~64KB cap to protect context, a non-obvious trait that directly affects agent call planning. It does not cover blocking behavior, buffer drain, or return format, but the disclosed cap is significant.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the action and resource, immediately explains the context-protecting cap. No wasted words; every sentence earns its place.

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

  Completeness4/5

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

  Given the simple two-parameter read operation and no output schema, the description provides enough for correct calling: the buffer concept and context protection are communicated. Could be enhanced by clarifying empty-buffer handling and whether read drains remaining data, but not mandatory for a typical agent call.

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

  Parameters3/5

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

  Schema coverage is 100% and both parameters (encoding and maxBytes) are already documented with descriptions, defaults, and bounds. The description adds no additional parameter semantics, but the schema fully covers the needed context.

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

  Purpose5/5

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

  The description states a clear verb ('Read') with a specific resource ('buffered bytes from the open serial port') and an important constraint (buffer cap). It distinguishes this from siblings like serial_write and serial_status without requiring schema inspection.

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

  Usage Guidelines3/5

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

  It implies 'when open, read after write' but does not explicitly say when to use this over serial_status or other read-like alternatives. No mention of conditions like empty buffer or expected interactions, so the agent must infer the read flow from context.

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

• serial_writeA
  4/5.0
  Behavior3/5

  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 that the tool performs a write/transmit operation and hints at binary handling, but it does not clarify side effects such as whether the port must be opened first, what happens on failure, or whether queued data is sent atomically. There is no contradiction, but the behavioral description is minimal.

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

  Conciseness5/5

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

  Two sentences with zero unnecessary detail. The core action is in the first sentence, and the second adds the domain-relevant encoding tip. Every phrase earns its place.

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

  Completeness4/5

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

  For a simple write operation with no output schema, the description covers the essential action and the key binary-encoding nuance. It lacks explicit error conditions and the 'must open first' prerequisite, but those are common-sense for a write tool and the context is adequate for an agent to invoke it correctly in most scenarios.

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

  Parameters4/5

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

  The schema already names both parameters with descriptions, and the description adds the key semantic that hex/base64 is the proper encoding for binary UART frames, giving the agent concrete guidance on what to supply. This goes beyond the schema's generic 'Payload to send' and provides actionable value.

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

  Purpose5/5

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

  The description states a specific action ('Write data') on a specific resource ('the open serial port'), includes an example use case for binary UART frames, and is clearly distinct from sibling tools like serial_read or serial_status. An agent can immediately tell what the tool does and when it applies.

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

  Usage Guidelines3/5

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

  The description gives important encoding guidance ('Use hex/base64 for binary UART frames') and references an example, but it does not explicitly state when not to use the tool or alternative routes. The need for the port to be open is implied by 'the open serial port' but not spelled out as a prerequisite, and no mention is made of when to prefer a different command.

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

• serial_statusA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. 'Report' strongly signals a read-only operation with no side effects, and it explicitly lists the two pieces of behavioral information returned. It does not detail error behavior or clarify whether 'buffered' refers to incoming or outgoing bytes, but the core behavior is clearly disclosed.

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

  Conciseness5/5

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

  The description is a single sentence with no filler or redundant content. It front-loads the verb and the resource, making it immediately scannable for an agent.

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

  Completeness4/5

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

  For a zero-parameter, simple status tool with no output schema, the description covers both key return values: session open state and buffered byte count. A more complete definition might specify the exact return format or types, but this is a minor gap given the tool's simplicity.

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

  Parameters4/5

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

  The tool has zero parameters, so the schema provides no behavioral meaningful detail. The description correctly avoids inventing parameter explanations; a baseline of 4 is appropriate because there is nothing to explain and the description matches the parameter-free interface.

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

  Purpose5/5

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

  The description uses a specific verb ('Report') and clearly defines the resource: whether a serial session is open and how many bytes are buffered. This immediately distinguishes it from siblings like serial_open, serial_read, serial_write, and serial_close by identifying it as a status query.

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

  Usage Guidelines3/5

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

  The usage context is implied: an agent would use this tool to check session state or buffer occupancy, but there is no explicit guidance about when to prefer this over related tools, nor any stated exclusions. No alternatives are mentioned, leaving the choice to inference.

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

• core_listA
  4.3/5.0
  Behavior4/5

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

  No annotations are provided, but the verb 'List' clearly indicates a read-only, non-mutating operation. The description adds no unnecessary safety warnings but clarifies the scope (installed cores) and provides examples. This is sufficient for a simple listing operation.

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

  Conciseness5/5

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

  The description is one concise sentence that front-loads the purpose and includes two useful examples. Every word earns its place, and there is no redundant or irrelevant content.

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

  Completeness5/5

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

  For a zero-parameter, read-only tool, the description is fully self-contained. It states what the tool does and gives sample output values, which is enough for an agent to invoke it without confusion. No output schema is present, but the description compensates adequately.

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

  Parameters4/5

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

  The input schema has zero properties, so there are no parameters to document. The baseline for zero-parameter tools is 4; the description adds no parameter information, but none is needed. Examples clarify the expected output format.

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

  Purpose5/5

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

  The description clearly states the verb 'List' and the resource 'installed Arduino cores (platform packages)', with concrete examples (e.g., arduino:avr, arduino:mbed_portenta). This unambiguously distinguishes it from sibling tools like core_install or board_list.

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

  Usage Guidelines3/5

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

  The description does not explicitly mention when to use this tool versus alternatives, nor does it state exclusions. Usage is implied by the tool name and the action 'list installed cores', but an agent is not directly guided to choose core_list over similar tools like board_list.

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

• arduino_cli_versionA
  4.4/5.0
  Behavior3/5

  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 purpose (verification) and that it outputs a version, but does not mention behavior such as exit codes, stderr output, or whether it invokes external process. However, the tool is simple and the behavior is largely implied by the name and description. Without annotations, a 3 is appropriate since the description adds basic context but not deep behavioral detail.

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

  Conciseness5/5

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

  Two sentences, no wasted words. The first sentence states the core action and output, the second gives explicit usage timing. Front-loaded and efficient.

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

  Completeness4/5

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

  For a zero-parameter, no-output-schema tool, the description is nearly complete. It covers purpose, timing, and the output (version). Could improve by noting expected output format (e.g., exit code or exact version string), but given the tool's simplicity and the lack of any schema to compensate, it is sufficiently complete for an agent to invoke correctly.

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

  Parameters4/5

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

  The tool has zero parameters, so parameter semantics are trivially complete. The description does not need to explain anything about parameters. A baseline of 4 for 0 params is granted, and the description's focus on version reporting aligns with the tool's no-input nature.

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

  Purpose5/5

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

  Description clearly states the tool confirms availability of arduino-cli and reports its version. The verb 'confirm' plus 'report version' specifies the exact action and resource. Distinguished from sibling tools by naming the toolchain verification purpose before compile/upload.

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

  Usage Guidelines5/5

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

  Explicit guidance to call this first to verify the toolchain before compile/upload. This provides both when to use (before compile/upload) and context (verification step). Though no explicit alternative is mentioned, the instruction is clear and sufficient for a version-check tool with no siblings competing for the same role.

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