embedded-mcp-toolkit

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 the output (device statuses) but does not disclose potential behaviors such as requiring the ADB server to be started, side effects, or error handling. This is adequate for a simple read-only listing tool but lacks depth.

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 that is direct and front-loaded with the verb and resource. It contains no unnecessary words and fully serves its 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 (no parameters, no output schema), the description provides sufficient completeness. It specifies what the tool lists and which statuses are included, covering the essential return information for a device list tool.

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

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

The tool has zero parameters, so the baseline is 4 per the rules. The description correctly focuses on behavior rather than parameters, and there is no need for additional parameter explanation.

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 specifies the resource 'connected ADB devices' with status values (device, offline, unauthorized). This clearly distinguishes it from sibling tools like adb_exec (which executes commands) and adb_shell_* (shell operations).

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 (when you need to check connected ADB devices) but does not explicitly state when to use it versus alternatives, nor does it mention exclusions or prerequisites. It provides clear context for the tool's purpose but lacks explicit guidance on appropriate use cases.

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

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

With no annotations provided, the description carries the transparency burden. It adds behavioral context like 'one-shot' and auto-discovery error behavior (errors out if 0 or >1 devices) from the schema, but it does not disclose whether the command is read-only or mutating (install and push imply mutation), any permission requirements, or output format. The mention of short shell commands hints at execution limits but not explicitly.

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

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

The description is one concise sentence that front-loads the core behavior ('Execute a one-shot ADB command') and then follows with supporting use cases. Every word earns its place; no redundancy or irrelevant detail.

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

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

Given the tool's moderate complexity (2 params, no output schema, no annotations), the description plus detailed parameter guidance covers the main usage scenarios and device-selection behavior. It does not explain return values or error handling for command failures, but for an execution wrapper over adb this is a minor gap.

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

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

Schema description coverage is 100%, so the schema itself thoroughly documents both parameters. The tool description adds no new parameter semantics beyond the schema; it only recites example commands. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description clearly states a specific verb and resource: 'Execute a one-shot ADB command without a persistent session.' It also enumerates example use cases (adb devices, install, push, short shell commands), which sharpens the purpose. This differentiates it from persistent-session siblings like adb_shell_open and from adb_device_list.

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

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

The description gives explicit context on when to use: for one-shot commands and short shell commands, and the device parameter guidance further states there is no need to call adb_device_list first and when to omit the device parameter. It does not explicitly name alternative sibling tools when persistent sessions are needed, but the phrase 'without a persistent session' implies the boundary.

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

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

With no annotations, the description carries the full burden. It discloses the primary action and mentions terminating the adb process, but it does not describe error behavior, idempotency, or what happens with an invalid session ID. The ambiguous 'adb process' term adds some context but also confusion.

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, front-loaded with the core action, and contains no filler. It is appropriately sized for the tool's simplicity, earning 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?

Given the tool's simplicity (one parameter, no output schema), the description is mostly adequate, but it does not cover potential side effects or failure modes. The ambiguous 'terminate the adb process' wording leaves room for misinterpretation about the tool's full impact.

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 provides a clear description for session_id ('The session ID returned by adb_shell_open'), and the tool description adds no further parameter semantics. With 100% schema coverage, 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 clearly states 'Close an ADB shell session' with a specific verb and resource, distinguishing it from sibling tools like adb_shell_open and adb_shell_write. However, the phrase 'terminate the adb process' introduces ambiguity about the scope (shell process vs. entire adb server), slightly reducing clarity.

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 (call this when done with an ADB shell session) but provides no explicit guidance on when to use it versus alternatives, nor does it mention prerequisites like having an open session. It lacks the exclusions or alternative references seen in stronger examples.

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

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

With no annotations, the description carries full transparency responsibility. It discloses the single-channel concurrency risk, the combined write+delay+read behavior, and detailed timeout semantics including Ctrl+C handling for resident commands. This goes beyond mere functionality and addresses practical safety concerns.

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 thorough but not bloated. The core purpose is stated first, followed by a crucial warning, then an alternative, and finally detailed timeout guidance. Each section earns its place, though the maxDuration explanation could arguably be trimmed without losing essential 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?

Given no output schema and no annotations, the description is remarkably complete. It explains the operation, concurrency constraints, timeout behavior, and parameter nuances, ensuring an agent can use the tool safely and effectively without needing external context. No critical gaps are apparent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds critical semantics for maxDuration (always pass a timeout, suggested ranges, fallback behavior), which is not present in the schema. Other parameters are already well described, but the extra guidance for maxDuration elevates the score.

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 sends a command to an ADB shell session and waits for output, combining write/delay/read. It distinguishes from siblings like adb_shell_write and adb_shell_read by explaining the combined behavior, and mentions alternatives like adb_shell_open for parallel 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 description explicitly warns against concurrency on the same session and instructs to wait for previous commands, with a clear alternative (open multiple sessions). It also provides guidance on timeout estimation via maxDuration, making usage expectations concrete.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It mentions returning the initial banner output and describes auto-discovery behavior (errors if 0 or >1 devices) and connection details (no probing, log directory follows alias). Still, it does not disclose session lifecycle (e.g., session remains open until adb_shell_close) or prerequisites like ADB connectivity.

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

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

The main description is two succinct sentences that front-load the core purpose. The parameter details are structured within the schema and are relevant and well-organized. No filler or redundant text.

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 and no output schema, the description adequately covers the main functionality and return value (banner output). It could be more complete by referencing the companion close tool or session lifecycle, but the sibling list and 'interactive session' terminology provide enough context for an experienced agent.

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

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

The parameter description far exceeds the schema, explaining when to pass an alias vs serial, how serials are resolved back to aliases, the exact behavior when omitted (auto-discovery with error conditions), and a note about log directories. This adds substantial semantic value beyond the schema's simple 'Target device alias'.

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

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

The description clearly states the action ('Open an interactive ADB shell session') and the resource ('Android device'). It distinguishes itself from siblings like adb_shell_exec (which executes one-off commands) and other shell open tools by specifying 'ADB shell' and 'interactive 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 parameter description gives practical guidance on device selection (prefer alias, omit only for single device) and explicitly notes there is no need to call adb_device_list. However, it does not provide explicit when-to-use vs alternatives, such as contrasting with adb_shell_exec for single commands or explaining when to use adb_shell_open instead of other session types.

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

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

With no annotations provided, the description takes on the burden of behavioral disclosure. It reveals a critical behavioral trait: concurrent access corrupts the output buffer. This is valuable beyond the schema. It does not fully describe all behavior (e.g., blocking, empty buffer), but it covers the key risk.

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

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

The description is two sentences, front-loaded with the purpose and followed by a crucial usage warning. Every word earns its place; there is no fluff or redundancy.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description is sufficiently complete. It covers purpose and a critical concurrency constraint. The schema handles parameter details, so the description doesn't need to repeat them. It is complete enough for an agent to use correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add any additional parameter semantics beyond what the schema already provides for session_id and clear. The clear parameter's meaning is fully documented in the schema, not the 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 clearly states the tool's purpose with a specific verb+resource: 'Read output from an ADB shell session.' It distinguishes itself from sibling tools like adb_shell_write and adb_shell_exec through the concurrency warning and the focus on reading.

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 provides an explicit when-not-to-use guideline: 'Do NOT call this concurrently with adb_shell_exec/adb_shell_write on the same session_id.' It does not name alternative tools for the same session, but the context of reading vs. writing/executing 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?

No annotations are provided, so the description carries the burden. It discloses a key behavioral trait: 'without appending a newline'. This adds value beyond the schema. It doesn't elaborate on error cases or prerequisites, but for a simple signal-sender, this is sufficient.

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

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

The description is a single, front-loaded sentence that concisely states the action and a critical nuance. There is no wasted verbiage.

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 two fully documented parameters and no output schema, the description covers the essential purpose, action, and distinguishing behavior. The sibling context (adb_shell_*) reinforces the domain. No additional detail is necessary.

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%: both session_id and key are fully described in the schema, including the enum values for key. The description adds no additional parameter semantics beyond the schema, 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.

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

The description clearly states the tool sends a control character (Ctrl+C/U/D/Z) to an ADB shell session, with the specific behavior of not appending a newline. This distinguishes it from sibling tools like adb_shell_write (for text input) and adb_shell_exec (for commands).

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 context is clear: use this tool to send a control character to an active ADB shell session. It doesn't explicitly mention alternatives or when not to use it, but the specificity of the action and the session_id parameter imply proper usage. No exclusions are stated.

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

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

There are no annotations, so the description carries the behavioral burden. It discloses the important concurrency hazard (output buffer corruption), but does not mention side effects of executing commands, prerequisites like an open session, or how output is retrieved.

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: the first states the core purpose, and the second provides a critical behavioral warning. No redundant wording, and the most important caveat is highlighted.

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

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

The description is minimally viable for a simple command-sending tool, but with no output schema and no annotations it could be stronger. It omits how to read output (though adb_shell_read is hinted at), whether a session must already be open, and what happens on success or failure.

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

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

Schema description coverage is 100%, and each parameter has a clear description in the schema. The tool description adds no parameter-specific meaning beyond the schema, 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 clearly states the action ('Send a command to an ADB shell session') with a specific resource. It does not explicitly differentiate from adb_shell_exec, which could overlap in behavior, so it stops short of full sibling 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 description provides an explicit when-not usage rule: do not call concurrently with adb_shell_exec/adb_shell_read on the same session_id. It does not describe positive use cases or alternative tool selection, but the concurrency warning gives actionable context.

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

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

Despite no annotations, the description discloses key behaviors: using default device when no name is given and returning all devices for 'all'. This provides good transparency for a read-only configuration tool.

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

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

Two efficient sentences: first states purpose, second adds parameter usage details. No wasted words.

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 one optional parameter, the description covers the key behaviors and edge cases (default and 'all'). It lacks output format details, but that's acceptable given no output schema.

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

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

With 100% schema description coverage, the description adds meaning beyond the schema by explaining the semantics of omitting the parameter (default device) and using 'all'.

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 verb 'Get' and the resource 'device configuration', and the behavior differentiates from siblings like adb_device_list by explaining the handling of 'all' and default device.

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

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

The description explains when to omit or use 'all' for the parameter, but lacks explicit guidance on when to use this tool versus sibling tools (e.g., adb_device_list, adb_exec).

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It only states 'Greet someone by name' but does not mention side effects, return value, safety, or any potential side effects. The agent cannot infer if this is a pure function, what it returns, or if it has any external effects.

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, short, front-loaded sentence with zero wasted words. It conveys the essential action efficiently, earning a perfect score.

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

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

For a tool with one required parameter and no output schema, the description is minimally adequate for invocation but lacks essential behavioral context. It does not describe the return value or any side effects, which an agent would need for full understanding. However, given the trivial nature of greeting, a score of 3 reflects the adequacy with clear gaps.

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 0% parameter description coverage, and the tool description only says 'by name', which barely clarifies the 'name' parameter. It adds no detail about format, constraints, or meaning beyond the parameter name itself, failing to compensate for the lack of schema documentation.

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

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

The description 'Greet someone by name' uses a specific verb ('greet') and a clear object ('someone by name'), making it distinct from sibling tools which are all SSH/serial/network operations. Although it doesn't specify the output, 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.

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

No guidance is provided on when to use this tool versus alternatives. There are no prerequisites, exclusions, or context clues about typical usage scenarios beyond the obvious greeting purpose.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior. It does so by stating the read-only query nature, the endpoint format (username@ip), the log directory output, and the local-launch special case. This exceeds minimal disclosure and helps the agent anticipate results without calling the tool.

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

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

The description packs multiple useful facts into a compact form: purpose, use case, output details, and a conditional edge case. Each sentence earns its place, though it could be tightened slightly by separating the log-directory detail from the endpoint query topic.

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 tool with no output schema, the description is remarkably complete. It explains what is returned, under what conditions, for what purpose, and how to interpret the special local-launch result. No critical information is missing for an agent to call and understand this tool.

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

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

The tool has zero parameters, so the schema already fully covers parameter semantics. The description appropriately does not invent parameter details and instead focuses on output behavior. Baseline 4 is appropriate for a no-parameter tool.

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

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

The description states a specific verb (query) and resource (MCP host endpoint, log save directories) and explains the concrete use case (cross-machine scp transfers). It clearly identifies what the tool returns and distinguishes its purpose from the broader sibling set of shell/serial/network 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?

It provides clear context for when the tool is needed (MCP on Windows, AI client on Linux) and when it behaves differently (local launches return 'local started' with no endpoint). It does not explicitly name alternative tools, but the scp-transfer context is specific enough to guide selection without confusion.

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

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

No annotations are provided, so the description carries the full burden. 'Scan' implies a non-destructive read operation, and the listed fields give some detail. However, it does not disclose permissions, scope (local vs remote), or any side effects, which is a moderate gap for a tool that could potentially access network configurations.

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 concise sentence, no redundant information. It front-loads the action and resource, making it easily scannable for an AI agent.

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

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

The description covers the basic purpose and the type of data returned (IP, MAC, status, speed), but it lacks details about output format, local vs remote scope, and any prerequisites. Given no output schema exists, the description should provide more context on what the agent can expect after 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?

This tool has zero parameters, so the schema is trivially covered (100%). The description does not need to explain parameters, and the baseline for 0-param tools is 4.

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 verb 'Scan' and the resource 'Windows network adapters', and further specifies the configuration details (IP, MAC, status, speed). This clearly distinguishes it from sibling tools like port_scan_tool and subnet_check_tool, which focus on other network aspects.

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 when network adapter information is needed on Windows, but it does not explicitly state when to prefer this over alternatives or mention any exclusions. There is no comparison with sibling tools, so the agent must infer usage from the tool name and description alone.

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

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

No annotations are provided, so the description carries the full burden. It describes the action (scanning Device Manager) but does not disclose behavioral details such as whether it is read-only, potential permissions required, or what the output format looks like. The description is not misleading, but it lacks depth.

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 with no unnecessary words or repetition. It is front-loaded and immediately clear.

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

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

The tool is simple with no output schema or annotations. The description explains the purpose but does not specify the return value structure (e.g., list of port names, maybe with details). This is a notable gap given that the output schema is absent.

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

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

There are zero parameters, and the schema has 100% coverage (empty schema). Per the baseline rule for 0-param tools, a score of 4 is appropriate; no parameter explanation 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 clearly states the tool's function with a specific verb ('Scan') and resource ('Windows Device Manager') for COM and LPT ports. It is unambiguous and distinguishes itself from sibling tools that handle individual ports or shell operations.

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: it is the tool to call when you need to discover available serial/parallel ports. However, there is no explicit guidance on when to use this versus alternatives (e.g., serial_open to act on a specific port) or when not to use it.

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

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

No annotations are provided, so the description carries the burden. It does disclose the key behavior that the process is terminated, not just the session closed. However, it omits consequences like irreversibility, error handling for invalid sessions, or whether it is a graceful shutdown, leaving gaps in 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 that is concise and without waste. It directly states the action and target, making it easy 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 simple one-parameter close operation, the description is mostly complete. It states the action and the process termination, and the schema fills in the parameter. What is missing is mention of what happens on failure or whether the operation is safe to repeat, but these are minor for a straightforward close tool.

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

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

The schema covers 100% of the parameter, describing session_id as 'The session ID returned by power_shell_open'. The description adds no additional parameter semantics, 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 clearly states the tool's function: closing a PowerShell shell session and terminating the process. It is specific about the resource (PowerShell session) and the action (close/terminate), distinguishing it from sibling close tools for SSH, serial, or ADB.

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: when you have a PowerShell session to close. However, it does not explicitly mention alternatives (e.g., ssh_shell_close, adb_shell_close) or provide exclusions, so the guidance is implied and not fully developed.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It discloses the combined operation flow (write + delay + read), indicates the one-way session nature, and highlights the critical concurrency/interleaving hazard. It doesn't cover timeout, error, or return-value behavior, but the core behavioral traits are transparent.

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

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

The description is two sentences, front-loaded with the primary purpose, and includes a crucial operational warning. No filler or redundant repetition of schema 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?

The description covers the core behavior and concurrency rule, which is essential context. However, with no output schema and no annotations, it omits return-value details (e.g., stdout, stderr, exit code), failure behavior, and timeout semantics, leaving some uncertainty for an agent invoking this tool.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal parameter-level insight beyond the combined operation concept; it doesn't elaborate on `clear`, `delay`, or `command` semantics beyond the schema definitions.

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

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

The description clearly states the action: 'Send a command to a PowerShell shell session and wait for the output.' It further distinguishes itself by explaining that it combines write + delay + read in one call, setting it apart from sibling tools like power_shell_write and power_shell_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 provides explicit usage guidance by warning against concurrent commands and instructing the agent to wait for the previous command to finish. It implies this tool is the synchronous alternative to manually chaining write/read calls, though it doesn't explicitly enumerate 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?

No annotations are provided, so the description carries the full transparency burden. It discloses that the tool opens a persistent interactive session and returns the initial banner, but it omits lifecycle expectations (e.g., needing power_shell_close) and resource implications. Some behavioral insight is present, but key details are missing.

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

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

The description is two short, front-loaded sentences with no redundancy. It immediately states the action and resource, then describes the return value, achieving high conciseness and clear structure.

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

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

For a simple tool with one fully documented optional parameter, the description states the purpose and return value. However, without annotations or an output schema, it does not mention the session lifecycle or how this tool fits with power_shell_close/read/write, leaving the agent to infer important workflow 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 input schema covers 100% of the single parameter (workingDir) with a meaningful description, so the baseline of 3 applies. The tool description itself adds no parameter-specific information, providing no extra value beyond the schema.

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

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

The description uses a specific verb ('Open') and clearly identifies the resource as 'interactive PowerShell shell session on the local Windows machine', distinguishing it from SSH, ADB, and serial shell open tools. It also states the immediate return behavior ('initial banner output'), making the tool's core function unambiguous.

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

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

The description implies usage when an interactive local PowerShell session is needed, but it does not explicitly contrast with sibling tools like power_shell_exec for one-off commands or mention session termination via power_shell_close. It provides context (local, interactive) but lacks explicit when-to-use/alternative guidance.

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

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

No annotations are provided, so the description carries the full burden. It discloses the concurrency hazard that can corrupt the output buffer, which is important behavioral context. It doesn't mention return format or clearing behavior, but those are partially covered by the schema's 'clear' parameter.

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 concise sentences: the first states the purpose, the second delivers a crucial warning. Front-loaded and 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?

The tool is simple (read output) and has no output schema. The description explains the core function and the concurrency constraint, which is essential context. It doesn't describe the return structure, but that's typical for a read tool and not required given the simplicity.

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% — both parameters ('session_id' and 'clear') are documented in the schema. The description adds no additional parameter semantics beyond the schema, so baseline 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 states the tool's purpose clearly: 'Read output from a PowerShell shell session' — specific verb and resource. It differentiates from sibling tools like power_shell_exec and power_shell_write by focusing on reading output.

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?

Provides explicit concurrency guidance: 'Do NOT call this concurrently with power_shell_exec/power_shell_write on the same session_id — concurrent access to the same PowerShell process corrupts the output buffer.' This clearly instructs when not to use it and highlights a critical constraint.

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?

Given no annotations, the description carries the burden of behavioral disclosure. It reveals a critical behavioral trait: concurrent access corrupts the output buffer, which is a non-obvious constraint. However, it does not mention side effects of the command itself (e.g., whether it modifies the session state) or expected output behavior beyond buffer handling. The description adds the 'clear' flag context, which briefly explains the parameter but lacks detail on output format.

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

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

The description is two sentences, front-loaded with the primary action, and includes a critical caution efficiently. No wasted words.

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 write tool with good schema coverage and a clear description, the description covers the crucial concurrency warning, but it lacks information on output format or post-execution steps. The command syntax is simple, so a 3 reflects that it's a concise definition but not a complete one.

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% with descriptions for all three parameters. The description adds context on the 'clear' parameter (buffer clearing behavior) and relates session_id to power_shell_open, which clarifies usage. This additional context exceeds the schema baseline, so a 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 clearly states the verb 'Send' and resource 'command to a PowerShell shell session', which identifies the tool's purpose. It distinguishes it from siblings like power_shell_read and power_shell_exec by focusing on writing, though it doesn't explicitly contrast with them.

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

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

The description provides an explicit 'Do NOT call concurrently' warning with sibling tools, which is strong usage guidance. It doesn't specify when to use this tool over alternatives (e.g., vs exec), but the concurrency constraint is a clear usage 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?

No annotations are provided, so the description carries full burden of behavioral disclosure. While 'close and release' clearly indicates a destructive action (mutating state), it does not disclose any side effects such as what happens to buffered data, whether the port is immediately reusable, or any error conditions. This is minimal 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 concise sentence with no wasted words. It efficiently conveys the tool's purpose and is front-loaded.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is functionally complete but lacks context about prerequisites (e.g., session must be open), expected behavior on partial closures, or error handling. It does not fully compensate for the lack of annotations.

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

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

Schema coverage is 100% and describes session_id as 'The session ID returned by serial_open'. The description adds no additional meaning beyond what the schema already provides. Baseline 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 clearly states the tool's action ('close a serial port session') and its effect ('release the port'). It uses specific verb and resource, distinguishing it from siblings like serial_open, serial_read, and serial_write.

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 after an open session, but does not explicitly state when to use (e.g., after finishing communication) or when not to use (e.g., if session is already closed). No alternatives or exclusions are mentioned.

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

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

Thoroughly discloses internal behavior: triggers device-side sz itself, uses ZMODEM handshake, blocks until completion/failure/timeout, logs to stderr, handles partial file removal on error, resolves remote_path relative to cwd, and explains the two distinct timeouts. No annotations exist, so this description fully carries the transparency 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?

The description is well-structured with a clear main purpose, an IMPORTANT warning, and logically ordered details. Each sentence contributes essential information given the complexity of ZMODEM transfers, avoiding superfluous text.

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?

Covers prerequisites, usage, error handling, timeouts, and failure modes comprehensively. Even without an output schema, it explains what happens during and after the operation (e.g., removal of partial files, blocking behavior). Complete for a tool with this complexity.

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 provides detailed descriptions for all parameters (100% coverage), but the description adds holistic context about how parameters interact (e.g., send_cmd for directory changes, timeouts interplay). This adds value beyond the schema, though the schema alone is quite informative.

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

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

The description clearly states the action (download a binary file) and the specific method (over ZMODEM via an existing serial session), distinguishing it from sibling tools like serial_upload or ssh_sftp_download.

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?

Provides explicit usage constraints (e.g., do NOT manually run sz, use send_cmd for directory changes) and clarifies prerequisites (existing serial session, lrzsz installed). Does not explicitly compare with alternative download methods (e.g., ssh_sftp_download), but the context makes the intended use 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?

No annotations are present, so the description carries full responsibility. It discloses the reboot side effect, configurable detection rules, fallback to 'printenv', and failure modes (kernel boot or verify timeout). This is rich 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?

Three sentences, each adding value: purpose, strategy/config, and failure behavior. No redundancy.

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

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

Covers the tool's entire workflow: reboot, detection, fallback, and failure. No output schema exists, but the description does not need to explain return values as it's a side-effectful operation. Only minor omission is explicit prerequisite of an open serial session, but session_id implies it.

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

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

Schema coverage is 100% for both parameters. The description reinforces the timeout behavior by mentioning a 'short window' and 'fails fast,' adding strategic context beyond the schema's definition. session_id is left to the schema, which is sufficient.

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

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

The description opens with a specific action—'Enter U-Boot by rebooting the device and stopping autoboot'—and includes a mechanism (reboot + autoboot stop). This clearly distinguishes it from sibling serial tools like serial_exec or serial_shell_login.

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

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

It describes the tool's role in the boot process and explains the detection strategy, but it does not explicitly state when to prefer this over alternatives or when not to use it. The context is clear for bootloader access, but no exclusions are given.

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

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

No annotations are provided, so the description carries the full burden. It discloses concurrency hazards, buffer clearing via the 'clear' flag, timeout defaults, and that timeout type is annotated in output. However, it does not describe failure modes or output structure, which is a minor gap.

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

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

The description is front-loaded with the core purpose, then adds a critical warning and a suggested alternative. It is somewhat lengthy but every sentence provides necessary operational detail, so it 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?

Given the tool's complexity (5 parameters, concurrency concerns, timeout behavior) and the lack of an output schema, the description covers essential usage, warnings, and alternatives. It stops short of specifying return data structure, but overall it is sufficiently complete for an agent to use effectively.

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 covers 100% of parameters with detailed descriptions, including maxDuration defaults and guidance, clear flag semantics, and delay purpose. The description adds the 'combines write+delay+read' context but does not materially extend parameter understanding beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description clearly states it sends a command to a serial shell session and waits for output, combining write, delay, and read. It explicitly differentiates itself from sibling tools like serial_write, serial_read, and serial_send_ctrl by describing its composite nature.

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?

Provides explicit usage guidance: warns against concurrent calls on the same session, instructs to wait for previous commands, and recommends opening multiple sessions via serial_open for parallel execution. This gives clear when-to-use and when-not-to-use context.

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

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

With no annotations provided, the description is the sole source of behavioral info. It announces that a shell session is started and returns banner output, but does not disclose side effects like port locking, timeout behavior, or required setup. Minimal but functional.

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?

Single sentence that front-loads the action, with no unnecessary words. Each part serves a purpose: action, resource, outcome.

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 6 parameters, no output schema, and no annotations, the description is thin. It omits lifecycle context such as how to close the session (though sibling serial_close exists) or whether multiple opens are allowed. Adequate for simple use but not fully self-contained.

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% with clear descriptions for all 6 parameters. The tool description adds no extra semantics beyond the schema, so baseline 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 clearly states the action (open a serial port and start a shell) and the resource (serial port connection), and mentions the return value (initial banner). It distinguishes from sibling tools like serial_exec and serial_read, which serve different purposes.

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 use this tool versus alternatives such as serial_shell_login or adb_shell_open. The description does not provide context about prerequisites, lifecycle, 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?

With no annotations, the description carries the full burden for behavioral disclosure. It reveals a critical trait: concurrent access with serial_exec/serial_write corrupts the output buffer. However, it does not mention return format or whether it blocks, but the concurrency warning is a major safety 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 only two sentences: first gives the purpose, second is a critical warning. No fluff, perfectly front-loaded, and every sentence earns its place.

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

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

For a simple read tool with well-documented parameters and no output schema, the description covers the essential context. The concurrency warning addresses the main risk, and the purposes is clear. It could mention buffering behavior briefly, but the clear parameter in schema partially covers 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?

The input schema covers both parameters (session_id and clear) with 100% coverage, so the description adds no extra parameter meaning. Baseline of 3 is appropriate because the schema already does the heavy lifting.

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

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

The description clearly states 'Read output from a serial shell session' with a specific verb and resource. It distinguishes itself from siblings by explicitly warning about concurrency with serial_exec/serial_write, making its role clear.

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 an explicit when-not-to-use guideline: 'Do NOT call this concurrently with serial_exec/serial_write on the same session_id.' This is a strong usage exclusion that helps the agent avoid a critical error, and it implies the tool's primary purpose is to read serial output.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It only states that a control character is sent without a newline, but does not describe session effects, whether the command blocks, or any prerequisites. The schema's enum descriptions add some detail, but the tool description itself lacks behavioral depth.

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 includes the essential information—what the tool does and a key distinguishing detail—without any redundant or filler content.

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

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

The tool is simple (two parameters, no output schema), and the description, combined with the schema, sufficiently conveys the action and scope. Some context is missing (e.g., whether the session must already be open), but this is minor given the simplicity and the sibling tool ecosystem.

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%, with both parameters having clear descriptions. The key parameter's enum values are explicitly documented (e.g., c=Ctrl+C, u=Ctrl+U). The tool description adds little beyond the schema, so a baseline of 3 is appropriate; it does not compensate with additional parameter-level meaning.

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 'Send', identifies the resource 'serial shell session', and specifies the exact set of control characters (Ctrl+C/U/D/Z). It also distinguishes itself from serial_write by noting it does not append a newline, making its purpose clear and distinct.

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

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

The description implies usage for sending control characters to a serial session, but does not explicitly state when to prefer this over alternatives like serial_write or serial_exec. No exclusions or alternative tools are mentioned, so guidance is limited to what can be inferred from the tool name and description.

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

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

With no annotations, the description carries the full burden, and it does a good job: it discloses the sequence of operations (connect, detect, unlock, return). It does not hide that it mutates state (auto-unlock) or that it establishes a session. However, it could add more context about what 'ready session' means, whether it leaves a persistent open connection, or failure 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 extremely concise and front-loaded: the first sentence states the purpose and outcome, the second explains the composite nature. Every word earns its place; no fluff or 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 composite login tool with no output schema, the description provides enough context: it tells the user what happens (connect, detect, unlock) and what to expect (ready session). It could be more complete by noting that the resulting session can be used with other serial tools, but that is implicitly understood from sibling names. Overall, it is well-suited for the tool's complexity.

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 has 100% coverage with clear descriptions for key, device, and timeout. The description does not add any extra semantic meaning beyond the schema. The baseline of 3 applies because the schema does the heavy lifting and the description does not need to compensate.

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 what the tool does: connects to a device, detects PSH state, auto-unlocks if locked, and returns a ready session. It explicitly says it combines open + PSH detect + unlock, distinguishing it from sibling tools like serial_open or serial_exec. The verb+resource model is specific and informative.

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 conveys the clear context for use: when you want a one-click login that handles connection, PSH detection, and unlocking in a single call. It implies this is a convenience wrapper over separate steps but does not explicitly name alternative tools or state when NOT to use it. That would require explicit exclusions for a 5.

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

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

With no annotations provided, the description fully carries the behavioral burden. It discloses the zero-side-effect buffered tail inspection, the fallback bare Enter probe (including the potential to answer Y/N prompts), automatic syncing of conclusive results, and that 'status' performs no device I/O. This is exceptionally transparent for a tool with hidden side effects.

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 text is dense but every sentence serves a purpose: it introduces the resource, defines the mark's role, details each action, and includes a critical safety warning. The structure front-loads the purpose and uses clear action labels. No filler or redundant phrasing.

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

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

For a tool with no output schema, the description covers the tool's behavior, side effects, and action semantics thoroughly. The only gap is that it does not describe the exact return format for 'status' or 'detect' results, which an agent might need to process the output. Still, the description gives enough context for safe and effective use.

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

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

The schema already covers 100% of parameters, so baseline is 3. The description adds value beyond the schema by explaining the default action ('detect' default), the meaning of 'set'/'clear' in context, and the subtle consequence of 'detect' (auto-sync). This goes beyond the schema's terse enum descriptions, justifying a 4.

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

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

The description opens with a specific verb+resource: 'Query, detect, or force-set the U-Boot mark of a serial session.' It clearly defines the tool's scope and differentiates it from siblings by explaining its relationship to serial_exec's marker wrapping, making the purpose unmistakable.

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 provides explicit when-to-use guidance for each action ('detect' default, 'set'/'clear' for out-of-sync, 'status' for read-only) and includes an explicit warning against detecting while a command may be running or awaiting input. However, it does not name alternative sibling tools directly, so it stops short of a full 'how this compares to serial_enter_uboot' exclusion.

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

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

There are no annotations, so the description carries the full behavioral burden. It discloses that the tool triggers the device-side rz itself, blocks until completion/failure/timeout, logs progress to stderr, and explains the distinct semantics of idle_timeout versus timeout, including the suggested-value behavior on huge transfers.

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

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

The description is front-loaded with purpose, immediately follows with the critical handshake warning, and then covers usage and timeout behavior. Every sentence contributes important operational context with no redundant 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?

Given no annotations, no output schema, and six parameters, this is an unusually complete description. It covers prerequisites, failure modes, handshake risks, usage guidance, blocking behavior, stderr logging, and timeout semantics, leaving very little for the agent to infer or discover by mistake.

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 every parameter already has a rich description, so the baseline is satisfied. The main description reinforces recvcmd and the timeouts and adds the working-directory-change example, but it does not meaningfully extend understanding of local_path, remote_name, or session_id beyond what the schema already states.

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

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

The description opens with a specific action and resource: 'Upload a binary file to the device over ZMODEM via an existing serial session.' This makes the purpose unambiguous and distinguishes it from low-level sibling operations like serial_write or serial_exec.

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

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

It provides explicit preconditions (lrzsz must be installed), explicit exclusions (do NOT manually run rz beforehand), and clear usage examples for recv_cmd, including directory changes like 'cd /home && rz'. It also warns against using serial_exec/write to start rz, making the when-not guidance specific.

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

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

The description discloses the behavioral effect of concurrent access on the output buffer, which is a valuable warning. However, with no annotations provided, the description carries the full burden but does not cover other important behaviors like default buffer clearing (clear flag), error handling, or return 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 entire description is two sentences: the first states the purpose, the second a critical warning. It is front-loaded, concise, and 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 simple write operation, the description provides the essential purpose and a concurrency caveat. However, it does not mention what the function returns (or if it returns anything), nor does it explain relationships with sibling tools, leaving some gaps for a tool with no annotations and no output schema.

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

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

All three parameters are fully described in the input schema with 100% coverage, including the clear flag's purpose and default. The description does not add any additional meaning beyond what the schema already provides, so it meets the baseline for high schema coverage.

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

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

The description clearly states the verb 'Send' and the resource 'a command to a serial shell session', which distinguishes it from reading or executing on the serial console. It is specific and actionable, though it does not explicitly compare to sibling tools like serial_exec.

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 only usage guidance is a negative warning about concurrency with serial_exec/serial_read. It does not explain when to use serial_write versus alternatives such as serial_exec or serial_send_ctrl, nor does it provide context like prerequisites or typical use cases.

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

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

No annotations are provided, so the description carries the full burden. It discloses return fields and the key behavior that logs are recorded continuously, including boot logs. It does not explicitly state side effects or permissions, but as a metadata query it is implicitly safe and read-only. This is more transparent than many descriptions.

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

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

Two sentences, front-loaded with the core purpose, then parameter behavior, then return details. Every sentence earns its place, with no redundant or filler content.

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

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

Given the tool's simplicity (two optional params, no output schema), the description is complete. It covers all parameter combinations, lists all return fields, and includes important behavioral context about log recording. No significant gaps.

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% with descriptions for both parameters. The description adds value by explaining the 'neither' case and describing the return structure, which goes beyond the schema's brief parameter descriptions. It clarifies the filtering semantics effectively.

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: 'Query active session metadata.' It uses a specific verb (Query) and resource (active session metadata), and distinguishes itself from sibling tools which are all about shell/connection operations rather than metadata lookup.

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

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

The description explains the parameter combinations: 'Pass session_id for one session, device for all sessions of a device, or neither for all active sessions.' This gives clear context on how to use the tool, though it does not explicitly exclude alternatives or mention when not to use it. However, the distinction from the sibling action tools is implicit and clear enough.

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

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

No annotations provided, so the description carries full burden. It discloses key behaviors: execution, waiting, classification, and structured results. However, details on classification scope, timeout handling, and error responses are missing, preventing a perfect score.

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 plus an important note. Front-loaded with the core action. No redundant information. 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?

No output schema, so description should hint at return structure. It mentions 'structured build results for AI analysis' but lacks specifics on failure modes, timeouts (despite maxWait parameter), or classification details. Adequate but with gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the one-build-per-session constraint (reinforcing session_id semantics) and noting classification (relating to classify parameter), exceeding 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 it executes a build command on a remote server via SSH, waits for completion, classifies errors/warnings, and returns structured results. It distinguishes from siblings like ssh_shell_exec by specifying build-specific behavior and the one-session-one-build constraint.

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

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

Explicitly states that each session supports only one build at a time and advises opening multiple sessions via ssh_shell_open for concurrent builds, providing clear when-to-use and when-not-to-use guidance.

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

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

No annotations are provided, so the description carries full burden. It mentions the reuse of an existing session, which is key. However, it does not disclose behavior such as whether local files are overwritten, error handling, or permission requirements. This is adequate but could be more detailed.

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 that efficiently conveys the tool's purpose, prerequisite, and mechanism. No unnecessary words.

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 (download file with given paths and session), the description is largely complete. However, it does not mention return values or overwrite behavior. With no output schema, a brief note on success/error would improve completeness.

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%: all three parameters (local_path, session_id, remote_path) have descriptions in the input schema. The description adds no additional parameter information beyond the schema. Baseline is 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 clearly states 'Download a remote file from the board to local over SFTP, reusing an existing SSH session.' It specifies the action (download), source (remote), destination (local), protocol (SFTP), and prerequisite (existing session). It distinguishes from sibling tools like ssh_sftp_upload and ssh_shell_* commands.

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 context by stating 'reusing an existing SSH session,' which indicates an established session is required. However, it does not explicitly state when not to use this tool or reference alternative tools for similar tasks (e.g., uploading via ssh_sftp_upload or shell commands).

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

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

No annotations are provided, so the description carries the full burden. It only states the action and session reuse, but does not disclose whether the remote file is overwritten, what happens on error, or any side effects. This is a significant gap for a mutation tool without annotation support.

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

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

The description is a single, well-structured sentence that states the action, method, and prerequisite in a concise manner. Every word contributes meaning, and there is no wasted content.

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

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

With no output schema and no annotations, the description omits return value information and error behavior. However, the tool is simple and the prerequisite (existing SSH session) is mentioned. This is adequate but not complete for a tool that could fail on invalid session or overwrite conflicts.

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 descriptions cover all three parameters (local_path, remote_path, session_id) with 100% coverage. The description adds no additional parameter semantics beyond what the schema already provides, 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 clearly states the tool uploads a local file to a remote board via SFTP, and explicitly notes it reuses an existing SSH session. This specific verb+resource+method distinguishes it from siblings like ssh_sftp_download and serial_upload.

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 provides clear context: it reuses an existing SSH session, implying the user must have opened one first. It does not explicitly name alternatives or state when not to use it, but the context is sufficiently clear to guide the agent.

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

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It states that the session is closed and the connection released, but does not describe consequences like subsequent reads/writes failing, idempotency, or cleanup of associated resources. This is minimal and lacks important behavioral context for a mutation-like operation.

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

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

The description is a single concise sentence that directly states the tool's purpose without any fluff or redundancy. Every word contributes to the meaning, making it highly efficient.

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 close operation with one parameter and no output schema, the description is adequate but misses key contextual details. It does not specify when to close, what happens if the session does not exist, or the post-conditions of closure. Given the lack of annotations, a slightly richer description would be more 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 input schema has 100% coverage, providing a clear description for session_id as 'The session ID returned by ssh_shell_open.' The tool description does not add further parameter meaning, but since the schema already fully documents the parameter, 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 clearly states the action: 'Close an SSH shell session and release the connection.' It uses a specific verb ('close') and resource ('SSH shell session'), and the 'SSH' qualifier distinguishes it from sibling close tools for serial, power, and adb shells.

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. It does not mention that it should be used after an SSH session is no longer needed, nor does it contrast with other close tools. The usage context is only implied by the name and sibling set.

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

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

No annotations provided. The description indicates it is a read-only operation (check, shows), but does not disclose whether it queries live state or cached data, or any permissions needed. Basic transparency is adequate for a simple check tool.

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

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

Two sentences, front-loaded with the verb, no unnecessary words. Efficiently conveys the tool's function.

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, no output schema), the description is fairly complete: it explains purpose and what it shows. However, it could mention the expected output format (e.g., list of IPs) for full completeness.

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

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

The single parameter `session_id` is fully described in the schema as 'The session ID returned by ssh_shell_open'. The description does not add additional meaning beyond that, so baseline 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 clearly states the verb 'Check' and the resource 'active SSH connections on the remote board', and specifies it shows client IPs connected to port 22. This distinguishes it from sibling tools like ssh_shell_open or ssh_shell_exec.

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 explicit guidance on when to use this tool versus alternatives. While the purpose is clear, there is no mention of exclusions or comparison to similar tools like network_scan_tool.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses the synchronous wait-for-output behavior and the single-channel concurrency hazard, which is valuable. However, it does not mention potential side effects of executing arbitrary commands, permission requirements, or what happens when a command times out or continues running in the background.

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 three sentences, front-loaded with the core action, and every sentence earns its place. The concurrency warning is essential and the alternative for parallel execution is compactly stated without redundancy.

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

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

For a command-execution tool with 5 parameters and no output schema, the description covers the essential operational behavior, concurrency constraints, and a clear parallel alternative. The main gap is the lack of explicit return-value semantics, but the detailed parameter schema compensates for most technical details.

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 baseline is 3. The phrase 'Combines write + delay + read' adds slight framing for the delay/read components, but the description does not add per-parameter meaning beyond what the input schema already documents.

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+resource construction ('Send a command to an SSH shell session and wait for the output') and explicitly frames the tool as combining write + delay + read. This clearly distinguishes it from lower-level siblings like ssh_shell_write and ssh_shell_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?

It provides explicit when/how guidance: do not issue concurrent commands to the same session_id, always wait for previous command completion, and open multiple sessions via ssh_shell_open for parallel execution. This gives the agent actionable alternatives and timing constraints.

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

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

No annotations are provided, so the description carries the full burden. It discloses key behaviors: auto-detection of PSH state and auto-unlock if locked. However, it does not cover what happens on failure (e.g., unlock fails) or the exact return format, leaving some gaps in 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 extremely concise: two sentences that efficiently convey the tool's purpose and key behavior. No fluff, every sentence earns its place.

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

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

Given no output schema and no annotations, the description is fairly complete in explaining the compound operation. However, it lacks details on the return format ('ready session' is vague) and does not address error cases or prerequisites like needing an established connection, which would enhance completeness.

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% (all parameters have descriptions). The description does not add meaning beyond what the schema already provides for key, device, and timeout. Baseline score of 3 is appropriate as the description adds no extra semantic 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 clearly states the tool performs a compound operation: 'One-click SSH login: connect, detect PSH state, auto-unlock if locked, and return a ready session.' It specifies the verb (login) and the resource (SSH session), and distinguishes itself from sibling tools like ssh_shell_open and ssh_build by explicitly combining multiple steps.

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 that this tool is for quickly obtaining a ready SSH session without manual steps, but it does not explicitly state when to avoid using it or mention alternatives. It lacks explicit when-not or exclusion guidance, making it slightly less clear for precise decision-making.

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

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

With no annotations, the description carries the full transparency burden. It discloses that the session is interactive and returns the banner, but it omits important behavioral traits such as the session remaining open until closed via ssh_shell_close, potential authentication requirements, or side effects. This is minimal but not misleading.

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

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

The description is two short sentences, front-loaded with the primary action. Every word contributes meaning, and there is no redundant 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 tool of this simplicity, the description is adequate: it names the action and the return value. However, it does not mention the session lifecycle (e.g., that the shell must be closed later), which could be inferred from sibling tools but is not stated. Lacks a bit of context but is generally complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (device and timeout). The description adds no additional semantic meaning beyond what is in the schema, 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 clearly states the action (open), the target (interactive SSH shell session to the board), and the immediate result (returns the initial banner output). It distinguishes from sibling tools like ssh_shell_write, ssh_shell_read, and ssh_shell_exec by focusing on session opening.

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 provided on when to use this tool versus alternatives. The description does not mention that ssh_shell_exec or ssh_shell_write might be better for non-interactive commands, nor does it specify prerequisites or contexts where this tool should be avoided.

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

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

With no annotations provided, the description carries the full transparency burden. It discloses a critical behavioral trait: concurrent access corrupts the output buffer. However, it does not describe the output format, blocking/non-blocking behavior, or how reading affects the session beyond the clear flag documented in the schema.

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

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

The description is two efficient sentences: the first identifies what the tool does, and the second warns about a critical concurrency issue. There is no filler or unnecessary 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 read tool with no output schema and no annotations, the description is minimally viable: it gives the purpose and a key warning. It still leaves gaps around return value structure, buffer read behavior, and how to properly sequence reads after exec/write calls.

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 provides complete descriptions for both session_id and clear, so parameter coverage is 100%. The description's mention of session_id in the concurrency warning adds no extra semantic value beyond what the schema already states.

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 function with a specific verb and resource: 'Read output from an SSH shell session.' This distinguishes it from related siblings like ssh_shell_exec and ssh_shell_write, which handle sending input.

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 a concrete when-not condition: do not call concurrently with ssh_shell_exec/ssh_shell_write on the same session_id because it corrupts the output buffer. It lacks explicit guidance on when to prefer this tool over other read-like alternatives, but the purpose and exclusion are clear.

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

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

With no annotations provided, the description carries the full burden. It discloses the 'without appending a newline' behavior and lists the keys, but does not explain the effects of each control character (e.g., SIGINT, EOF) or any session state requirements. The schema does add these details, but the description itself could be more forthcoming.

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, well-structured sentence. It front-loads the verb, specifies the key characters, and adds a crucial qualifier. No unnecessary words or 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 simple tool with two parameters and no output schema, the description is adequate. It explains what to send, to which session, and notes the newline behavior. Slight gaps include explicit session-open prerequisites, but these are implied by the session_id parameter 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?

Schema coverage is 100% with thorough descriptions for both parameters. The description adds minimal value beyond the schema, only reinforcing the key values via 'Ctrl+C/U/D/Z' and the no-newline behavior. This meets the baseline for high schema coverage.

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

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

The description clearly states the tool's action ('Send a control character'), the target (SSH shell session), and the specific characters (Ctrl+C/U/D/Z). It distinguishes itself from siblings like ssh_shell_write by noting it does not append a newline.

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 usage context is implied: use for sending control characters to an SSH session, not for arbitrary text. However, it does not explicitly mention alternatives or when not to use it, leaving room for clearer guidance.

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

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

With no annotations provided, the description takes on full responsibility for disclosing behavioral traits. It reveals a critical concurrency hazard (output buffer corruption) and hints at buffering behavior, which is more than minimal. It does not detail return values or idempotency, but the disclosed risk is substantial.

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 exceptionally concise: two sentences, no wasted words. The purpose is front-loaded, and the safety warning is delivered efficiently. Every element serves a functional 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?

For a simple write tool with no output schema, the description covers its purpose and a key operational risk. It doesn't specify return behavior or the typical write-read flow with ssh_shell_read, but the schema handles parameter context, and the warning adds missing operational insight, making it fairly complete.

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

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

Schema description coverage is 100%, so parameters are well-documented in the structured data (e.g., 'clear' flag, 'command', 'session_id'). The tool description adds no extra parameter-specific meaning beyond what the schema already provides, meeting the baseline without exceeding it.

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 'Send a command to an SSH shell session' with a specific verb and resource. The concurrency warning referencing ssh_shell_exec/ssh_shell_read helps distinguish this tool from related siblings by implying its role in the write operation.

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

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

The description provides explicit usage constraints by warning against concurrency with ssh_shell_exec/ssh_shell_read on the same session, which names alternatives and gives a clear when-not-to-use context. However, it stops short of fully contrasting with all sibling tools or specifying ideal scenarios.

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

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

No annotations are provided, so the description carries the full burden. It transparently discloses the tool's behavior: it retrieves host IP, subnet mask, and gateway, calculates the subnet range, and determines if the target IP is in the subnet. This is sufficient for a read-only analysis tool, though it does not mention error handling or limitations.

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

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

The description is two sentences, with the first stating the main purpose and the second listing the specific computations and output. Every word contributes value, no redundant phrases, and it is appropriately sized for a single-purpose tool.

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

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

With only one parameter and no output schema, the description provides a comprehensive list of what the tool calculates and returns, including network address, broadcast address, usable host range, CIDR, and the same-subnet determination. This is enough for an agent to understand what to expect, though the exact output format is not specified.

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 fully documents the single parameter target_ip with a description and example, so the description doesn't need to add much. The description's mention of 'target IP' adds no extra meaning beyond the schema's definition, and with 100% schema coverage the baseline is 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 uses the specific verb 'Analyze' with the resource 'subnet information for a target IP address' and clearly lists the distinct calculations and outputs (network address, broadcast address, usable host range, CIDR) and the final comparison result. This distinguishes it from sibling tools like network_scan_tool and port_scan_tool, which are more about scanning than single-IP subnet analysis.

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 checking if a target IP is in the same subnet as the host, but it does not explicitly state when to use it versus alternatives like network_scan_tool, nor does it mention any exclusions or prerequisites. The usage context is clear but not explicitly contrasted with other tools.

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

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

No annotations provided, but the description indicates a safe read-only operation. It does not disclose any potential side effects or authentication needs, though none are likely for a version tool.

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

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

Single sentence that is front-loaded and contains no extraneous information. 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 no parameters, no output schema, and a simple purpose, the description is nearly complete. It could optionally mention the return format, but this is not critical.

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?

No parameters exist, so the description bears no parameter burden. The schema coverage is 100% (0 params), warranting a baseline of 4.

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 it retrieves the MCP server version and toolkit information. It distinguishes itself from sibling tools that focus on device/shell/network operations.

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 use when version/toolkit info is needed. No explicit when-not or alternatives provided, but for a simple query tool this is adequate.

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