zspace-cli

by skyzhao1223

Overview Schema Source Related Servers Discussions Admin

Python

Local

Storage profile by pool, user and category

zspace_usage

Read-only

Report where physical disk space actually goes on the ZSpace NAS.

Instructions

Report where physical disk space actually goes on the ZSpace NAS.

Use this FIRST for any "is my NAS full?" or "what is using my space?" question. It is the only view that includes Time Machine backups, other users' spaces, the safe box, Docker, RAID metadata and the recycle bins -- every one of those is outside //my/data and returns N001411 to file listing, so walking the file tree systematically under-reports pool usage (measured: a full 57-minute walk of 2.69M files accounted for only 4.84 TiB of a 7.97 TiB pool).

Returns per pool: total/used/free bytes, used_pct, and entries of {kind, owner, label, label_cn, bytes} sorted largest first, where label is one of my / my_tm (Time Machine) / my_recycle / my_safe / sys_docker / sys_raid / sys_vm / sys_iscsi / sys_other. Read-only.

The my_recycle entry is the recycle bin's physical footprint, so this is the cheap way to see how much space deleted-but-not-purged data is holding before deciding whether to list or empty it. Also note these are physical sizes: my includes the second copy of every double-backed-up folder, whereas a file-level walk (zspace_du) reports logical sizes. The walk therefore comes out lower by exactly the mirrored bytes -- measured on one pool as 4.838 TiB walked vs 6.008 TiB reported here, the 1.17 TiB gap being the double-written folder. Neither number is wrong; they measure different things.

If you compare these figures against a scan run on an SMB mount, expect a mismatch: the mount exposes "@Recycle" and other directories the file API cannot see, and a mount-side scan that fails to skip "@Recycle" counts recycled data as live. That inflates totals silently rather than erroring.

For the size of one specific directory use zspace_du instead; for per-disk health use zspace_disks.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`refresh`	No	Ask the NAS to recompute the snapshot first (slower)

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.6/5.0

Behavior5/5

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

Annotations only declare readOnlyHint and openWorldHint, but the description adds substantial behavioral context: the exact categories included, that they return N001411 to file listing, that figures are physical (not logical) sizes including mirrored second copies, and that SMB-mount scans can silently mismatch due to '@Recycle'. This is far beyond what annotations convey.

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 and the routing rule, and every paragraph targets a real decision (walk under-reporting, physical vs logical, SMB mismatch). It is somewhat verbose with repeated measured figures, but the density of decision-relevant information mostly justifies the length.

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?

Given an output schema exists, return-value explanation is optional, yet the description still sketches the per-pool return shape and label taxonomy. Combined with the documented pitfalls (physical vs logical sizing, SMB mismatch, recycle footprint), it is complete for correct invocation and interpretation.

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 description coverage is 100% and there is a single optional `refresh` parameter documented in the schema; the description adds no additional parameter detail. Baseline 3 applies since the schema fully carries parameter meaning.

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+resource: reporting where physical disk space goes on the ZSpace NAS, broken down per pool/user/category. It explicitly distinguishes itself from siblings by naming zspace_du (single-directory size) and zspace_disks (per-disk health) as different tools for different questions.

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 an explicit routing rule ('Use this FIRST for any "is my NAS full?" or "what is using my space?" question') and names alternatives for adjacent questions (zspace_du for one directory, zspace_disks for disk health). It also tells the agent when this view is the only one that sees certain categories.

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