zspace-cli

by skyzhao1223

Overview Schema Source Related Servers Discussions Admin

Python

Local

Directory size and file count

zspace_du

Read-only

Get the size, file count and directory count of one NAS directory.

Instructions

Get the size, file count and directory count of one NAS directory.

Returns {path, bytes, files, dirs, state, complete, source, categories}.

Always check complete before reporting the numbers. The server-side statistic is instant and exact for small-to-medium trees, but on large ones the NAS returns state="running" with a partial snapshot that never converges -- measured on a 1.175 TiB / 448k-file folder, fourteen consecutive calls all reported ~0.35 TiB with the file count jittering between 27k and 30k. There is no poll endpoint that works, so when complete is false either pass walk=true or tell the user the figure is a lower bound. Never present a partial number as the answer.

walk=true traverses via /v2/file/list at roughly one request per directory; a 448k-file tree needs ~93k requests and ~12 minutes. Read-only.

Do not cross-check this against a du run on an SMB mount and assume one of them is broken. The mount exposes directories the file API cannot see at all -- notably "@Recycle", the same recycle bin that zspace_recycle_list reads as "/.recycle/my" -- so a mount-side count includes recycled data this tool correctly excludes. Mount-side scans must skip "@Recycle" (and ".zspace_trash"); counting it inflates totals without raising any error.

For whole-pool accounting use zspace_usage; to list individual large files use zspace_bigfiles.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`path`	Yes	Absolute directory path, e.g. /sata11/my/data/影视
`walk`	No	Force an exact client-side traversal (slow, but the only reliable option for very large trees)

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.1.13Oct 14, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only declare readOnlyHint and openWorldHint; the description goes well beyond by disclosing the non-converging partial-snapshot failure mode on large trees, with a concrete measured example (1.175 TiB / 448k files, ~0.35 TiB reported over fourteen calls), the absence of a working poll endpoint, and the cost of the exact path (~93k requests, ~12 minutes for 448k files). This is exactly the behavioral context annotations cannot carry.

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 purpose, then the critical `complete` caveat and the walk trade-off, before the file-API/NAS gotchas. Every paragraph carries actionable information, though the @Recycle cross-check warning and the repeated 'never present a partial number' admonitions make it longer than strictly necessary.

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?

An output schema exists, yet the description still supplies the one field an agent must interpret (`complete`) along with the returned key set. Combined with the cost model, failure mode, and alternative-tool routing, nothing needed to call this correctly on either a small or a very large tree is missing.

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

Parameters4/5

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 semantics for `walk`: it explains the underlying /v2/file/list mechanism, the request-per-directory ratio, and a realistic runtime. That substantially extends the schema's terse 'slow, but the only reliable option' note. The `path` parameter gets no added meaning, keeping it short of a 5.

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 -- 'Get the size, file count and directory count of one NAS directory' -- and immediately differentiates from siblings by naming zspace_usage for whole-pool accounting and zspace_bigfiles for individual large files. An agent can distinguish it from zspace_ls, zspace_tree and the other listing tools 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.

Usage Guidelines5/5

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

Explicit when/when-not guidance: always check `complete` first, pass walk=true or report a lower bound when complete is false, never present a partial number as the answer. It also routes to the correct alternatives (zspace_usage, zspace_bigfiles) and warns against a specific misuse (cross-checking against an SMB du run).

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