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

Annotations already declare readOnlyHint=true, and the description reinforces a non-mutating behavior ('Check', 'return instructions'), with no contradiction. It adds useful context by specifying the conditional outcome when the CLI is missing and OS-specificity of the instructions.

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

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

A single, front-loaded sentence states both the check and the conditional return behavior with no filler. Every word contributes to the tool's operational meaning.

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

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

For a zero-parameter read-only diagnostic with an output schema, the description covers the core behavior completely: what is checked and what is returned when missing. The presence of sibling install_arduino_cli also provides surrounding context for how this tool fits into the workflow.

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 no parameter-level meaning is needed. The description fully satisfies the parameter semantics dimension by not pretending to rely on any inputs; baseline 4 is appropriate.

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

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

The description states a specific action ('Check whether arduino-cli is available') and a resource ('arduino-cli'), making the tool's purpose immediately clear. It also differentiates from the sibling install_arduino_cli by focusing on detection and returning instructions rather than performing installation.

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 usage before installing or when verifying the CLI's presence: 'return OS-specific installation instructions if missing' indicates the tool is a diagnostic step. It does not explicitly name alternatives like install_arduino_cli, so it stops short of fully explicit when/when-not guidance.

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

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

Annotations already mark idempotentHint=true and destructiveHint=true, but the description adds no specificity about what destructive actions occur, such as cleaning build cache or exporting binaries into the sketch folder. It is consistent with the annotations and does not contradict them, but it provides no extra behavioral context.

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

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

The description is a single sentence with no filler and leads with the action and resource. It is appropriately concise, though it could have included a small amount of contextual guidance without becoming verbose.

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

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

An output schema is present, so return-value details are already covered. Required parameters are implied and the schema documents optional parameters and defaults. The main gap is the lack of side-effect context, but the annotations and schema compensate sufficiently for a compile operation.

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

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

Schema description coverage is 86%, with clear descriptions for sketchPath, fqbn, clean, buildPath, exportBinaries, and autoInstallCore. The description adds no parameter semantics beyond naming FQBN, which the schema already documents, so the baseline score of 3 applies.

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

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

The description states a precise action ('Compile'), a clear resource ('Arduino sketch'), and the key constraint ('specific board FQBN'). It clearly distinguishes this tool from sibling tools like upload_sketch and list_supported_boards.

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 no guidance on when to use this tool instead of alternatives such as upload_sketch, ensure_core_installed, or list_supported_boards. There is no mention of prerequisites, exclusions, or decision context, so the agent must infer usage from the tool name and sibling list.

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

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

Annotations provide readOnlyHint=true and openWorldHint=false, which cover the safety profile. The description adds that it generates rather than executes compile/upload commands and that it infers FQBN candidates, but it doesn't detail output shape or heuristics. No contradiction with annotations.

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

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

A single front-loaded sentence with no filler. Every phrase adds information: the action, the target hardware, the inference outcome, and the generated next commands.

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

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

No required parameters, an output schema, and read-only annotations reduce the burden. However, with many sibling tools covering detection and board listing, the description lacks workflow placement and does not hint at when this richer detection is needed.

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

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

Schema description coverage is 100%, so the schema already documents port and includeBoardDetails. The description adds no extra parameter-level context, so the baseline of 3 is appropriate.

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

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

The description names a concrete action ('Detect connected Arduino-compatible hardware'), the resource, and what it produces ('infer board/FQBN candidates, and generate next compile/upload commands'). It is specific enough to distinguish from simpler listing siblings, though it doesn't explicitly name an alternative.

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

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

No guidance on when to call this tool versus list_connected_boards, list_serial_ports, or get_board_details, nor any conditions or exclusions. An agent must infer that it is a pre-compile/upload detection step.

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

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

Annotations already provide idempotent and destructive hints. The description adds useful behavioral context by saying it can auto-install via `arduino-cli core install`, making the mutation mechanism explicit. No contradiction with annotations.

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

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

Two short sentences convey the action and the installation mechanism without redundancy. The key purpose is front-loaded, and every word adds 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?

Given the output schema and annotations, the description sufficiently covers the main behavior. It could mention behavior when `autoInstall` is false or failure modes, but these are not critical for a simple 3-parameter 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 input schema already documents all three parameters with 100% coverage, including examples. The description does not add parameter-specific detail, but the schema carries the burden adequately.

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

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

The description clearly states the tool's purpose: ensuring the Arduino core for a board FQBN is installed. The mention of `arduino-cli core install` differentiates it from sibling `install_arduino_cli`, which installs the CLI itself.

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

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

Usage is implied: run this when a board FQBN might need its core installed before compiling or uploading. However, it does not explicitly say when to prefer this over alternatives or when `autoInstall` should be disabled.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, covering the safety profile. The description adds the arduino-cli dependency and the 'detailed metadata' scope, but does not disclose further behavioral traits such as whether results are cached, require a network call, or depend on installed cores.

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

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

A single sentence that front-loads the action ('Get'), the object ('detailed board metadata'), and the scope ('specific FQBN'). There is no filler, jargon, or repetitive restatement of the tool title.

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, single-parameter, read-only tool with an output schema, the description provides enough context to invoke it correctly: what it returns, for which board, and through which CLI. It could optionally mention prerequisites like having arduino-cli installed, but that gap is minor.

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 fully documents the only parameter, fqbn, including a concrete example. The description's mention of FQBN adds no new semantic detail beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Get') and a clear resource ('detailed board metadata') scoped to a particular FQBN and source (arduino-cli). This immediately differentiates it from sibling tools that list boards or search references rather than fetch details for one board.

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 'for a specific FQBN' gives a clear usage condition: call this when the agent already has or can derive the exact board identifier. It does not explicitly state when not to use it or name alternative tools, but the context is unambiguous 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?

Annotations already declare destructive, open-world, and idempotent behavior; the description adds useful specifics: installation is attempted (may fail), package managers are involved, and a CLI path is configured after install. It does not detail every system-level side effect, but the annotation baseline lowers the burden.

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

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

One compact sentence with the main action front-loaded and the post-steps appended. Every phrase earns its place; no filler or schema 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?

For a tool with only two optional, fully described parameters, an output schema, and annotations covering safety profile, this is largely complete. The remaining gap is implicit guidance about when installation is needed and what conditions (e.g., available package manager) must hold, but the method enum and 'attempt' wording mitigate that.

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

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

Schema coverage is 100% and both parameters have descriptive definitions, so the baseline is 3. The description does not need to add parameter meaning; any additional detail would be redundant.

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 ('install arduino-cli'), scopes it to the current OS, and adds follow-up actions (verify and configure CLI path). This clearly separates it from sibling tools like ensure_core_installed, which handles cores rather than the CLI itself.

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 use case: when arduino-cli needs to be installed on the current OS via package managers. However, it does not explicitly state when not to use it, mention prerequisites such as admin rights, or contrast it with alternative install-related siblings.

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

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

Annotations already establish readOnlyHint=true, so no contradiction exists. The description adds useful context about 'local' scope and 'pin/spec metadata', but it does not disclose whether results are paginated, sorted, or limited in any way. This is acceptable for a simple read-only list tool, but the description adds only modest behavioral detail beyond annotations.

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

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

The description is a single sentence with no wasted words. It front-loads the action and resource, then adds the key metadata qualifier. Every word earns its place.

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

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

For a zero-parameter read-only list tool with an output schema, this description is complete. It identifies the resource, the scope ('local'), and the included metadata ('pin/spec') without needing to restate schema information or return formats.

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 is fully covered. There is no parameter meaning for the description to add, so the baseline of 4 applies. The description's mention of 'pin/spec metadata' hints at what the returned entries contain, but no parameter documentation is needed.

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

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

The description uses a specific verb ('List') with a clear resource ('local board reference entries') and states what metadata is included ('pin/spec'). The word 'local' differentiates it from the sibling search_board_reference, which an agent can infer is for searching broader or non-local references.

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 this tool is for enumerating local board reference entries, but it does not explicitly state when to choose it over search_board_reference or get_board_details. The 'local' qualifier gives some context, but there is no direct guidance on alternatives or exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint is absent, so the safety profile is covered. The description adds the context that results are detected by arduino-cli, implying current hardware state, but it does not disclose any additional behavioral details such as caching, ordering, or refresh behavior.

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

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

The description is a single concise sentence that directly states the action and scope. Every word is useful, with no fluff or repetition beyond the title.

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

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

For a zero-parameter, read-only list operation with an output schema present, the description is sufficiently complete. It names what is listed, the source of detection, and adds enough context for an agent to invoke it correctly.

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

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

The tool has zero parameters and the input schema is empty, so there is no need for detailed parameter descriptions. The baseline of 4 applies because nothing needs to be explained beyond what the schema already conveys.

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 connected boards and serial ports detected by arduino-cli.' It clearly names what is returned and scopes it to arduino-cli. However, it does not explicitly distinguish this from siblings like list_serial_ports or list_supported_boards, so an agent could still confuse it with those tools.

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

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

There is no guidance on when to use this tool versus alternatives such as list_serial_ports, list_supported_boards, or detect_hardware. The description only explains what it does, not when to prefer it or when to avoid 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?

Annotations already communicate that this is read-only, and the description adds relevant context about the arduino-cli dependency and platform support. It also sets expectations that board metadata is only included when detected, but does not describe failure modes or environment requirements beyond the OS list.

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 short sentences deliver the core purpose, implementation dependency, and platform scope with no filler. The resource is front-loaded and every clause adds 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 zero-parameter, read-only tool with an output schema, the description is mostly complete: it names the resource, the implementation, and supported platforms. It would be stronger with an explicit note on when to prefer it over list_connected_boards.

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?

There are zero parameters and schema coverage is 100%, so there is no parameter documentation burden on the description. The description correctly says nothing about parameters.

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

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

The description states a clear verb ('List') and resource ('serial ports') and adds 'detected board metadata' to define scope. It is distinguishable from close siblings like list_connected_boards because the resource is explicitly serial ports.

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

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

No guidance is given on when to choose this tool over related tools such as list_connected_boards, detect_hardware, or read_serial_snapshot. The platform note ('Works on Windows/macOS/Linux') is useful but does not explain when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description need not restate safety. It adds that the data comes from the local arduino-cli index, but does not disclose any further behavior such as cache freshness or index update requirements.

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 short sentence with no filler or repetition; it front-loads the action and resource.

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

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

For a simple read-only tool with one optional parameter and an output schema, the description is largely sufficient. It could more fully clarify the distinction between supported/installable boards and connected boards, but no critical calling information 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 single optional 'search' parameter is already fully described in the schema ('Optional case-insensitive filter for name/FQBN.'). With 100% schema coverage, the description has no obligation to add more.

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 ('List') and a clear resource ('supported/installable boards from the local arduino-cli index'). It is clear enough to distinguish from connected-board listing, though it does not explicitly name sibling tools.

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

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

The phrase 'from the local index' gives some context, and one can infer this is for enumerating installable boards, but there is no explicit when-to-use guidance, exclusion, or comparison to alternatives such as list_connected_boards or search_board_reference.

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 readOnlyHint annotation already covers the safety profile, and the description adds the time-bounded capture behavior. However, it does not disclose whether the tool opens/closes the port itself or requires an existing session, which would be useful beyond the annotations.

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

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

A single, focused sentence that front-loads the action and scope. Every word contributes to the core meaning, with no repetition or 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 read-only tool with an output schema and well-covered parameters, the description is almost adequate. The main gap is the missing relationship to sibling serial tools, especially whether an open session is required or whether this tool manages the port lifecycle itself.

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

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

Schema description coverage is 100%, so the schema fully documents port, baudRate, and durationMs. The description adds no extra meaning beyond aligning 'bounded duration' with durationMs and 'given port' with port, which is sufficient at the baseline.

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 ('Capture'), resource ('serial output'), and scope ('from a given port' with a 'bounded duration'). It implies a snapshot behavior that differs from a continuous serial read, though it does not explicitly contrast with sibling tools like serial_read.

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

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

No guidance is given about when to use this tool versus serial_read, serial_expect, or serial_open_session. The phrase 'bounded duration' hints at one use case, but there are no explicit conditions, exclusions, or alternative recommendations.

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 readOnlyHint annotation already establishes that this is a safe, non-mutating operation, and the description's 'checks' wording is consistent with that. The description adds useful context about what is checked (voltage, current, pin risks) but does not disclose what happens on failure or what the output represents.

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 with the action, target, and timing all front-loaded. There is no filler or redundant restatement of the tool name or title.

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 readOnlyHint and an output schema present, the description does not need to detail return values. However, for a tool accepting a nested power/wiring schema with no required fields, the description gives no guidance on how to use the input fields or whether board inference is expected, so it is only moderately complete.

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

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

The description does not explain any of the five parameters, including how to supply board/FQBN/port or the nested power/wiring objects. 'Voltage/current/pin risks' loosely maps to power/wiring, but with only 60% schema description coverage, the description leaves too much parameter meaning to inference.

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

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

The description names a specific action (run preflight checks) and a clear resource domain (electrical voltage/current/pin risks). It also positions the tool relative to upload and serial write operations, distinguishing it from the many sibling upload/serial tools.

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

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

The description explicitly states when to use this tool: before upload or serial write operations. It does not name alternatives or exclusions, but the timing and triggering operation are 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?

The readOnlyHint annotation already discloses that this is a safe read operation, so the description does not need to restate that. It adds the qualifier 'local', which provides context about the data source, but does not disclose whether the search is case-sensitive, returns partial matches, or handles multiple matches. Given the annotation coverage, this is acceptable but not exceptional.

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, compact sentence that front-loads the verb and resource, then immediately lists the search criteria. There is no redundant information or filler; every word contributes to the tool's purpose.

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

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

Given the tool's simplicity (one parameter) and the presence of an output schema (which presumably defines the return format), the description is adequately complete. It covers what the tool does and what the input means, without needing to describe return values. It might benefit from a note about when to choose this over list_board_reference, but that is a secondary concern.

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 description coverage (the 'query' property has no description), so the description must compensate. It does so by explicitly enumerating what the query parameter can be: board name, alias, id, or FQBN. This gives the agent clear guidance on what values are valid, though it does not specify matching behavior (e.g., exact vs. partial).

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

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

The description states a specific verb ('search') and resource ('local board reference'), and names four distinct search criteria (board name, alias, id, FQBN). This makes it clearly distinguishable from siblings like list_board_reference, which would list all boards, and get_board_details, which would retrieve details for a specific board.

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 for finding a board reference by a search term, but it does not explicitly state when to use it versus list_board_reference or other siblings. No alternatives or exclusions are mentioned, so an agent must infer the appropriate use case from the description's wording.

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

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

Annotations already mark the tool as destructive and idempotent. The description adds useful side-effect information by noting that the port lock is released, which goes beyond the schema. It does not describe failure behavior, but the annotations and simple scope make this acceptable.

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 compact sentence with no filler, front-loading the action and object. Every word contributes to meaning.

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

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

For a one-parameter, straightforward closure tool, the essential purpose and side effect are covered. It could explicitly state that a session must be open first or point to how to find sessionId, but the sibling tools and idempotentHint provide enough lifecycle 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?

Schema description coverage is 0%, so the description must compensate by explaining the sessionId parameter. It only reuses the word 'session' without clarifying where the ID comes from, its format, or how it relates to sibling session tools. The parameter name is somewhat self-explanatory, but the description adds minimal value.

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 ('Close') and a specific resource ('a serial session'), with an immediate consequence ('release its port lock'). It clearly distinguishes the tool from siblings like serial_open_session and serial_read.

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

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

The description implies usage at the end of a serial session, but it does not explicitly say when to use it versus alternatives or mention that the session must already be open. The agent must infer the appropriate context from the sibling tool names.

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 readOnlyHint annotation already covers the safety profile, and the description adds a useful behavioral cue by saying the tool 'waits' and has a timeout. It does not disclose whether pattern matching is regex or literal, whether caseSensitive defaults to false, or whether the session cursor advances, but the annotation lowers the burden for basic side-effect transparency.

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

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

The description is a single, front-loaded sentence with no filler or redundancy. It efficiently captures the core behavior without wasting tokens, which is ideal for quick agent scanning.

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 five parameters, only 20% schema coverage, and important behavioral details like pattern matching semantics and case-sensitivity defaults unstated, the one-sentence description is not enough for fully confident invocation in non-trivial cases. The output schema and readOnlyHint help, but an agent would still need to guess at several edge behaviors.

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

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

Schema description coverage is only 20%, so the description needed to compensate by explaining pattern semantics, timeout units/defaults, fromOffset behavior, and caseSensitive meaning. Instead, it mostly paraphrases 'string pattern' and 'timeout', adding little beyond the schema's existing parameter names and the one fromOffset description.

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

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

The description states a specific action ('wait for'), a concrete target resource ('string pattern in a serial session buffer'), and a limiting condition ('with timeout'). The verb 'wait for' clearly separates it from sibling tools like serial_read and read_serial_snapshot, so the tool's role is immediately identifiable.

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

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

The description implies when to use the tool: when you need to wait for a pattern rather than just read available data. However, it does not explicitly name alternatives, contrast behavior with serial_read/read_serial_snapshot, or state when not to use it, leaving the guidance to inference.

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

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

Annotations already declare readOnlyHint=true, which aligns with the description's 'List' wording. The description adds a small behavioral detail by mentioning 'port lock state' as part of the returned information. No contradictions exist, but the description does not go beyond what the read-only annotation and output schema would already suggest.

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 action and the object. Every word adds meaning, with no filler or redundant restatement of the tool name. It is efficient for an agent to parse.

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

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

For a parameterless, read-only listing tool with an output schema present, the description is sufficiently complete. It states exactly what the tool lists—active serial sessions and port lock state—and the readOnly annotation covers behavioral safety. No additional context is required 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 tool has zero parameters, so the empty schema is fully self-explanatory and carries 100% coverage. The description does not need to add parameter semantics because there are none to clarify. This meets the baseline of 4 for no-parameter tools.

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

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

The description uses a specific verb ('List') and clear resource ('active serial sessions'), and adds the unique detail of 'current port lock state.' This distinguishes it from sibling tools like serial_open_session, serial_read, and serial_close_session. An agent can understand exactly what this tool does without opening the schema.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as serial_read or read_serial_snapshot. The context is implied—checking active sessions—but the description does not state a preferred use case or exclude other tools. This leaves the agent to infer selection criteria.

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

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

The description adds meaningful behavioral context beyond the annotations by disclosing statefulness and port lock ownership. However, it does not explain what the destructiveHint=true actually entails, such as whether opening a new session invalidates an existing session or forcibly takes over the port, and it does not mention cleanup requirements.

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, compact sentence with no filler. It front-loads the primary action ('Open') and packs two important concepts, statefulness and lock ownership, into a concise and readable statement.

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 this is a stateful, destructive operation with session lifecycle implications, the description is somewhat thin. The output schema and annotations help, but the agent is left to infer session cleanup, lock contention behavior, and the relationship with serial_close_session, which are important for using this tool safely.

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

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

Schema description coverage is 100%, so all four parameters (port, ttlMs, baudRate, maxBufferBytes) are already documented in the schema. The description adds no parameter-level meaning beyond the structured definitions, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Open') with a clear resource ('stateful serial monitor session') and adds a distinguishing trait ('port lock ownership'). This clearly differentiates it from one-shot readers like serial_read or read_serial_snapshot and from session management tools like serial_list_sessions.

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 'stateful serial monitor session with port lock ownership' implies this tool is for long-lived, exclusive serial access, but it never states when to use it versus serial_read, read_serial_snapshot, or serial_expect. There is no explicit when-not-to-use guidance or reference to serial_close_session.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation, lowering the burden on the description. The description adds useful context about buffered data and the open-session precondition, but it does not disclose whether bytes are consumed, whether the call blocks waiting for data, or what happens when the buffer is empty.

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

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

The description is a single front-loaded sentence that states the operation and required context without filler. Every word earns its place for a read operation of this simplicity.

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 tool with four parameters and an output schema, the description is close to sufficient, but it leaves key behavioral expectations ambiguous for an agent: whether the read consumes the buffered data, whether it waits, and how it differs from read_serial_snapshot. Those gaps make it minimally viable rather than complete.

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

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

The schema already documents encoding, maxBytes, and fromOffset with types, defaults, and ranges; only sessionId lacks a description. The description adds no further parameter details, and at 75% schema coverage it neither substantially exceeds nor badly misses the baseline.

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: reading buffered bytes from an open serial session. It clearly identifies the operation and required state, but it does not explicitly distinguish this from the sibling read_serial_snapshot, so it falls short of full differentiation.

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 'from an open serial session' implicitly tells the agent that serial_open_session must be called first and that this is a read operation rather than a write or expect operation. However, it gives no explicit when-to-use or when-not-to-use guidance, and the relationship to read_serial_snapshot is unexplained.

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

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

Annotations already mark this as destructive and non-idempotent. The description adds useful behavioral context beyond those hints: safety preflight is enforced unless explicitly skipped. This helps an agent understand the default safety behavior and the existence of an escape hatch.

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

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

Two sentences with no wasted words. The core action is front-loaded, and the important safety qualifier is stated immediately after.

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 output schema and annotations, the description supplies the essential prerequisite (open serial session) and the safety behavior. It could go deeper on preflight details or post-write response handling, but those are partially covered by schema and sibling 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 describes 4 of 6 parameters, so baseline credit applies. The description does not add meaning for sessionId or the nested safetyContext object, and it does not explain data encoding or line endings beyond the schema. It is adequate but does not compensate for the remaining gaps.

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: 'Write bytes to an open serial session.' This clearly distinguishes serial_write from sibling tools like serial_open_session, serial_read, and serial_close_session.

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 key usage context: a serial session must already be open. It also indicates that safety preflight is enforced by default unless explicitly skipped. It does not explicitly name alternative tools, but the intended use case is 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?

Annotations already mark this as destructive, and the description adds meaningful behavioral context by calling out post-upload reset/re-enumeration windows. It stops short of describing how those windows are handled or what side effects the readiness wait has, but it does explain the main non-obvious 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?

A single tightly worded sentence with no filler; the core action and the distinguishing timing behavior are front-loaded. Every phrase adds information.

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

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

For a complex 11-parameter tool with an output schema and rich parameter descriptions, the description orients the agent to the compound workflow and its most important hidden pitfall (reset/re-enumeration). It does not explicitly mention safety preflight or core auto-install, but those are covered by parameter semantics and 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?

Schema description coverage is 91%, so the schema already documents nearly every parameter. The tool description adds no parameter-level detail, which is acceptable under the high-coverage baseline of 3.

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

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

The description states a specific verb ('Upload'), a concrete resource ('a sketch'), and a distinguishing outcome ('wait for a serial readiness pattern'). It also names the unique reset/re-enumeration handling, which separates it from siblings like upload_sketch and serial_expect.

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 composite behavior — upload plus wait for readiness — clearly implies when to use it, and the sibling list reinforces the distinction from plain upload_sketch or serial_expect. However, the description never explicitly says 'use this instead of X when Y', so an agent must infer the selection rule.

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

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

The annotations already mark this as destructive and idempotent, but the description adds no behavioral context beyond that: it does not say that uploading overwrites the board's firmware, can interrupt a running board, or may invoke preflight checks. There is no contradiction with the annotations, but also no added disclosure.

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

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

The description is a single, front-loaded sentence with no filler. Every word contributes to the core action and target.

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 rich schema, output schema, and annotations, the one-liner plus schema may be enough for straightforward use. Still, the description omits how this relates to upload_and_wait_ready and does not orient the agent around the safety-preflight and auto-install behavior exposed by the parameters.

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

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

Schema description coverage is 100%, so the schema documents all seven parameters, including nested safetyContext fields. The description itself adds no parameter-level meaning, which matches the baseline of 3 for high-coverage schemas.

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

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

The description states a clear action ('Upload') and resource ('a compiled sketch to a connected board/port'), which distinguishes it from compile_sketch and read/list tools. It does not explicitly differentiate it from the sibling upload_and_wait_ready, so it falls short of a 5.

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

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

No guidance is given about when to prefer this tool over upload_and_wait_ready, compile_sketch, or safety_preflight. The phrase 'compiled sketch' and 'connected board/port' imply prerequisites but do not provide explicit usage context, exclusions, or alternatives.

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