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 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 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 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 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.