Move files or directories

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

Annotations only include openWorldHint: true, which is minimal. The description carries the burden and discloses key behaviors: it mutates NAS state, removes sources from original location, requires destination to exist (with a pointer to zspace_mkdir), and returns a specific structure. It does not detail error cases or permission requirements, but the main side effects are well covered.

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 three concise paragraphs: a one-sentence definition, a usage paragraph with input format, precondition, return, and mutation warning, and a decision paragraph. It is front-loaded with the core purpose and avoids redundancy. Every sentence adds value.

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?

Given the tool's complexity (accepts single or list, has preconditions, mutates state) and the presence of an output schema, the description covers the essential aspects: purpose, usage, input flexibility, precondition, return structure, and differentiation from siblings. Minor gaps like error handling or permission requirements exist, but overall it is sufficiently complete for an agent to invoke correctly.

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?

Schema coverage is 100%, so the parameters are already documented. The description adds semantic value by clarifying that 'paths' can be a single path or a list, and that 'to' must be an existing directory (with a creation hint). This goes beyond the raw schema descriptions, enriching the agent's understanding of parameter usage.

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 clearly states a specific verb and resource: 'Move one or more files/directories on the NAS into a destination folder.' It also distinguishes itself from copy and rename by explicitly mentioning those alternatives, so an agent can immediately tell what this tool does and what it is not.

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?

The description gives explicit usage context: 'Use to reorganize files, e.g. sort media into per-genre folders.' It further provides decision rules: 'Choose move vs copy by whether the originals should survive' and 'To change only the name within the same directory, use zspace_rename instead.' This fully guides when to use this tool versus alternatives.

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