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

No annotations are provided, so the description carries the burden of behavioral disclosure. It mentions the return format (list of dictionaries with name and description) but omits details like ordering, filtering, authentication needs, or potential side effects. It is adequate for a simple read operation but not rich.

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: the first explains the purpose, the second the return value. It is concise, front-loaded, and contains no unnecessary 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 zero parameters and an output schema that is described in the description, the description is fairly complete. It could mention whether the list is user-specific or static, but it is adequate for the tool's 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?

The tool has zero parameters, so the baseline is 4. The description adds no parameter information, but that is acceptable because no parameters exist and the schema coverage is complete.

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 that the tool retrieves a list of all available tools with their descriptions, using a specific verb and resource. It naturally distinguishes from sibling SSH tools.

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

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

The description provides clear context for usage (listing all tools), but does not explicitly state when not to use it or mention alternatives. However, given no sibling tools serve this purpose, it is still effective.

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

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

With no annotations, the description carries the full burden and does so richly: it discloses the silent Windows format substitution, the archive_path extension auto-correction, that failures return an error dict rather than raising, and the long-running in_progress/handle_id contract with ssh_cmd_check_status polling plus the single-concurrent-operation 'busy' limit. This is behavior an agent cannot infer from schema or annotations.

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

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

The purpose and the critical cross-platform caveat are front-loaded, and each caveat sentence carries distinct, actionable information. The 'Returns' block partially restates fields already covered by the output schema, which is the main source of 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 cross-platform archive tool with no annotations, the description covers the exact traps an agent needs: format degradation, extension correction, non-exception failure mode, and the async polling contract. Nothing required to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains that requesting tar.gz/tar on Windows actually yields zip and that archive_path may be auto-corrected. It says nothing extra about use_sudo, so it stops short of a 5.

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

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

States a specific verb and resource ('Create a compressed archive from a directory'), which cleanly distinguishes it from the sibling ssh_archive_extract that does the inverse operation. An agent can identify the tool's job from the first line alone.

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 Windows caveat effectively guides format selection by telling the agent that tar.gz/tar are silently degraded to zip and that no cross-platform-portable format exists, and it names ssh_archive_extract as the counterpart extractor. However, it never states plainly when to choose this tool over alternatives such as ssh_dir_transfer or ssh_cmd_run, so guidance is strong but implicit rather than explicit.

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 behavioral burden and does so: it distinguishes raised exceptions (BusyBox tar gap) from returned error dicts, explains that overwrite=False degrades to a warning on Linux but defers to Expand-Archive on Windows, and discloses the single-operation-at-a-time 'busy' constraint. These are non-obvious traits an agent could not infer from schema alone.

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

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

Front-loads the core action and the platform rule, and each paragraph carries real operational content. It is long and somewhat dense, with a few passages (the two 'independent gaps') that could be tightened, and it re-describes return fields already covered by the output schema, which costs a point.

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

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

For a 4-parameter mutation-adjacent tool with no annotations, it covers platform constraints, failure vs exception behavior, overwrite edge cases, fallback procedures, and the async in_progress/polling contract. An agent has everything needed to call it correctly and recover from its failure modes.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining that archive_path's extension alone determines the accepted format (not content sniffing) and by detailing the partial-success semantics of overwrite=False rather than just restating the flag. It does not add much on use_sudo or destination_path, keeping it short of a 5.

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

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

Opens with a specific verb+resource ('Extract an archive to a directory') and immediately scopes it against the sibling ssh_archive_create by explaining that the two operate on platform-specific formats. An agent can tell exactly what this does and how it relates to the archive-creation tool without opening any schema.

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

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

Explicitly states when extraction succeeds and when it fails (Linux/macOS tar-only vs Windows zip-only, with a worked example of the mismatch), notes that no cross-platform format exists, and names the fallback path via ssh_cmd_run for the BusyBox --strip-components gap. It also routes the agent to ssh_cmd_check_status for long calls and forbids re-invoking meanwhile.

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

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

With no annotations, the description carries the full burden and does so: background monitoring keeps collecting output/exit codes after a timeout, handles do not survive reconnects while ssh_task_launch PIDs do, the PID fallback returns a different status vocabulary, and the wait cap exists because MCP clients abort at ~60s. These are non-obvious behavioral traits an agent could not infer elsewhere.

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?

Purpose and polling rules are well front-loaded with clear terminal/non-terminal grouping, but the long 'Returns:' block largely duplicates the existing output schema, and the OPERATION-handle paragraph is verbose. Much earns its place; a meaningful portion does not.

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 high-complexity polling tool, the description enumerates every terminal and non-terminal status, explains the rare fallbacks, the not_found/unknown distinction, and the operation-handle variant. An agent has everything needed to poll correctly and interpret each result.

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 handle_id and wait_seconds (including the clamp and polling advice). The description restates handle_id's origin but adds no syntax, format, or edge-case detail beyond what the schema provides, so baseline 3 applies.

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

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

The opening sentence states a specific verb+resource ('check the status of a command started with ssh_cmd_run') and immediately scopes it as a polling companion to ssh_cmd_run. It is clearly distinguishable from ssh_task_status, ssh_cmd_output and ssh_cmd_kill without opening any schema.

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

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

Explicit when-to-use ('after ssh_cmd_run returns status=io_timeout or wait_timeout'), how-often ('call this repeatedly - it's designed to be polled'), what not to do ('Do not rerun the original command while polling'), and an alternative routing rule ('Prefer ssh_task_status directly for PIDs to avoid ambiguity'). All conditions that select this tool versus siblings 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?

With no annotations, the description carries the full behavioral burden. It discloses a genuinely non-obvious nuance (finished long-running operations are removed, still-running ones survive so they can be polled), which is valuable. However, it omits irreversibility of the clear, any permission requirements, and confirmation 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?

Two short sentences, with the core action front-loaded and the scope caveat immediately following. The 'Returns' line is slightly redundant given the tool has an output schema, but it is brief and does no real harm.

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 scope caveat is well handled and the presence of an output schema means return values need not be elaborated. For a zero-parameter, no-annotation tool, this is nearly complete; only the lack of any usage routing against sibling history/command tools leaves a small 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. No parameter-level detail is required or missing.

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

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

States a specific verb ('Clear') and resource ('command history for the current SSH connection'), which distinguishes it cleanly from the viewing sibling ssh_cmd_history. It does not name that sibling, so it stops short of explicit differentiation, but the verb plus the clarifying parenthetical makes intent 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?

Usage is only implied: an agent can infer this is for wiping history, and the parenthetical hints at the interaction with running operations. There is no explicit when-to-use, when-not, or alternative such as ssh_cmd_history or ssh_cmd_kill.

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 substantial work: it defines the origin taxonomy ('user' vs tool_internal/connection_probe/sudo_probe), explains parent_tool linkage, and flags the non-obvious behavior that stderr is NOT folded into output even for a failed command. It does not cover permissions, connection requirements, or pagination/cost limits.

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 purpose sentence is front-loaded and good, but the bulk of the text is a field-by-field return-value dump that largely duplicates the existing output schema. That padding dilutes the genuinely useful behavioral notes (origin labels, stderr exclusion).

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

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

An output schema exists, so the description is not obligated to enumerate return fields, yet it does so thoroughly and adds the origin/parent_tool and stderr semantics an agent needs. Missing pieces are usage routing and connection prerequisites, which are moderate rather than critical given the rich schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces include_output and the output/stderr split but adds no syntax or semantics beyond the schema's own parameter descriptions (limit, pattern, reverse, output_lines, include_internal are all documented there).

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

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

The opening sentence gives a specific verb and resource ('Retrieve command execution history') and the field breakdown makes clear this is a history-listing tool rather than a single-command output fetch. It implicitly contrasts with ssh_cmd_output (by noting stderr is 'retrieved the same way ssh_cmd_output(stream='stderr') would') and with origin/parent_tool fields, but never explicitly states how it differs from siblings like ssh_cmd_check_status.

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

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

There is no explicit when-to-use or when-not-to-use guidance. The description never says to reach for this tool instead of ssh_cmd_output or ssh_cmd_check_status, nor does it state prerequisites (e.g. that a connection must exist). The only scoping hints live in the schema's include_internal description, not in the tool description itself.

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 supplied, so the description carries the full burden and does so: it enumerates every terminal state a kill can end in, explains the force+wait_seconds escalation to SIGKILL, defines force_kill_used precisely (attempted, not succeeded), and discloses the side effect that ssh_cmd_check_status will later report 'killed'. Permission, reversibility, and ambiguity cases are all addressed.

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

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

Front-loaded with purpose and routing in the first two paragraphs, then error conditions, then returns. It is long, and the Returns block partially restates the output schema, but the per-state semantics justify most of the length.

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

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

For a 4-parameter mutation tool with no annotations, the description closes every gap an agent needs: identifier provenance, escalation policy, full result vocabulary including the ambiguous 'failed_to_kill' and 'error' states, and the downstream status effect. Nothing required to invoke or interpret it is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further: it clarifies that handle_id is a history lookup rather than a raw PID, that force only matters if the process survives wait_seconds, and how signal and force interact. It does not add much on wait_seconds beyond the schema default.

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

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

States a specific verb+resource (terminate a running command) and immediately scopes the identifier type: the handle_id from ssh_cmd_run, explicitly contrasted with raw PID. An agent can distinguish it from ssh_task_kill without opening any schema.

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

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

Names the alternative tool and the exact condition for choosing it (background tasks from ssh_task_launch → ssh_task_kill with PID). It also states the failure condition (handle not in this connection's history; handles don't survive reconnects), which is a genuine when-it-won't-work 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?

No annotations are provided, so the description carries the full behavioral burden and does so richly: separate non-interleaved stdout/stderr buffers, ~2 MB per-stream retention with earliest lines dropped, an error naming the first available line for dropped requests, a ~32 KB inline truncation limit on ssh_cmd_run, and handles not surviving reconnects.

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

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

Front-loaded with the core purpose and useful scoping/alternative guidance in the first two sentences, and clearly sectioned. It is somewhat long, and the explicit 'Returns' block partially restates what the output schema already provides, so a small amount of trimming is possible.

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 4 params, no annotations, and an available output schema, the description covers limits, error cases, retention behavior, and alternatives thoroughly. An agent has everything needed to call it correctly and interpret its results.

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

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

Schema description coverage is 100%, so the schema already documents lines, stream, handle_id, and start_line semantics. The description reinforces the stream distinction and line-paging idea but adds little syntax or format detail beyond the schema, matching the baseline 3 when the schema does the heavy lifting.

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

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

States a specific verb+resource ('Retrieve captured output from a command started with ssh_cmd_run, identified by its handle_id') and ties the resource directly to its producing sibling. An agent can distinguish it from ssh_cmd_check_status/ssh_cmd_history, which the description explicitly routes elsewhere.

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

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

Gives concrete when-to-use conditions: after an io_timeout/wait_timeout to see progress, to page through output a response didn't include in full, or to re-inspect output without rerunning. It also names alternatives (ssh_cmd_check_status, ssh_cmd_history, ssh_task_launch) for adjacent needs.

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 behavioral burden and does so thoroughly. It discloses timeout semantics (io_timeout, wait_timeout, runtime_timeout), handoff behavior, background monitoring, connection lifetime, Windows cmd.exe behavior, working directory independence, output handling, and detailed status values. This goes far beyond what any annotation would typically provide.

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 long but well-structured with clear headings (Timeout semantics, Windows targets, Working directory, Returns). Every section addresses a likely agent question. It is front-loaded with the core behavior, then structured details. While lengthy, it is not redundant and each part 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 description is extremely complete for a complex tool with 6 parameters and an output schema. It covers timeout semantics, handoff behavior, status meanings, connection lifetime differences from ssh_task_launch, working directory independence, Windows command syntax, output truncation and stream separation, and all status values. Given the complexity, it provides everything an agent needs to call 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 schema already provides detailed parameter descriptions. The description reiterates and expands on timeout parameters and cwd, but since the schema covers everything, the baseline 3 is appropriate. The description adds meaningful behavioral context for timeouts (e.g., io_timeout fires only on silence) that complements 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?

States a precise verb (Execute) and resource (a command on the remote host) and immediately describes the blocking behavior. Clearly distinguises it from siblings like ssh_task_launch and ssh_cmd_check_status by explaining scope and blocking semantics.

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 names when to use this tool vs alternatives: e.g., 'For anything that may take more than about a minute, ssh_task_launch is usually the better tool' and 'For commands that should survive you disconnecting/reconnecting entirely, use ssh_task_launch instead'. Also gives detailed timeout selection guidance.

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

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

With no annotations provided, the description carries the full burden and does so: it discloses that a duplicate key returns an error dict rather than raising, that credentials are stored in plaintext in ~/.mcp_ssh_hosts.toml, that it writes to whichever config file is active, that credentials become visible to the LLM, and that the agent must not read the file directly. This is exactly the safety/permission context annotations would otherwise supply.

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

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

Front-loaded with the most decision-critical caveat (no overwrite) and organized with bullets for auth modes and optional fields. It is long and includes some repetition (config-file location stated twice, plus return values already covered by the output schema), which keeps it from a 5.

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

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

Covers everything an agent needs for a 9-parameter mutation tool: auth prerequisites, duplicate-key failure mode, active-config selection, credential visibility warning, and expected success/error payloads (redundant given the output schema, but harmless). Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds relational meaning the schema cannot: password OR keyfile (or both), key_passphrase only for encrypted keys, and sudo_password being required for key-only auth unless passwordless sudo is configured. These are constraints not expressed in the per-parameter schema text.

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

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

The first sentence states a specific verb+resource ('Add a new host configuration to the host configuration TOML file'), and the second explicitly disambiguates from the similarly-named ssh_host_update, noting that despite the name it does NOT update existing entries. An agent can distinguish this from ssh_host_list, ssh_host_update, and ssh_host_remove without opening any schema.

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

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

Explicit routing guidance: check 'ssh_host_list' first because the host may already be configured and 'ssh_conn_connect' can be called directly; use ssh_host_update if the entry exists. It also states the preconditions for password vs keyfile auth and when sudo_password is required. This is when-to-use, when-not-to-use, and alternatives all in one.

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 delivers: it discloses the capability probe behavior for linux/flex targets, that missing capabilities fail with named errors rather than silent degradation, the os_type='flex' fallback for unrecognized POSIX kernels, the in_progress/handle_id long-running contract with polling instructions, and the single-concurrent-operation 'busy' error.

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?

Long but dense; most sentences earn their place (long-running contract, capability model, busy constraint). The two 'os_version' field explanation leans toward restating output-schema detail and is the weakest portion, but overall it is front-loaded and disciplined.

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 connection tool that can hang, this covers the async handle/polling flow, the concurrency limit, platform classification, and capability probing. Although an output schema exists, the remaining prose is behavioral rather than shape-describing, so nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% for the single host_name parameter, so the schema already documents it. The description reinforces the 'user@hostname or alias' semantics and clarifies hosts must be pre-configured, but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource: establish an SSH connection to a pre-configured host. It also distinguishes itself from siblings like ssh_conn_status, ssh_conn_is_connected, and ssh_conn_host_info by framing this as the connection-establishment step and explaining the host key/alias resolution.

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 explains how to identify the host (user@hostname or alias) and, crucially, the long-running fallback ('do not call it again', poll ssh_cmd_check_status instead) and the one-operation-at-a-time constraint. However, it gives no explicit guidance on when to use this versus alternatives such as ssh_host_add_host or ssh_host_use_config when a host is not yet configured.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it discloses async behavior (in_progress + handle_id after the 50s wait cap), the required polling tool, the prohibition on calling again during the wait, and the one-at-a-time concurrency limit with a 'busy' failure mode. It also describes the returned system details and capability fields for specific connection types.

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 purpose and then uses clear sections ('Returns:' and 'Long-running calls:'). It is somewhat long, but the async and concurrency details earn their place because they change how an agent must invoke and follow up on the tool.

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

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

Given that an output schema exists, the description does not need to explain return values, yet the extra return-value context is helpful. It covers the async and concurrency behavior completely, but it still lacks explicit sibling differentiation from ssh_conn_status or ssh_conn_is_connected.

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

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

The tool takes zero parameters, so the baseline is 4. The empty schema and description correctly reflect that no input arguments are needed, and there are no parameter semantics to clarify.

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

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

The description states a specific verb and resource: 'Get detailed SSH connection status and system information.' It is clear what the tool retrieves, but it does not explicitly distinguish itself from sibling tools like ssh_conn_status or ssh_conn_is_connected, leaving mild ambiguity about which connection-status tool to choose.

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 useful usage guidance for long-running calls: poll ssh_cmd_check_status with the returned handle_id, do not call again meanwhile, and only one such operation runs at a time. However, it provides no when-to-use guidance relative to alternatives such as ssh_conn_status or ssh_conn_is_connected.

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, and it does meaningful work: it discloses timing expectations (a few ms normally, at most ~5s) and the side effect that a dead connection is detected and dropped. It does not state whether it blocks, nor whether any auth/permission is needed, but the drop-on-failure behavior is real added value.

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

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

Front-loaded with the core guarantee ('real round trip... not just a cached flag') followed by the failure-recovery hint; every sentence earns its place. The Returns block slightly duplicates the output schema, which costs a point.

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

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

With an output schema present, explaining the bool return is not strictly required, and the description covers timing, side effects, and next steps. The one gap is that it never says WHICH connection is checked given the zero-parameter signature (current/default host context is left implicit).

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

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

The tool takes zero parameters, so the baseline is 4. The description goes slightly further by naming the follow-up call and its argument shape (ssh_conn_connect(host_name=...)), hinting how the host is selected after a failed check.

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+resource — 'Check whether there is a WORKING SSH connection' — and sharpens it by defining 'working' as a real round trip rather than a cached flag. It does not, however, name or differentiate itself from the sibling ssh_conn_status, which an agent must distinguish on its own.

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 (use it to detect connections that died while idle) and a follow-up action is given for the False case (reconnect with ssh_conn_connect). But there is no explicit when-to-use/when-not or contrast against ssh_conn_status, leaving the agent to infer which connectivity check to call.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the in_progress/handle_id return shape, the wait cap, the polling contract via ssh_cmd_check_status, and a concurrency constraint ('only one such operation runs at a time... fails with a busy error'). These are non-obvious runtime behaviors not captured by any structured field.

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

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

Front-loaded with the purpose and return shape, followed by the long-running behavior. The async paragraph is long but every clause (wait cap, handle_id, poll target, busy error) is load-bearing, so it stays 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 parameterless read tool with an output schema, the description covers purpose, returned fields, and the full async/concurrency contract. An agent has everything needed to invoke and re-invoke it correctly.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify beyond the empty schema, and it introduces no spurious parameter semantics.

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

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

States a specific verb and resource ('Get essential SSH connection status information') and even enumerates the returned fields (user, working directory, OS type), which helps separate it from ssh_conn_is_connected. However, it never names or contrasts with those siblings, so the agent must infer the distinction.

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

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

It gives clear guidance for the async case ('Do not call it again meanwhile', poll ssh_cmd_check_status), but offers no guidance on when to use this versus ssh_conn_is_connected or ssh_conn_host_info. Usage is implied by the purpose rather than 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?

With no annotations, the description carries the full burden and does so well: it guarantees no privileged command is executed, explains platform-specific detection logic (passwordless vs. password-based sudo on Linux/macOS; session-level Administrator check on Windows), documents return semantics, and discloses the long-running/in_progress behavior and busy error. This is unusually rich behavioral 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 well front-loaded and organized with clear labels ('On Linux/macOS:', 'On Windows:', 'Returns:', 'Long-running calls:'). It is somewhat long, and the detailed Returns block partially duplicates the existing output schema, but every section still aids correct invocation.

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, cross-platform capability-check tool with long-running behavior, the description covers purpose, platform-specific semantics, return fields, and timeout/polling mechanics. An agent has everything needed to call it and to handle the in_progress case without consulting other sources.

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

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

The tool takes zero parameters, so there are no parameter semantics to add; the baseline for 0 params is 4. The description correctly introduces no parameters and instead documents platform behavior, which is the relevant information here.

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

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

The description states a precise verb and resource ('Check whether elevated access is available on the remote system') with an explicit scope constraint ('without running any privileged command'), which clearly distinguishes it from command-running siblings like ssh_cmd_run. An agent can identify it immediately as a pre-flight capability probe rather than an action tool.

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

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

It explicitly says when to call it ('Call this before using use_sudo=True on other tools if you're not sure elevation will succeed') and names the sibling to poll for long-running results (ssh_cmd_check_status(handle_id=...)). It also defines the concurrency limit ('Only one such operation runs at a time'), leaving little to inference.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the dry_run safety default, the BusyBox error condition with a capabilities check, the in_progress/handle_id behavior past the 50s wait cap, polling via ssh_cmd_check_status, and the 'busy' failure mode. These are exactly the behavioral traits an agent cannot infer from 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?

Front-loaded with the core action and the safety-critical dry_run default, then layered with fallback and long-running details. It is long, but nearly every sentence is operationally load-bearing; the Returns block is slightly verbose relative to the existing output schema.

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

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

Given a destructive mutation tool with no annotations, 4 parameters, and a long-running mode, the description covers safety defaults, failure modes, fallbacks, polling, and result-shape differences. Nothing material an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so baseline is 3; the description adds real meaning on top by spelling out that dry_run defaults to True and only previews, that pattern uses ssh_dir_search_glob syntax, and that path is the base search directory. It stops short of describing use_sudo semantics, so not a 5.

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

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

States a specific verb and resource ('recursively find and delete files matching a filename glob pattern') and immediately differentiates from siblings by referencing ssh_dir_search_glob's pattern syntax and contrasting the return key with ssh_dir_delete's `deleted_items`. An agent can identify this tool without opening any schema.

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

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

Explicitly states the dry_run default and the consequence of omitting it (preview only, nothing deleted), names the fallback path (ssh_cmd_run with find -exec rm -f) for BusyBox xargs without -0, and explains the long-running polling workflow and the one-at-a-time constraint. When-to-use and when-to-substitute are both covered.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: platform-dependent error conditions, capability preconditions, a viable fallback, the exact return shape, async behavior past the 50s wait cap, the polling tool to use, and a concurrency constraint ('only one such operation runs at a time ... fails with a busy error'). This is unusually complete disclosure.

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

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

Front-loaded with the core purpose, then organized into platform caveat, return format, and long-running behavior sections. Every sentence carries information, though the return-format block restates a documented output schema, adding slight 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 tool with real complexity (platform quirks, async handles, concurrency limits) the description covers everything an agent needs to call it correctly — preconditions, failure modes, polling path, and result shape. Nothing material is missing.

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

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

Schema coverage is 100% and there is a single required 'path' parameter already documented in the schema. The description adds only implicit meaning via the du example ('<path>' as a directory), which is marginal beyond the schema 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?

States a specific verb and resource ('Calculate the total size of a directory recursively') and immediately defines the exact semantics — sum of regular files, directory entries excluded, platform-independent. An agent can distinguish it from ssh_file_stat or ssh_dir_list_advanced without opening any schema.

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

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

Gives concrete when-not guidance (raises on 'linux' connections lacking find -printf, with a capability check reference) and an explicit alternative fallback (ssh_cmd_run("du -sk <path>")) along with the tradeoff (KB, includes directory overhead). It stops short of comparing against sibling tools like ssh_file_stat for single-file sizing, but the routing context 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, so the description carries the full burden and does: overwrite=True deletes the entire existing destination first (a destructive detail), overwrite=False merges and silently overwrites name collisions, async in_progress/handle_id behavior past the 50s wait cap, and a single-concurrent-operation constraint. This is exactly the destructive/async context an agent needs before calling.

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

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

Front-loaded purpose followed by a scannable bullet for the critical overwrite distinction; nearly every sentence earns its place. The Returns block overlaps with the existing output schema, though the caveat about files_copied/bytes_copied counting total destination contents (not just newly copied files) is real added value.

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

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

For a destructive, potentially long-running recursive copy, the description covers routing, overwrite semantics, return shape interpretation, and the async polling contract. Nothing an agent needs to invoke or correctly interpret this call is missing.

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

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

Schema coverage is 100% so baseline is 3, but the description adds genuine meaning beyond the schema's thin 'Overwrite existing files' label by spelling out delete-then-copy vs merge-and-silently-overwrite, and explicitly contrasts it with the same-named parameter on other tools. use_sudo, preserve_symlinks and preserve_permissions get no added detail 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?

States a specific verb+resource (recursive remote-to-remote directory copy) and immediately distinguishes itself from ssh_dir_transfer for local<->remote work, and from ssh_file_move/ssh_file_copy's overwrite semantics. An agent can route correctly without opening any schema.

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

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

Explicit when-to-use (remote-to-remote) and when-not (local<->remote → ssh_dir_transfer). It also gives operational guidance: poll via ssh_cmd_check_status rather than re-calling, and only one such operation runs at a time with a 'busy' error otherwise.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses the dry_run=True default and its consequence, the critical-path refusal list, the presence/absence semantics of the 'dry_run' return key, the in_progress handle behavior past the 50s wait cap, and the one-operation-at-a-time 'busy' failure. This is far beyond what the schema conveys.

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

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

Front-loads the destructive-recursion purpose and the dry_run default, which are the highest-stakes facts, and every section (return, long-running) earns its place. It is dense and slightly long, with heavy capitalization for emphasis, but not padded.

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

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

For a destructive, potentially long-running tool with no annotations, the description covers safety defaults, refusal behavior, return shape (even though an output schema exists), and async/polling semantics. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description meaningfully extends `dry_run` beyond the schema's one-liner by explaining that omitting it previews and nothing is deleted unless `dry_run=False` is passed explicitly. `use_sudo` gains no additional explanation, keeping it from a 5.

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

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

States a precise verb+resource with scope ('Delete a directory and all its contents recursively') and explicitly names the sibling it is not ('For a simpler non-recursive removal without the preview step, see ssh_dir_remove'). An agent can distinguish it from ssh_dir_remove and ssh_dir_batch_delete_files without opening any schema.

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

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

Gives explicit when-to-use context (recursive removal with preview) and routes to the alternative (ssh_dir_remove) for the non-recursive case. It also warns against re-calling during a long-running operation and points to ssh_cmd_check_status for polling.

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 discharges it well: it discloses the BusyBox `find` failure mode and that it raises an error rather than degrading, the Windows placeholder values for permissions/group, the async long-running behavior (in_progress + handle_id + polling ssh_cmd_check_status, don't re-call), and the single-concurrent-operation 'busy' limit.

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

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

Front-loaded with purpose and routing, then progressively deeper detail; each block (depth semantics, platform caveats, returns, async) earns its place. It is on the long side and the returns section partly overlaps the existing output schema, but nothing is filler.

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

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

Complete for a tool of this complexity: it covers routing, depth semantics, platform-specific errors and fallbacks, the return shape including cross-tool type-code differences, and async polling. An agent has everything needed to call it correctly and recover from the documented failure modes.

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 would be 3, but the description adds genuine meaning to `max_depth` by explaining `find -maxdepth` semantics with a concrete example (max_depth=1 = path plus immediate children; omit for unlimited). It does not elaborate on `use_sudo`, though that parameter is self-describing in 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?

States a specific verb and resource ('List contents of a directory recursively') plus the distinguishing metadata it returns (size, permissions, ownership, modification time). It explicitly differentiates itself from ssh_dir_list_files_basic (bare filenames, non-recursive) and ssh_dir_search_glob (pattern-only, faster on large trees), so an agent can route correctly without opening either schema.

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

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

Gives explicit when-to-use and when-not-to-use guidance, naming both alternatives and the conditions that select them ('when you need more than just names', 'when you only need to filter by filename pattern'). It also documents a fallback path with concrete steps (list_files_basic + ssh_file_stat per entry) for constrained hosts.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses the async long-running pattern (50s wait cap, {"status": "in_progress", "handle_id"} fallback), how to retrieve results via ssh_cmd_check_status, a do-not-retry instruction, and a single-concurrency 'busy' failure mode. This is exactly the behavioral context annotations would otherwise need to supply.

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

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

Front-loads the core purpose, then routing alternatives, then a labeled 'Returns' block, then a labeled long-running note. Every sentence earns its place, and the sectioning makes each concern scannable.

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

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

For a one-param listing tool with an output schema present, all an agent needs is covered: scope, routing to alternatives, return shape, and the async/polling protocol. Nothing required for correct invocation is missing.

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

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

Only one parameter (path) and schema coverage is 100%, so the schema already fully documents it; per the baseline rule this lands at 3. The description reinforces that listing is of the immediate contents of `path` and returns bare filenames rather than full paths, which adds mild clarity but no new syntax.

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

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

States a specific verb (List) and resource (directory contents) with precise scope qualifiers: non-recursive, no metadata, via SFTP. It explicitly names the sibling tools it is not (ssh_dir_list_advanced, ssh_dir_search_glob) so an agent can distinguish it without opening another schema.

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

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

Gives explicit when-to-use-else guidance: for recursive/metadata listings or pattern filtering, use ssh_dir_list_advanced or ssh_dir_search_glob, and for file-vs-directory determination use ssh_file_stat or ssh_dir_list_advanced. Alternatives and their selecting conditions are named directly.

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

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

With no annotations, the description carries the full behavioral burden and does: non-recursive SFTP mkdir vs. sudo mkdir -p, Windows New-Item -Force semantics, mode being silently ignored on Windows, exception-on-failure, and the long-running handle/poll protocol including the single-concurrent-operation 'busy' constraint.

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

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

Front-loaded with the core purpose and organized into scannable bullets, with no filler prose. It is somewhat long, and the bulleted return-value breakdown partially duplicates the existing output schema, which keeps it short of a 5.

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

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

For a platform-divergent mutation tool with an output schema, the description covers what an agent needs: platform/sudo matrix, failure mode, and the async handle handoff to ssh_cmd_check_status. Nothing required to call it correctly is missing.

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

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

Schema coverage is already 100%, but the description adds real meaning beyond it: `mode` applies to the created directory, is ignored entirely on Windows, and `use_sudo` not only toggles sudo but changes recursion behavior and is a no-op on Windows.

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

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

The opening sentence gives a precise verb and resource ('Create a directory on the remote system'), which is unmistakable against the delete/remove siblings in the tool list. An agent can identify the operation without opening the schema.

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

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

It spells out the exact conditions under which the call succeeds or fails per platform and sudo flag, which is effectively usage guidance for invoking it correctly. It does not, however, name an alternative tool or state when to prefer another approach (e.g. batch creation via ssh_cmd_run).

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

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

With no annotations, the description carries the full burden and does so well: immediate action, exception rather than error dict on non-empty dir with recursive=False, no partial deletion, and the in_progress/handle_id polling contract with the single-operation 'busy' constraint. The only gap is that it does not discuss sudo/permission requirements beyond noting permission-denied as a failure cause.

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

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

Front-loaded with the core action and the sibling comparison, then structured into failure behavior and long-running behavior. The 'Returns:' block partially restates what the output schema already encodes, adding some redundancy, but the exception and handle_id details are not recoverable from structured fields.

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

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

Covers purpose, alternative routing, failure mode, partial-delete semantics, and the async polling contract for a tool that can exceed the server wait cap. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes beyond the schema by spelling out the behavioral consequence of recursive=False (raises rather than partially deleting) and confirming the default. use_sudo is left to the schema alone, so it falls short of a 5.

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

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

States a specific verb and resource ('Remove a directory on the remote system') and immediately anchors it to the familiar rmdir/Remove-Item semantics, which lets an agent distinguish it from ssh_dir_delete without opening either schema.

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

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

Explicitly routes the agent: use this for simple non-preview removal, use ssh_dir_delete for a safer recursive delete with a dry_run preview step. It also warns there is NO dry-run here, so the when-not is stated, not inferred.

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 exist, so the description carries the full burden, and it does so richly: platform-dependent regex flavor (POSIX ERE vs Python re), Windows SFTP fallback handling, the 'incomplete' result shape that avoids false 'no matches' claims, and the async handle_id/polling contract with the single-operation 'busy' constraint. This is exactly the behavioral context annotations would otherwise supply.

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

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

Front-loaded with purpose before diving into platform behavior and return shapes, and each sentence conveys distinct operational value. It is longer than typical but not padded; the inline sibling comparison in the first sentence is slightly dense.

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 search tool with an output schema, the description still covers the non-obvious return variants ('incomplete' with skipped list, 'in_progress' with handle_id) and the error condition for an unreadable dir_path. An agent has everything needed to invoke and interpret 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%, so the baseline is 3, but the description adds genuine meaning beyond the schema: it clarifies that regex=True changes the regex dialect by platform (with PCRE-avoidance guidance) and that regex=False performs literal fixed-string matching. The use_sudo and case_sensitive params get no extra description, keeping it just short of 5.

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

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

States a specific verb+resource ('Recursively search file CONTENTS for a pattern under a directory') and immediately distinguishes itself from two named siblings (ssh_dir_search_glob for filenames, ssh_file_find_lines_with_pattern for a single known file). An agent can route correctly without opening any schema.

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

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

Explicitly contrasts this tool against its closest alternatives and states the selecting condition for each. It also gives when-to-use regex vs literal mode and platform caveats, leaving nothing to inference.

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

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

No annotations are provided, so the description carries the full burden and does so well: it discloses the cross-platform max_depth behavior, the BusyBox find failure mode (errors instead of running), the return shape with single-character type codes, and the long-running in_progress/handle_id polling protocol including the one-at-a-time busy constraint.

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?

Purpose is front-loaded, then alternatives, then semantics, limitations, and returns in clearly ordered blocks. It is on the long side and the long-running paragraph is dense, but nearly every sentence delivers operative detail rather than filler.

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

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

With an output schema present the description needn't restate return values, yet it adds the non-obvious type-code decoding. Combined with the BusyBox limitation, fallback path, and async polling contract, an agent has everything needed to call and recover from 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains find -maxdepth semantics and that max_depth=1 includes the base path plus immediate children only, and it documents when include_dirs applies. use_sudo is left to the schema, keeping it short of a 5.

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

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

States a specific verb (recursively search), resource (files/directories), and scope (filename glob, name-only) in the first sentence. It explicitly differentiates itself from two siblings by name, so an agent can route correctly without opening any schema.

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

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

Names the alternatives and the exact condition that selects them: ssh_dir_search_files_content for content matching, ssh_dir_list_advanced for metadata, and ssh_dir_list_files_basic as a fallback when BusyBox find lacks -printf. When-to-use and when-not-to-use are both covered.

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

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

With no annotations, the description carries the full burden and does so well: archive-based mechanism, OS-dependent format selection, exact destination layout semantics (contents vs enclosing folder), the full result contract, long-running handle behavior, and the concurrency/busy error. This is unusually rich behavioral disclosure.

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

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

Front-loads purpose and uses clean bullets. Some content is redundant: an output schema exists, yet the description enumerates every return field, which consumes space without adding value beyond the schema.

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

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

For a complex, mutation-oriented transfer tool with async execution, the description covers the tricky edge cases an agent needs: destination layout, format selection, long-running handle polling, and busy errors. Nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema by explaining the asymmetric destination semantics (upload places contents into remote_path, download places the folder inside local_path). The use_sudo implication is left to 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?

States a precise verb and resource ('Transfer directories between local and remote systems') and the scope ('directories', not files) implicitly separates it from the ssh_file_transfer sibling. An agent can identify the operation and its two modes (upload/download) without opening the schema.

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

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

The description gives operational guidance for polling (use ssh_cmd_check_status, don't re-invoke meanwhile) and notes a one-at-a-time busy constraint. However, it never explicitly says when to choose this over the closely-related ssh_file_transfer or ssh_dir_copy siblings, so tool-selection guidance is only implied.

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 and does so thoroughly: it declares that failures return a dict rather than raising, that the timestamp is non-configurable and inserted before the extension, the default 50s wait cap, the in_progress/handle_id escape hatch, the polling tool to use, and the single-concurrent-operation 'busy' constraint.

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

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

Front-loads purpose and the sibling exclusion first, then appends behavioral detail in clearly labeled Returns / Long-running blocks. It is longer than average but nearly every sentence conveys a constraint an agent needs; only minor tightening of the timestamp prose would help.

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

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

For a mutation tool with no annotations, the description supplies the missing safety and control context: failure-not-exception semantics, non-reversibility-adjacent details of timestamping, concurrency limits, and the async handoff. Even though an output schema exists, the added return-shape detail is accurate and 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 baseline is 3, but the description goes well beyond the schema on append_timestamp by spelling out the exact format (%Y%m%dT%H%M%S), the insertion point (before the extension), and a concrete example, while flagging what it is not (not appended after, not configurable). use_sudo and the path params get no additional treatment, keeping it just short of a 5.

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

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

States a specific verb (copy) and resource (file on remote host) and immediately scopes it: 'source and destination are both remote paths'. It names the sibling it is not (ssh_file_transfer) and the condition that selects that sibling (local<->remote), so an agent can distinguish it without opening any schema.

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

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

Provides an explicit when-to-use-this vs when-to-use-the-alternative rule ('for local<->remote transfers use ssh_file_transfer instead'), plus the operational condition for the long-running path ('if this takes longer than the server's wait cap...'). Nothing is left to inference.

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

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

With no annotations, the description carries the full burden and does so thoroughly: uniqueness constraint, zero/multi-match failure behavior, error returned as a value rather than a raised exception, sudo read semantics, the 50s wait cap with {'status': 'in_progress', 'handle_id'} fallback, the single-concurrent-operation 'busy' error, and the polling tool. This is far beyond what the schema conveys.

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

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

Front-loads the core action and the uniqueness rule, then uses labeled sections for Returns and Long-running calls. It is longer than typical, but the structure is clear and each block (error contract, wait-cap behavior) carries distinct information, so little is wasted.

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

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

For a mutation tool with sudo options and long-running support, the description covers failure modes, return shape, concurrency limits, and async polling. Despite an output schema existing, the extra detail on the non-obvious in_progress/busy behavior leaves nothing an agent needs missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: match_line is 'whitespace-trimmed, literal text - not a pattern' and must match exactly one line. It also explains the deprecated force/use_sudo read behavior. Meaningful value over the schema's one-line parameter descriptions.

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

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

States a specific verb and resource ('Delete a line by its exact content') and pins down the matching semantics precisely. It distinguishes itself from ssh_file_replace_line by naming the equivalence and from ssh_file_find_lines_with_pattern by pointing to it as a prerequisite. An agent can select it without opening any schema.

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

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

Explicitly says to run ssh_file_find_lines_with_pattern first if uniqueness is uncertain, and explains what happens when the match is not unique. It also clarifies this is a shortcut for ssh_file_replace_line_multi(new_lines=[]), giving a clear alternative and the condition that selects each.

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 and does so richly: per-platform regex flavor (POSIX ERE on Linux/macOS vs Python re on Windows), the local-SFTP-read rationale on Windows, error-key semantics, and the long-running in_progress/handle_id polling contract via ssh_cmd_check_status with a 'busy' single-op constraint.

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

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

Front-loaded with purpose and sibling routing, then regex/Windows rationale, then returns, then long-running behavior. It is long, but nearly every sentence carries non-obvious operational value rather than restating structured fields.

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

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

For a search tool with an output schema already present, everything an agent needs is covered: return shape, no-match-is-not-an-error semantics, error key, and the async polling path. Nothing material is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes further by explaining regex semantics that the schema only gestures at: the exact regex dialect per platform and the PCRE-pitfall example (\d vs [0-9]/[[:digit:]]), plus that regex=False means a literal fixed-string match. use_sudo is left to 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?

States a specific verb (search), resource (a remote file), and scope (return matching lines with line numbers). It is immediately distinguishable from siblings like ssh_file_read (whole file) and ssh_dir_search_files_content (directory-wide).

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 routes the agent: use this to find WHERE a pattern occurs, then ssh_file_get_context_around_line for surrounding lines, or ssh_file_replace_line/ssh_file_delete_line_by_content for editing. It even names the prerequisite those edit tools have (exact, unique line match) that this tool helps satisfy.

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

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

With no annotations, the description carries the full burden and does so: it discloses the SFTP read + local matching model, Unicode/non-ASCII safety on all platforms, and the long-running async contract (50s wait cap, in_progress handle_id, poll via ssh_cmd_check_status, single-operation concurrency with a 'busy' failure). This is unusually complete behavioral disclosure.

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

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

Front-loaded purpose followed by clearly separated guidance and a Returns block; every section earns its place. It is somewhat long, and the return-shape detail is redundant given the output schema, which keeps it from a 5.

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

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

For a 4-param tool with no annotations, the description covers purpose, uniqueness precondition, alternative tool, platform safety, and the async polling contract. Although an output schema exists (so return values needn't be restated), the added detail does no harm and nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real semantics beyond the schema: match_line is 'whitespace-trimmed, literal text, not a pattern', which is not obvious from the schema's 'Exact line content to match'. context and use_sudo are left to the schema, so it stops short of a 5.

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

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

States a specific verb and resource ('Get lines before and after a line ... to see it in context before editing') and explicitly positions itself against the line-editing tools it complements. An agent can distinguish it from ssh_file_replace_line and siblings without opening a schema.

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

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

Gives explicit when-to-use ('before editing') and a concrete prerequisite path: use ssh_file_find_lines_with_pattern first if the line's uniqueness is uncertain. It also states the hard precondition that match_line must match exactly one line, which routes the agent correctly.

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

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

With no annotations, the description carries the full burden and delivers: exact literal (non-pattern) matching, whitespace-trimmed comparison, hard failure on zero or multiple matches rather than guessing, failure returned as a value not a raised exception, deprecated force param, sudo read behavior, and long-running/polling/busy semantics. This is unusually complete behavioral disclosure.

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

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

Front-loaded with the core behavior and match constraint, then failure modes, then the async polling caveat. Every section is useful, though the long-running paragraph is somewhat verbose and the RETURNS block partly duplicates the output schema.

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

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

Covers the mutation, its preconditions, its failure contract, and the async completion path, so an agent has everything needed to invoke and interpret the tool. The explicit return-key naming (lines_inserted vs lines_written on siblings) further reduces cross-tool confusion.

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, and the description adds genuine meaning: match_line must match exactly one line literally, lines_to_insert format conventions (single, multiple, empty-string), and that force is deprecated. It clarifies rather than merely restates 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?

States a specific verb and resource ('Insert one or more new lines immediately after a matching line') with clear scoping. The exact-match semantics and the reference to ssh_file_find_lines_with_pattern distinguish it from replace/delete siblings. An agent can tell what it does without opening the schema.

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

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

Gives a concrete prerequisite ('Use ssh_file_find_lines_with_pattern first if you're not sure the line is unique') and implicitly contrasts with replace-by-pattern tools. However, it does not state when to prefer this over, say, ssh_file_write or ssh_file_replace_line for the same edit, so the guidance is strong but not exhaustive.

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 exist, so the description carries the full burden and does so richly: it discloses error semantics (fails cleanly rather than raising), the exact return shape on success/failure, the async handoff (status in_progress with handle_id), the 50s wait cap, and the single-operation concurrency 'busy' constraint. This is far beyond what any structured field provides.

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

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

Front-loaded with the core action and overwrite behavior, then return values, then the async caveat. Every block earns its place, though the description is on the longer side for a move tool and the 'Returns:' block partially overlaps the output schema.

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

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

For a mutation tool with no annotations, the description covers the safety-relevant behaviors (overwrite risk, clean failure, permission errors), the async lifecycle, and the concurrency limit. An agent has everything needed to invoke and follow up correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it explains that `overwrite` defaults to False and that True maps to `mv -f`/`Move-Item -Force`, and clarifies the move-vs-rename semantics tied to `source`/`destination`. `use_sudo` is left to the schema, keeping it from a 5.

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

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

States specific verbs (move/rename) and resource (file or directory), and clarifies it handles both by inspecting `source`. An agent can immediately distinguish it from ssh_file_copy and ssh_dir_copy without opening schemas.

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

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

Gives clear conditions for the overwrite semantics and source-not-found behavior, and routes the agent to ssh_cmd_check_status for long-running cases while warning 'do not call it again meanwhile'. It doesn't explicitly contrast with ssh_file_copy for the copy-vs-move decision, so it stops short of a 5.

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

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

No annotations are present, so the description carries full behavioral burden and meets it: it discloses the return shape, client-side decoding, the server wait cap (~50s), the in_progress/handle_id fallback, the required polling via ssh_cmd_check_status, and the single-concurrency 'busy' failure mode. This is unusually rich operational 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?

Well front-loaded: purpose, then differentiation, then returns, then long-running behavior. Slightly padded by the bullet list where several points (Unicode, OEM code page, binary-safe, shell escaping) overlap, but nothing is wasted enough to harm selection.

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 an output schema exists, the description need not restate return values, yet it does so briefly and adds the async/polling contract that the schema cannot express. For a read tool with 3 params, all decidable information is present.

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

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

Schema description coverage is 100%, so encoding, max_size, and file_path are already documented in the schema. The description adds only marginal meaning (client-side decode semantics for encoding), which the schema already covers via defaults. 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?

States a specific verb and resource ('Read file contents directly via SFTP') and immediately frames the mechanism (SFTP byte-level read with client-side decoding). It distinguishes itself from sibling ssh_cmd_run by naming that alternative explicitly.

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

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

Provides an explicit when-to-use section ('Why use this instead of ssh_cmd_run with cat/Get-Content?') with concrete selection criteria: Unicode correctness across platforms, Windows code page issues, binary safety, shell escaping. The agent can route correctly without inference.

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

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

With no annotations, the description carries the full burden and does so: exact/literal matching semantics, whitespace trimming, failure mode returns a {'success': False, 'error': ...} dict rather than raising, sudo read behavior, the deprecation of force, and the long-running/in_progress handle + polling + single-concurrency 'busy' contract.

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

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

Front-loaded with the core contract and well-sectioned (params, returns, examples), but the force explanation is stated twice (parameter list and schema-adjacent text) and the long-running paragraph is dense. Minor redundancy keeps it from a 5.

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

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

For a mutation tool with no annotations, the definition covers match semantics, failure behavior, sudo/auth implications, an example, sibling routing, and the async in_progress flow. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so 3 is the baseline, but the description adds real meaning beyond it: match_line is whitespace-trimmed literal text (not a regex), and force is a compatibility no-op whose semantics have moved to use_sudo. That extra nuance justifies 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?

States a precise verb+resource (replace one line in a file) and immediately distinguishes itself from the multi-line and delete-line siblings by name. An agent can route correctly without opening any schema.

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

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

Gives explicit preconditions (match_line must match exactly one line; use ssh_file_find_lines_with_pattern first if uniqueness is uncertain) and names the alternatives for other cases (ssh_file_delete_line_by_content, ssh_file_replace_line_multi). Nothing is left to inference.

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

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

No annotations exist, so the description carries the full burden and does: it discloses the uniqueness-match failure mode, that failures return {'success': False, 'error'} rather than raising, the exact success return shape, and the long-running/in_progress handle polling and single-operation 'busy' constraint.

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

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

Front-loads purpose, then constraints, returns, and examples in a scannable order; every section earns its place. Minor redundancy between the description's force/use_sudo note and the schema's own parameter descriptions, which is the only thing keeping it from a 5.

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

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

For a mutation tool with no annotations, everything an agent needs is present: matching semantics, failure behavior, return shape, sudo/force implications, async fallback, and worked examples. Nothing required for correct invocation is missing.

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

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

Goes well beyond the schema by pinning down semantics: match_line is whitespace-trimmed literal text, not a pattern, and must match exactly one line; new_lines encodes delete ([]) vs blank line ([""]); force is deprecated. These distinctions are not derivable from the schema alone.

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

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

States a specific verb+resource ('Replace a line in a file with one or more new lines') and explicitly differentiates itself from ssh_file_replace_line and ssh_file_delete_line_by_content. An agent can distinguish it from the sibling line-editing tools without opening any schema.

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

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

Explicitly states when to use this over ssh_file_replace_line ('when you need to insert more than one line, or delete a line'), and routes to ssh_file_find_lines_with_pattern when uniqueness is unverified. Both the alternative and the selecting condition are named.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses cross-platform caveats (Windows mode/uid/gid are not real ACLs and shouldn't be reasoned about), the exists=True/False/None semantics with error strings, the fact that a missing path is a normal non-exceptional return, and the long-running wait cap with the busy constraint and polling target.

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?

Length is substantial but largely earned by the platform caveats, error tri-state, and long-running protocol, and it is front-loaded with the core purpose. The Windows attribute paragraph is arguably over-detailed relative to its decision value, keeping it just short of a 5.

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

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

Even though an output schema exists and would relieve the description of explaining return values, the description goes further by covering the non-obvious error tri-state, timestamp format, platform caveats, and the async handle flow. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100% for the single path parameter, so the schema already documents it. The description adds no syntax, format, or path-resolution detail beyond 'file or directory path', so the baseline 3 applies.

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

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

States a specific verb+resource ('Get status information about a file or directory') and pins down the mechanism ('via SFTP stat'), which differentiates it from shell-based siblings like ssh_cmd_run. An agent knows exactly what it retrieves without opening the schema.

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

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

The description implies its purpose but never states when to prefer this over adjacent siblings (e.g. ssh_dir_list_advanced, ssh_file_read, ssh_dir_calc_size). It does give one actionable routing instruction - poll ssh_cmd_check_status on in_progress and don't re-call - but no when/when-not guidance for the core stat operation itself.

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 and does so well: it discloses the sudo /tmp staging mechanism and its OS restriction, that Windows raises rather than attempting Unix commands, that failures raise exceptions instead of returning success:False, the exact success response shape, and the async long-running protocol (50s cap, handle_id, poll via ssh_cmd_check_status, don't re-invoke, single-concurrency 'busy' error).

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

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

Front-loaded with the core action and the routing rules before the caveats, and uses a Returns block plus a long-running paragraph to organize secondary detail. Every sentence earns its place, though the sudo caveat and async paragraph make it longer than typical for a 4-param 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?

Despite an output schema existing, the description adds return-shape and exception semantics plus the async polling contract, which the output schema alone would not convey. Nothing needed to call this tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: local_path/remote_path must be file paths and not directories, and use_sudo=True is explained behaviorally (staged through /tmp with mv/chmod/rm, Windows raises). It doesn't restate the direction enum, but the constraints it adds are substantive.

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

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

States a specific verb+resource+transport: transfer a single FILE via SFTP between the local machine and remote host. It explicitly differentiates itself from two named siblings (ssh_dir_transfer for directories, ssh_file_copy for remote-to-remote), so an agent can route correctly without opening any schema.

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

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

Gives explicit when-to-use rules with named alternatives and their selecting conditions: directories -> ssh_dir_transfer, remote-to-remote -> ssh_file_copy. The sudo caveat further scopes usage (Linux/macOS only; Windows raises immediately).

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 delivers: mode is applied via chmod and silently ignored on Windows, failures return an object rather than raising, and long-running calls return an in_progress handle requiring polling. It even warns about the one-operation-at-a-time busy constraint.

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

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

Front-loads the core action, then layers platform caveats, return shape, and async behavior in a logical order. The Returns block is long but each line carries real signal; minor overhead remains.

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

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

For a 6-parameter mutation tool with no annotations, the description covers the mutation semantics, platform caveats, failure mode, and async handling. Complete enough that an agent can call and interpret it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: append=True on a nonexistent file just creates it, and mode only takes effect on Linux/macOS. use_sudo is left to its schema description, which is adequate.

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

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

States a specific verb and resource ('create a new file, or overwrite/append to an existing one') with clear scope, distinguishing it from read/replace-line siblings. The append-vs-overwrite semantics are spelled out so an agent knows exactly what calling it does.

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

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

Gives useful operational guidance for the async case (poll ssh_cmd_check_status, don't re-call, busy error). But it never says when to choose this tool over siblings like ssh_file_transfer, ssh_file_replace_line, or ssh_file_copy. Usage is implied through behavior rather than an explicit selection rule.

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

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

With no annotations present, the description carries the full burden and does so well: it discloses the long-running/wait-cap behavior, the in_progress + handle_id return shape, the polling tool ssh_cmd_check_status, the 'do not call again' rule, and the single-concurrency 'busy' failure mode. The only gap is the no-connection/no-op or error behavior, which 'if one exists' hints at but never states.

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

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

Front-loads the purpose, then usage, then return, then the async caveat in clearly labeled blocks. Every block earns its place, though the long-running boilerplate is somewhat template-heavy for a zero-argument disconnect call.

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

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

An output schema exists so the return values need not be spelled out, yet the description still notes the disconnection-status dictionary plus the async envelope. Usage, concurrency, and recovery path are all covered; only the no-op/error case when no connection exists is left implicit.

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

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

The tool takes zero parameters (empty object schema, additionalProperties false), so there is nothing for the description to clarify. Baseline of 4 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?

Specific verb (Disconnect) plus resource (the current SSH connection) with the scope qualifier 'if one exists'. It is trivially distinguishable from sibling connectors such as ssh_conn_connect, ssh_conn_is_connected, and ssh_conn_status without opening any schema.

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

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

Gives explicit when-to-use conditions: before connecting to a different host, or when finished with SSH operations. It does not name a when-not case or an alternative tool (e.g. that simply letting the session lapse is an option), so it falls short of a full 5.

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

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

With no annotations, the description carries the full burden and does so: it discloses that secrets (passwords, sudo passwords, passphrases) are deliberately omitted, that output depends on which config file is active, and that config_path reflects that state. This is exactly the safety/state context annotations would otherwise supply.

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

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

Front-loaded with the core purpose and return fields, and the security rationale is well placed. It is slightly repetitive, restating the 'don't open the file' admonition three times, and the return-value block duplicates the output schema.

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

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

For a zero-parameter list tool with no annotations, the description covers purpose, safety posture, state dependency, and return contents; an agent has everything needed to call it correctly without opening the config file.

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 input parameters, so the baseline is 4; the description correctly does not invent parameter semantics and instead documents the returned shape.

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

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

States a precise verb+resource ('List all configured SSH hosts') and enumerates the returned fields (key, alias, description). It is immediately distinguishable from sibling mutation tools like ssh_host_update and ssh_host_remove.

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 names the alternative paths: use ssh_conn_add_host/ssh_host_update/ssh_host_remove to modify hosts, and never read the TOML file. It also explains the config-file switching behavior tied to ssh_host_use_config, giving full when/when-not guidance.

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