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

Annotations cover only readOnly/openWorld, but the description discloses operational traits the agent could not otherwise know: a single shared task slot that clears stale tasks, interference between concurrent scans, and that `complete` may be false with partial results on timeout. It also quantifies the server-side speed advantage over client-side walking.

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?

Front-loads purpose and use case, then layers caveats and alternatives. Every sentence carries distinct information — performance rationale, concurrency warning, completeness check — with no restatement of the schema.

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?

Despite a return shape being restated (redundant given the output schema exists), the definition covers everything an agent needs: purpose, alternatives, concurrency hazard, partial-result signal, and safety profile. Nothing material is missing.

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 description coverage is 100%, so `top`, `paths`, and `min_size_mib` are already documented in the schema; the description adds only the ordering guarantee ('biggest first') which is not a parameter property. Baseline 3 is appropriate when the schema carries parameter meaning.

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?

States a specific verb and resource with ordering semantics: 'List the largest files under the given directories, biggest first.' It also explicitly differentiates itself from zspace_du and zspace_usage, so an agent can route without opening any schema.

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?

Gives a concrete use case ('find cleanup candidates') and names the two alternatives with the condition that selects each: zspace_du for a directory's total size, zspace_usage for pool-level accounting. This is explicit when-to-use and when-not-to-use guidance.

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

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

Annotations already include readOnlyHint and openWorldHint, but the description adds concrete behavioral detail: it reports both connected and disconnected outcomes, states it 'never modifies NAS state,' and specifies the exact proxy endpoint. This goes beyond what annotations alone convey and gives an agent confidence about side effects and result semantics.

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: it opens with the core purpose, then gives usage timing, return format, safety note, and sibling differentiation in a logical order. No sentence is wasted, and the sibling contrast is placed at the end where it is least likely to obscure the primary instruction.

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 zero-parameter connectivity probe with an output schema present, the description is complete. It gives the endpoint, success and failure response shapes, a no-mutation guarantee, and when to call it. There is no missing information an agent would need to invoke the tool 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?

The tool has zero parameters, so the schema fully covers the parameter surface with 100% coverage. The description confirms the fixed target (127.0.0.1:13579) and return shape, which is sufficient; there is no parameter meaning left to explain.

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 states a specific verb and resource — 'check whether the ZSpace NAS is reachable through the local desktop client proxy' — and explicitly differentiates the tool from zspace_pool_info by clarifying this is a connectivity probe with a pool summary. An agent can distinguish it from siblings without opening any schema.

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 when-to-use guidance: 'Call this first to verify the proxy at 127.0.0.1:13579 is online before running other file operations.' It also names the alternative and the condition for choosing it: 'use pool_info when you only need capacity.' This fully covers usage context and exclusions.

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

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

With only openWorldHint in annotations, the description carries the full burden of disclosing side effects. It explicitly states 'Mutates NAS state but leaves the sources untouched', requires the destination to exist, and notes copies consume additional capacity. This goes well beyond what the annotations provide.

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 each sentence serving a distinct purpose: operation, use case, return shape, side effects, and alternative selection. No redundancy or 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?

Given only two clearly documented parameters, existing output schema, and modest annotations, the description is complete enough for an agent to invoke the tool correctly. It covers behavior, prerequisites, return shape, capacity impact, and how to choose between this and zspace_move.

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 baseline is 3. The description adds meaningful extra semantics by clarifying that the destination must already exist and may need to be created with zspace_mkdir, which is not obvious from the schema alone.

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 states a specific verb ('Copy'), a resource ('files/directories on the NAS'), and a target ('destination folder'). It also distinguishes itself from zspace_move explicitly by noting the originals are left untouched.

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?

Provides explicit when-to-use guidance: duplicating media or creating backups. It names the alternative (zspace_move) and gives the selection rule: choose copy when the original must remain, move when it should not. Also directs users to create the destination with zspace_mkdir and check capacity with zspace_pool_info for large trees.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description's 'Read-only' line merely restates that. The valuable additions are the ZDR-pool caveat explaining why disk-level data can contradict pool-level free space, and the power_on_hours interpretation tip about previously used drives, neither of which is derivable from annotations or schema.

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 purpose is front-loaded and the usage guidance follows logically, but the explicit return-shape listing duplicates the output schema that already exists, which is wasted text. The illustrative 476 GiB / 59.8 GiB example is helpful but adds length.

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?

With readOnly/openWorld annotations and a full output schema present, the description needs only to justify when to call the tool and what pitfalls exist. It does both, including the disk-vs-pool free-space trap and sibling routing, so nothing an agent needs is missing.

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 tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. The documented return fields do not function as parameters here.

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 opening sentence names a specific verb ('Report') and resource ('every physical disk') and enumerates exactly what is covered: free space, temperature, health, SMART counters, fragmentation, power-on hours, and empty bay counts. It is clearly separable from siblings like zspace_smart and zspace_usage, which it explicitly names later.

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 gives an explicit trigger ('Use before recommending a drive purchase or when a pool is nearly full') and explains why the tool is needed over the pool-level alternative, with a concrete observed example of a misleading pool report. It also routes the agent to zspace_smart for full SMART attributes and zspace_usage for pool totals.

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

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

Annotations already provide readOnlyHint=true and openWorldHint=true, and the description consistently states "Read-only; never modifies NAS state." It adds helpful context beyond annotations by revealing that the return shape is "whatever the NAS API exposes and is not normalized," which sets expectations about variability. No contradictions.

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 well-organized with the core action first, followed by usage context, read-only note, and sibling differentiation. It is slightly redundant with the annotation ("Read-only; never modifies NAS state") but every sentence otherwise adds value and nothing is extraneous.

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 zero-parameter, read-only diagnostics tool with an output schema present, the description covers all necessary aspects: purpose, usage triggers, read-only guarantee, return shape variability, and distinction from the closest sibling. There are no gaps that would prevent correct selection or invocation.

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 tool has zero parameters and the input schema is empty, so there is nothing for the description to clarify beyond what the schema already reflects. The description appropriately focuses on behavior, not parameters, matching the baseline for a no-parameter tool.

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 states a specific action and resource: "Return raw disk statistics reported by the ZSpace NAS." It clearly differentiates from the sibling zspace_pool_info by noting the raw, unnormalized shape versus normalized pool info, so an agent can distinguish them immediately.

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?

Explicit use cases are given: "Use for diagnostics and health monitoring (I/O, capacity, SMART-style counters as exposed by the NAS API)." It also provides a direct exclusion and alternative: "choose pool_info for 'how much free space', this one for 'is a disk unhealthy'." This leaves no ambiguity about when to use the tool.

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

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

Annotations already declare readOnlyHint=true, but the description adds meaningful behavioral context beyond that: it states the tool does not modify NAS state, overwrites an existing local file of the same name, requires local_dir to exist, and returns a specific shape. This helps the agent predict side effects and retry safety without contradicting annotations.

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 core purpose in the first sentence. There is slight redundancy between 'Does not modify NAS state' and 'Unlike upload this never changes anything on the NAS,' but overall every major point is covered without excessive length.

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?

This is a simple two-parameter tool with an output schema and read-only annotations. The description covers the tool's direction, key constraints, retry safety, local overwrite behavior, and return value. Nothing important is missing for an agent to select and invoke it 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 description coverage is 100%, so the baseline is 3. The description adds value by clarifying that local_dir must already exist, that remote_path is an absolute NAS path, and that an existing local file of the same name will be overwritten. These are behavioral details tied to parameters that are not fully explicit in the schema.

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 states a specific verb and resource: 'Download a file from the ZSpace NAS to a local directory.' It also distinguishes the tool from its siblings by explicitly framing it as 'NAS -> local' and 'the inverse of zspace_upload.' This leaves no ambiguity about what the tool does.

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 provides clear guidance: 'Use to pull media or documents off the NAS.' It also names the relevant alternative zspace_upload and explains the key difference in behavior, including that download never changes NAS state and is safe to retry. This is explicit when/why guidance, not just an implied usage.

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

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.

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.

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.

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.

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.

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.

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

Annotations already declare readOnlyHint=true, and the description reinforces it with 'Read-only' while adding non-redundant constraints: 'the path must already exist' and 'Returns the raw info object'. This goes beyond the annotation to inform error conditions and return format.

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 short paragraphs, each earning its place: purpose, usage, and exclusions. It is front-loaded with the core purpose, and there is zero 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 single-parameter read-only tool with an output schema, the description covers everything an agent needs: when to use, what it returns, the constraint that the path must exist, and how to handle multiple paths. No gaps remain.

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% with a clear description for 'path' including an example. The description adds no additional parameter-level meaning beyond the schema, only the constraint that the path must exist, which is usage guidance rather than parameter semantics. Baseline 3 is appropriate.

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 states a specific verb ('Return') and resource ('detailed metadata for one file or directory on the ZSpace NAS'), and explicitly contrasts with ls by mentioning 'more than the ls summary exposes'. This clearly distinguishes the tool from its siblings.

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 provides explicit when-to-use ('when you need more than the ls summary exposes') and when-not-to-use ('use zspace_ls to enumerate a directory, or zspace_search to locate an item first'), naming the exact alternative tools. No ambiguity.

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

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

Beyond the readOnlyHint annotation, the description discloses automatic pagination (max 50 entries per call), the exact return shape ({name, path, is_dir, size}), and the effect of show_hidden=True. This gives the agent a concrete behavioral model without any contradiction.

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 well-organized: purpose first, then behavior, then alternatives. Every sentence adds value and none merely repeats the title.

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 two-parameter read-only tool with output schema and annotations, the description covers pagination, return shape, option semantics, and sibling routing. Nothing needed for correct invocation is missing.

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 schema already documents both parameters with defaults and descriptions, so schema coverage is 100%. The description restates the path and show_hidden behavior but adds no substantial meaning beyond the schema, which fits the baseline of 3.

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 states a specific verb ('list') and resource ('directory on the ZSpace NAS'), and clarifies its flat scope. It also names sibling tools it is not, making differentiation from zspace_tree, zspace_search, and zspace_info immediate.

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 explicitly says when to use: browse files, locate items, or pick targets for move/copy. It also gives clear alternatives with conditions: zspace_tree for nested structure, zspace_search when name is known, and zspace_info for metadata on a known path.

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

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

Annotations only provide openWorldHint=true, so the description must carry behavioral disclosure. It explicitly states the side effect ('Mutates NAS state'), a failure condition ('Fails if a directory of that name already exists'), and the return value ('Returns the created {name, path}'). This fully discloses the tool's behavior beyond the schema.

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 five sentences long, each earning its place: purpose, use case, parameter nuance, failure/return, and relationship to siblings. It is front-loaded with the core action and avoids any redundant phrasing.

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 simple two-parameter tool with an output schema, the description covers purpose, usage, failure, return, and side effects. Nothing an agent needs to invoke it correctly is missing, especially given the output schema already documents the return shape.

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 already covers both parameters with descriptions and examples (100% coverage). The description adds critical nuance for 'name' by clarifying it is a 'bare basename, not a path,' which is not explicit in the schema. This extra semantic guidance raises it above the baseline of 3 for high schema coverage.

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 clear verb-resource statement: 'Create a new directory on the ZSpace NAS under the given parent.' It precisely identifies the operation and the target namespace, and differentiates from siblings by implying it is a preparatory action rather than a move/copy/delete. The scope is unambiguous.

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?

Explicit guidance is provided: 'Use to prepare a destination before moving files into it.' It also states when to use it relative to zspace_move and zspace_copy, which require the destination to already exist. This tells an agent exactly when to call this tool and when not to.

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

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.

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

Annotations already provide readOnlyHint=true, so the description's 'Read-only; never modifies NAS state' is consistent and helpful. It goes further by disclosing that it returns normalized per-pool numbers rather than raw diagnostics, which is meaningful behavioral context beyond the structured annotations.

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 core capability, followed by usage guidance and sibling differentiation. Every sentence adds value; there is no filler or repetition of schema content.

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 zero-parameter read-only tool with an output schema, this description is complete: it states what is returned (a list of {name, total_tb, free_tb} objects), when to use it, and how it differs from related siblings. Nothing needed to invoke it correctly is missing.

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 tool has zero parameters, so there is nothing for the description to clarify about arguments. The description correctly implies an unqualified list operation, and the baseline for a no-parameter tool is 4.

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?

States a specific verb and resource: 'List every storage pool on the ZSpace NAS with its name and capacity.' It clearly distinguishes itself from zspace_disk_stats and zspace_check, so an agent can tell which tool answers a capacity question without opening schemas.

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?

Explicitly says when to use it ('inspect free space before an upload or to report total capacity'), and when to prefer alternatives ('Prefer this over zspace_disk_stats... Use zspace_check instead if you need to know whether the NAS is reachable at all'). This is strong routing guidance.

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

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

Annotations already establish readOnlyHint, but the description adds real behavioral context: -1 means never auto-purge, that is the factory default, and deleted data will occupy pool space indefinitely as a consequence. The 'Read-only' sentence is redundant with the annotation, and no auth or rate-limit context is offered, so it stops short of 5.

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 tool's purpose and returned fields are front-loaded in the first clause, followed by only the interpretations and the diagnostic cue that an agent actually needs. No filler sentences.

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 zero-parameter read with annotations and an output schema, everything required to call and interpret it is present. The -1 semantics are exactly the piece an output schema cannot convey, and they are supplied.

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?

Zero parameters, so the baseline is 4. The description's detail about the returned value -- days, with -1 meaning never auto-purge -- is interpretationally useful, though strictly it describes output rather than input, and an output schema is already present.

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?

States a precise verb+resource (read the recycle bin retention policy) and names the exact fields returned ({my_cycle, public_cycle} in days). This clearly separates it from the mutating siblings (zspace_recycle_purge/empty/restore) without the agent needing to open a schema.

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?

Gives a concrete diagnostic trigger: 'If a user reports that deleting files did not free space, check this first.' It also eliminates the alternative explicitly -- 'there is deliberately no MCP tool for changing it' -- so the agent knows not to hunt for a write counterpart.

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

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

Annotations already carry destructiveHint=true and openWorldHint=true, and the description adds substantial context beyond them: irreversibility, that this is the only operation that actually frees pool space, that personal and public bins are separate stores (with the total_num=0 failure mode), and that it purges everything in the bin rather than just the current task's deletions.

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?

Front-loads the destructive outcome in the first sentence, then organizes the remaining guidance into pitfalls and workflow. Every sentence carries operational value; nothing is redundant 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?

An output schema exists, so return values need not be detailed, yet the description still names the summary fields and tells the agent to verify total_num is non-zero before claiming space was freed. Combined with the pitfall and confirmation guidance, an agent has everything needed to invoke this safely.

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 personal/public and confirm semantics are already documented, giving a baseline of 3. The description goes further by explaining the operational consequence of choosing the wrong bin (success with total_num=0 and no space freed) and reinforcing that confirm must be explicitly true or the call is refused.

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?

Opens with a specific verb+resource+scope: 'Permanently purge an entire recycle bin.' It explicitly contrasts with the sibling that handles the narrower case ('Use zspace_recycle_purge to remove specific items instead'), so an agent can disambiguate without opening either schema.

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?

Gives an explicit precondition workflow (call zspace_recycle_list first, show the user, get agreement), states the required confirm=true, and names the alternative tool and the condition that selects it. It also warns when the call will silently succeed but do nothing, which is genuine when-to-use guidance.

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

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.

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.

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.

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.

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.

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.

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

Annotations already declare destructiveHint=true, but the description adds critical context the annotations cannot: irreversibility, the confirm=true guard that refuses otherwise, and the exact return shape {purged, failed}. Minor gap: no mention of auth requirements or partial-failure semantics.

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?

Front-loads the irreversible warning, then the sibling preference, then the required workflow, then the guard, then the return shape. Every sentence earns its place with no repetition.

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?

Covers purpose, irreversibility, sibling differentiation, prerequisite listing call, confirmation guard, and return shape. With annotations covering destructiveness and a 100% schema, nothing an agent needs to call this safely is missing.

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 baseline is 3, but the description adds meaning beyond schema: the confirm gate is tied to the refusal behavior, and paths are framed as 'in-bin paths from zspace_recycle_list' which clarifies the required format source. It also explains the consequence of omitting confirm.

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?

States a specific verb (permanently delete) and resource (named items in the personal recycle bin) with scope precision ('only the named items, leaving everything else untouched'). This clearly distinguishes it from zspace_recycle_empty and zspace_remove.

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?

Explicitly routes the agent: 'Prefer this over zspace_recycle_empty whenever the goal is to free the space held by specific files.' Also prescribes calling zspace_recycle_list first and showing the user the destruction set, which is a complete when-to-use workflow.

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

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

Annotations only carry openWorldHint, so the description must disclose the mutation profile and does: it clarifies the operation restores data rather than deleting it, and states a hard precondition (bin must not be emptied). It does not cover permissions required or behavior when a destination path already exists, leaving a modest gap for a mutation 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?

Three sentences, purpose front-loaded, followed by the critical path constraint and then recovery context. No redundant restatement of the name or schema; every sentence carries information.

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?

An output schema exists, so the brief 'Returns {restored, failed}' is supplementary rather than required. For a mutation tool with near-empty annotations, it discloses the non-destructive nature and precondition but omits auth requirements and destination-overwrite behavior.

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 baseline is 3, but the description adds real semantic value beyond the schema's example: paths must be in-bin paths from zspace_recycle_list, not original locations. That constraint is the main way an agent would get this wrong, and the description prevents it.

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?

States a specific verb (restore) and resource (items from the personal recycle bin to their original locations). Easily distinguished from sibling recycle tools (list, purge, empty) whose names imply different operations.

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?

Explicitly frames this as the recovery path after an accidental zspace_remove, names the precondition ('only works while the bin has not been emptied'), and points to zspace_recycle_list as the source of valid paths. When-to-use, when-not-to-use, and the related sibling are all covered.

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

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

Annotations already signal destructiveHint, but the description adds substantial behavioral context: deletion is immediate and unrecoverable, there is no trash/undo, what the return payload looks like, and the pool-root prohibition. This goes well beyond what annotations alone provide and contains 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.

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

The description is front-loaded with the core action, then flows into safety warning, alternatives, and confirmation steps. Every sentence contributes unique value, and no filler or redundancy inflates the length.

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 one-parameter destructive tool with annotations and an output schema, the description supplies everything an agent needs: purpose, irreversibility, alternative, precondition checks, and return format. Nothing critical is missing for correct invocation.

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%, but the description enriches the sole parameter by clarifying it accepts a single path or list, emphasizes absolute paths (already in schema), and adds the critical constraint 'never pass a pool root,' which is absent from the schema. This adds real meaning beyond the structured definition.

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 'Permanently delete one or more files/directories from the ZSpace NAS,' which states a specific verb, resource, and permanence. It differentiates from siblings by explicitly naming zspace_move as the reversible alternative, so an agent can choose correctly.

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?

Gives explicit when-to-use ('only when you are sure the items are no longer needed'), when-not-to-use (reversible case → zspace_move), and pre-call safety steps (confirm paths with zspace_ls or zspace_search, never pass a pool root). This exhaustively routes the agent around misuse.

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

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

Annotations only include openWorldHint=true, so the description carries the burden. It discloses that the operation mutates NAS state, cannot be undone, keeps the parent directory the same, and returns the updated {name, path}. It does not mention permission requirements or what happens if the target name already exists, but the core behavioral traits 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 compact and front-loaded: the first sentence states the action and scope, the second explains the use case, and the third gives the key constraint. Every sentence earns its place, and the sibling comparison is concise.

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 two-parameter tool with 100% schema coverage and an output schema, the description is nearly complete. It covers the mutation risk, the same-directory constraint, and the return value. A minor gap is the lack of error conditions (e.g., name collision), but the description is sufficient for an agent to invoke it correctly in most cases.

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 baseline is 3. The description adds value by clarifying that new_name is a bare basename, not a path, and that the parent directory stays the same. This prevents a common misuse where a user might pass a full path as new_name.

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 states a specific verb ('Rename'), a specific resource ('one file or directory on the ZSpace NAS'), and the key constraint 'keeping it in place.' It clearly distinguishes from siblings by noting it is same-directory only and does not accept multiple paths, unlike zspace_move.

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?

Explicitly says when to use it ('fix a name without changing location') and when not to ('use zspace_move to relocate to a different parent'), and notes that move accepts several paths while rename does not. This is strong routing guidance.

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

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

The description discloses the global index search with client-side filtering, the default path, the 100-result cap, and the silent-drop behavior for matches outside the path. It also confirms read-only status. These details go well beyond the readOnlyHint and openWorldHint annotations, providing essential operational context.

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 well-structured, starting with purpose, then usage, then behavioral nuances and a warning, then differentiation from siblings. Every sentence adds value—no fluff—and it remains readable despite length.

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?

With an output schema present, the return format is covered. The description covers purpose, usage, behavioral pitfalls, parameter nuances, and differentiators. The caution about empty results from path filtering is critical for correct invocation. Nothing essential is missing.

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 descriptions already cover both parameters, but the description adds meaningful semantics: it explains the default path's role in filtering, the meaning of 'keyword' (match against file names), and the consequence of the default. This goes beyond the schema, though it could explicitly tie parameters to behavior even more.

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 the tool searches for files/directories by name keyword, and explicitly differentiates from zspace_ls and zspace_tree ('matches by name across the index rather than walking a directory'). This gives a precise verb-resource-action and distinguishes it from siblings.

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 ('Use to find a file without knowing its exact location') and provides a critical warning about the default path filtering behavior, advising the user to widen the path before concluding a file doesn't exist. It also names alternatives (zspace_ls, zspace_tree) and explains why they differ.

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

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

Annotations already declare readOnly=true and openWorld=true, yet the description adds substantial context: the endpoint is keyed on serial and rejects other identifiers with N300403, NVMe drives report no classic attributes, and the response includes server-supplied warning/fault text. This is real behavioral disclosure beyond the structured annotations.

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?

Well front-loaded with the core purpose first, then input constraints, then output shape, then interpretation guidance. Slightly redundant in enumerating the return object fields even though an output schema exists, but no sentence is wasted.

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 one-parameter read tool with annotations and an output schema, this covers everything needed: valid input source, invalid input failure, return contents, NVMe exception, and which attribute ids matter. Nothing required for a correct call is missing.

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% with a single required 'sn' parameter, so the schema carries the baseline. The description adds genuine meaning: the parameter must be a serial (not a pool id or /dev name) or the call fails, and where to obtain a valid value.

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?

States a specific verb and resource ('Return the full SMART attribute table for one disk') and explicitly distinguishes itself from the sibling zspace_disks, which is positioned as the quick-overview tool. An agent can route correctly without opening either schema.

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?

Gives the prerequisite ('Get serials from zspace_disks first'), the wrong-input failure mode (pool id or /dev name returns N300403), and the alternative for a different need ('For a quick health overview use zspace_disks'). Explicit when-to-use and when-to-use-something-else.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description's 'Read-only' line adds no new safety info. It does add the recursion-depth behavior and the note that output is 'as exposed by the NAS API', which is mild context, but nothing about pagination, error cases, or the exact structure. With annotations covering the key safety trait, a 3 is appropriate.

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 tight: a one-sentence purpose, a short usage note, a brief behavioral note, and a clear alternative line. Every sentence earns its place, and the key distinguishing information is front-loaded.

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 read-only tree tool with two simple parameters and an output schema present, the description covers purpose, usage, alternatives, and the key recursion behavior. Nothing an agent needs to call it correctly is missing.

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 description coverage is 100%, so both 'path' and 'depth' are already documented with defaults and descriptions. The description repeats 'depth caps recursion (default 2)' but adds no meaning beyond the schema. Baseline 3 applies because the schema carries the load.

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 the verb 'Return' and the resource 'a nested tree view of a directory on the ZSpace NAS', and immediately distinguishes itself from siblings (zspace_ls and zspace_search). This gives an agent an unambiguous mental model of what the tool does and how it differs.

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?

Explicitly states when to use ('to understand overall folder structure before deep operations') and provides clear exclusions and alternatives ('use zspace_ls for a single level with sizes, or zspace_search when you are looking for a name rather than a layout'). No inference needed.

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

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.

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.

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.

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.

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.

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.

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.