cygnus-ssh-mcp

Official

Overview Schema Source Related Servers Discussions Admin

ssh_dir_calc_size

Calculate the total size of a remote directory recursively over SSH by summing regular file sizes, returning bytes and human-readable units.

Instructions

Calculate the total size of a directory recursively: the sum of the sizes of all regular files under it (directories' own sizes are not counted - same on every platform).

On a 'linux' connection whose find lacks -printf (check ssh_conn_connect/ ssh_conn_host_info's capabilities), this raises a clear error instead of running. Fallback: ssh_cmd_run("du -sk <path>") - kilobytes, and it includes directory overhead, but works on most BusyBox builds.

Returns: {'path', 'size_bytes' (int), 'size_human' (e.g. "1.23 MB", "512.00 KB", "3.50 GB" - 2 decimal places, binary/1024-based units)}.

Long-running calls: if this takes longer than the server's wait cap (default 50s), it
returns {"status": "in_progress", "handle_id": ...} instead of the result - the work keeps
running. Get the result by polling ssh_cmd_check_status(handle_id=...), which returns this
tool's normal response once finished. Do not call it again meanwhile. Only one such
operation runs at a time; another one started meanwhile fails with a 'busy' error.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`path`	Yes	Directory path to calculate size for

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.3.0May 28, 2026

TDQS

A4.4/5.0

Behavior5/5

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.

Conciseness4/5

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.

Completeness5/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

Deploy Server