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 disclose a meaningful constraint: paths must sit inside downloadRoots/localRoots when the host defines them. However, it is silent on the overwrite default of true (which can clobber local files), on directory recursion behavior, and on auth/permission needs, leaving real behavioral gaps for a tool that writes to the local filesystem.

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

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

Three front-loaded sentences: action first, then use case, then the constraint. Every sentence carries weight, though the run-on feel of the final sentence slightly blurs the structure.

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

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

An output schema exists, so return values need no explanation. Against 0% schema coverage and no annotations, the description covers purpose, use case, and path constraints but omits the overwrite clobber risk and directory-handling behavior an agent would want before invoking.

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

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

Schema description coverage is 0%, so the description must compensate. It adds genuine meaning for remotePath and localPath (plain paths, path-root containment) that the schema lacks entirely, but says nothing about host or the consequential overwrite flag, leaving half the parameters undocumented.

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

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

States a specific verb (Download), resource (remote file or directory), destination (local machine), and transport (SFTP). The direction is unmistakable and cleanly separates it from the sftp_upload sibling, which pulls/pushes in the opposite direction.

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?

'Use to pull logs, config or artifacts for offline analysis' gives a concrete usage scenario and intent. It stops short of explicitly naming when NOT to use it or pointing at alternatives like sftp_list, so it is clear context without routing 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. It usefully discloses the two operating modes (directory listing vs single-file stat), but says nothing about authentication expectations, error behavior on missing paths, or that the operation is non-mutating.

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

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

Two tight sentences: the core behavior is front-loaded, followed immediately by practical use cases. No filler, no redundancy.

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

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

An output schema exists, so return-value explanation is unnecessary. However, with zero annotation coverage and zero schema description coverage, the undocumented 'all' parameter and absent behavioral cues (read-only nature, error handling) leave real gaps for a 3-parameter tool.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It hints at path semantics via 'directory' vs 'single remote file', but adds nothing about remotePath's default of '/', and the 'all' parameter (presumably hidden-file inclusion) is unexplained in both schema and description.

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

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

States concrete verbs (list, stat) and resources (remote directory, single remote file), so the dual-mode behavior is immediately clear. It doesn't name which siblings to prefer over it, though the reference to finding files 'before downloading them' implicitly points at sftp_download.

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

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

Gives three concrete when-to-use scenarios: verifying a deployment landed, inspecting permissions, and locating log files prior to download. No explicit when-not or named alternatives, but the context is clear enough to guide selection.

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

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

With no annotations, the description carries the full burden and does disclose a genuine behavioral constraint (the uploadRoots containment rule) plus remotePath absoluteness. However it is silent on the default overwrite=true semantics, i.e. that existing remote files are replaced by default, and says nothing about permissions/mode behavior or authentication needs.

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?

Four short sentences, front-loaded with what the tool does and why you would reach for it, and no filler. The path-constraint sentences are dense but each carries a distinct rule.

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

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

An output schema exists, so return values need no explanation. But for an unannotated mutation tool with 5 parameters, the description omits the destructive-by-default overwrite behavior and the meaning of mode, leaving an agent without enough to call it safely in all cases.

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

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

Schema description coverage is 0% across 5 parameters, so the description must compensate. It meaningfully explains remotePath (must be absolute, must sit under uploadRoots) and localPath (any readable local path), but leaves mode and overwrite completely undefined — overwrite being the most consequential omission since it defaults to true.

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 (upload) and resource (local file or directory to a remote host over SFTP), which is unambiguous on its own. It does not explicitly contrast itself with the mirror-image sibling sftp_download, so an agent must infer the direction distinction rather than being told.

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?

"Use to ship code, config or binaries before running deploy commands" gives a concrete usage context and even implies ordering relative to the ssh_run deploy siblings. It stops short of naming when-not-to-use or explicitly pointing at sftp_download for the reverse direction.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses what is and is not returned (aliases and descriptions, never addresses or credentials), which is security-relevant transparency. It stops short of covering auth requirements, failure modes, or rate 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?

Three short sentences, front-loaded with purpose and followed by usage and return-scope. Every sentence carries distinct information; nothing is redundant padding.

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

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

An output schema exists, so return-value detail need not be explained here, and there are no parameters to document. The description supplies the discovery/ordering context an agent needs to place this tool correctly in the ssh workflow.

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

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

Zero parameters, so the baseline is 4 per the rubric. The only parameter-like semantics introduced is that returned values are valid aliases usable with other tools, which is helpful framing but does not change the baseline.

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

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

The description states a specific verb and resource ('List the remote hosts reachable through this server') and immediately scopes it against siblings by clarifying that only aliases and descriptions are returned, not addresses or credentials. An agent can distinguish this discovery tool from ssh_probe, ssh_run, and sftp_list 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?

It gives explicit ordering guidance ('Call this first whenever you need to touch a remote machine') and states the goal of that call (learning valid aliases and permissions). It does not name specific alternatives or state when-not to use it, so it falls just short of the 5-level criteria.

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

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

With no annotations, the description carries the full burden, and it does disclose the runtime behavior — it probes the host and returns identity fields plus latency, and it is positioned as a non-mutating check to run before real commands. It does not mention auth requirements, timeout behavior, or whether the probe leaves any trace on the host, so it is good but not complete.

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

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

Two sentences, front-loaded with the action and followed by the usage trigger, with no filler. The parenthetical return list is slightly dense but earns its place by previewing the diagnostic payload.

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

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

An output schema exists, so return values need no further explanation, and a one-parameter diagnostic tool has limited surface to cover. The description addresses purpose, usage trigger, and runtime behavior; the only real gap is host-parameter format guidance.

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

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

Schema description coverage is 0% and the single required parameter 'host' has no documentation anywhere. The description never clarifies the expected format (hostname, IP, user@host, or ssh-config alias), which is exactly the ambiguity that matters for a connectivity tool with a low-coverage schema.

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

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

The description names a specific operation (test connectivity), its target (a host), and exactly what it returns (uname, uptime, id, round-trip latency). It also implicitly separates itself from the sibling ssh_run by framing itself as a pre-flight diagnostic, so an agent can pick it out of the ssh_* family 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?

It gives clear context: 'Use to diagnose cannot connect problems before running real commands,' which routes the agent to use this before ssh_run/ssh_run_many. It lacks an explicit when-not-to-use statement or naming of the sibling tools, so it falls short of a 5.

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

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

With no annotations provided, the description carries the full burden and largely succeeds: it discloses the return shape, the background/daemonizing behavior, and the policy-refusal model ('a refusal names the rule that blocked it'). It does not explain timeout behavior, cwd semantics, or whether commands are run as a privileged user, leaving a few operational unknowns for a mutation-capable tool.

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

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

Four dense sentences, front-loaded with purpose then immediately branching into read vs. write usage, sequencing advice, the background flag, and the policy caveat. No filler and every sentence carries actionable 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?

An output schema exists so return values need not be spelled out, and the description still adds policy-refusal and background context. However, for a tool that can mutate remote state, the absence of any note on timeout defaults, cwd resolution, or privilege level leaves small but real gaps.

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

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

Schema coverage is 0%, so the description must compensate, and it only partially does: it explains background=true and ties host to per-host allowCommands/denyCommands rules. cwd, timeout, and the format/escaping of command are undocumented in both schema and description, so roughly half the parameters remain unexplained.

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

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

The description opens with a specific verb+resource ('Execute a shell command on a remote host') and even states the return payload (stdout, stderr, exit code). It implicitly separates itself from ssh_run_many by emphasizing 'one command per call', and the policy/allowCommands note ties it to the ssh_run policy siblings.

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

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

Explicit when-to-use is given for both read ('inspecting state: logs, processes, ports, containers, service status') and write ('deploy, restart, edit') scenarios, plus sequencing guidance ('chain with &&') and a concrete rule for background=true. The only gap is that it never names ssh_run_many as the multi-host alternative, but it does constrain its own scope clearly.

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 meaningful work: it discloses that each host applies its own allowCommands/denyCommands policy, that one host may be refused while others run, and that per-host status is reported rather than failing the whole call. Missing are auth requirements, parallelism/concurrency limits, and the interaction between timeout and stop_on_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?

Three sentences, front-loaded with the core action, then usage examples, then the key behavioral caveat. No filler and every sentence carries 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?

An output schema exists, so return values need not be explained, and the description still adds the useful 'one result per host' framing. For a 4-parameter fan-out tool with no annotations, the omission of timeout semantics and any auth/parallelism notes keeps it from being fully 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 0%, so the description must compensate for four undocumented parameters. It clarifies that 'hosts' is a multi-host fan-out and 'command' is identical across hosts, and it implicitly characterizes the default stop_on_error=false behavior ('per-host status is reported rather than failing the whole call'). However, 'timeout' is entirely unaddressed and stop_on_error is only implied, leaving real gaps.

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

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

States a specific verb and resource ('Run the same command across several hosts in parallel') plus the output shape ('one result per host'), which cleanly distinguishes it from the single-host ssh_run sibling. An agent can pick this over ssh_run 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 four concrete usage scenarios (compare versions, fleet-wide service check, restart several boxes, survey disk usage) that map well to when this tool is appropriate. It stops short of naming alternatives or stating when not to use it (e.g. single host → ssh_run), so it is clear context without explicit exclusions.

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

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

No annotations are provided, so the description carries the full behavioral burden — and it does disclose the critical trait that nothing is executed (no side effects), plus that the matched rule is returned. It omits auth/permission prerequisites and whether the check is bound to the active session/credentials, which is the main remaining gap.

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

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

Three short sentences, zero filler. The most important fact (no execution) is front-loaded in the first sentence, and the additional return/usage notes follow in priority order.

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

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

An output schema exists, so return values need no explanation, and the description covers the key dry-run semantics plus when to call it. Missing only permission/session prerequisites, which would matter for a policy-evaluation tool.

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

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

Schema description coverage is 0% for two required params, so the description must compensate — but 'host' and 'command' are only mentioned obliquely ('a command on a host') with no format, naming convention, or syntax guidance. An agent has to guess how hosts are addressed and whether multi-command strings are allowed.

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 (check/would be allowed) and resource (a command on a host), and the all-caps 'WITHOUT running it' immediately separates it from what a naive reader would assume ssh_run does. An agent can distinguish this dry-run/authorization check from ssh_run 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 two concrete triggering situations: before a risky/unfamiliar command, or to diagnose a prior refusal. It does not explicitly name ssh_run as the alternative being gated, so routing is implied by the description rather than stated as a rule.

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