zspace-cli

by skyzhao1223

Overview Schema Source Related Servers Discussions Admin

Python

Local

List recycle bin contents

zspace_recycle_list

Read-only

List what is currently in a recycle bin, including each item's original location.

Instructions

List what is currently in a recycle bin, including each item's original location.

Always call this before zspace_recycle_empty -- emptying purges every item in the bin, including files deleted earlier by other means, and is irreversible. The personal and public bins are separate stores; files deleted from //my/data land in the personal one.

The listing triggers a server-side scan and this call waits for it to settle, so an in-progress scan is not mistaken for an empty bin. Returns {bin, total, items: [{name, path, original_path, is_dir, bytes}]}. The path is the in-bin location and is what zspace_recycle_restore and zspace_recycle_purge need. Read-only.

Naming: this tool reaches the bin through the API, where it is "/.recycle/my". The same bin is visible on an SMB mount as a directory called "@Recycle" at the share root (plus a ".zspace_trash" variant), which is outside //my/data and therefore not readable through the file API at all. If you are also running scripts against a mounted path -- the skills/ scanners do exactly that -- they must skip "@Recycle", or recycled files get counted as live data. That miscount raises no error, it just quietly inflates totals; it survived in 8 of the 9 scanners before being caught. Do not try to list "@Recycle" through this API to cross-check: it returns N001411 for every path outside my/data whether or not it exists, so that response tells you nothing.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum items to return
`public`	No	True for the shared/family bin, False for the personal one

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 give readOnlyHint/openWorldHint, but the description adds substantial non-obvious behavior: the listing triggers a server-side scan that the call waits to settle (so an in-progress scan isn't misread as empty), personal and public bins are separate stores, and the read path is '/.recycle/my' via API versus '@Recycle'/'.zspace_trash' on SMB. The 'Read-only' statement agrees with readOnlyHint, so no contradiction.

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

Conciseness3/5

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

Content is front-loaded with purpose and the critical ordering rule, and headings help scanning. However it runs long for a two-parameter list tool, with an extended aside about scanner miscounts ('survived in 8 of the 9 scanners') and the N001411 error that, while genuinely useful, is disproportionate detail. Several sentences could be compressed without losing decision-relevant information.

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?

The tool is fully covered: annotations carry the read-only/open-world profile, an output schema exists so the inline return shape is a bonus rather than a necessity, and the description supplies the operational hazards (irreversibility, scan settling, SMB/API path split, misleading error code) an agent needs to call it correctly.

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

Parameters5/5

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

Schema coverage is 100% so the baseline is 3, but the description adds real semantic content about the `public` parameter: the personal and public bins are separate stores with different deletion origins ('/<pool>/my/data' lands in the personal one). It also ties the returned `path` field to the parameters of downstream tools, which the schema does not convey.

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?

The opening sentence gives a specific verb and resource (list recycle bin contents) plus the distinguishing payload detail (each item's original location). It is immediately separable from the sibling mutation tools zspace_recycle_restore, zspace_recycle_purge and zspace_recycle_empty by describing itself as the read-side listing.

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?

It states an explicit ordering rule with rationale: 'Always call this before zspace_recycle_empty', explaining that emptying is irreversible and purges items deleted by other means. It also names the sibling tools that consume the returned `path` (restore/purge) and warns against using this API to cross-check the SMB '@Recycle' view. Nothing about when to reach for this tool is left to inference.

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