Upload local file to NAS

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

Annotations only provide openWorldHint, so the description carries the behavioral burden. It explicitly warns that this mutates NAS state and that a same-named file is overwritten, and it discloses the >64 MB sliced protocol triggered by HTTP 413. These are exactly the hidden behaviors an agent needs before invoking the tool.

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

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

The description is compact and front-loaded with the main purpose, then organized into related notes about parameters, large files, and related tools. It is slightly longer than strictly necessary, but every sentence contributes operational information rather than filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutating upload tool with only an openWorldHint annotation, the description covers prerequisites, overwrite semantics, size limits, the underlying HTTP 413 reason, related sibling operations, and the return value. Nothing critical is left for the agent to guess.

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

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

The input schema already describes all three parameters at 100% coverage, so the baseline is 3. The description adds meaning beyond the schema by stating that remote_dir must already exist, that new_name renames the file on arrival, and that local_path is the source of the upload.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise verb and resource: 'Upload a file from the local machine to a directory on the ZSpace NAS.' It also distinguishes itself from siblings by calling itself 'the inverse of zspace_download' and linking remote_dir creation to zspace_mkdir, so an agent can disambiguate it from the other zspace_* tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

It states when to use it ('push media or documents to the NAS'), gives an explicit prerequisite (remote_dir must exist and can be created with zspace_mkdir), names the alternative direction via zspace_download, and advises checking zspace_pool_info for free space before large uploads. This is concrete routing guidance, not just a restatement.

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