Skip to main content
Glama
cygnussystems

cygnus-ssh-mcp

Official
by cygnussystems
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

ssh_dir_list_files_basic

List immediate filenames in a remote directory via SFTP without recursion or metadata. Use when you need only entry names, not sizes, permissions, or file types.

Instructions

List the immediate contents of a directory (via SFTP - not recursive, no metadata). For recursive listing with size/permissions/type/etc., or to filter by filename pattern, use ssh_dir_list_advanced or ssh_dir_search_glob instead.

Returns: List of bare filenames (strings) directly inside path - not full paths, not recursive, and no indication of which entries are files vs. directories (use ssh_file_stat on an entry, or ssh_dir_list_advanced, if you need that).

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
NameRequiredDescriptionDefault
pathYesDirectory path to list

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv1.6.1
    • addedOutput schema / properties / result / anyOf
      Added value: +[
+  {
+    "items": {},
+    "type": "array"
+  },
+  {
+    "additionalProperties": true,
+    "type": "object"
+  }
+]
    • removedOutput schema / properties / result / items
      Removed value: -{}
    • removedOutput schema / properties / result / type
      Removed value: -"array"
  2. First observedv1.3.0

TDQS

A4.7/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 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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

Deploy Server

Other Tools