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

Annotations already declare destructiveHint=true and readOnlyHint=false; the description adds the meaningful nuance that maps to that hint — it writes a local file but 'does not overwrite existing local files by default' — which tells the agent the default is non-clobbering. No auth, rate-limit, or partial-transfer behavior is covered, but the added context is substantive rather than a restatement.

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?

Four short sentences, front-loaded with the action and destination, and the overwrite caveat is placed last where it belongs. The only near-waste is 'Provide the NAS file path,' which largely restates the required field in 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?

An output schema exists, so return values need no explanation, and the annotations carry the safety profile. The description covers destination resolution and overwrite behavior adequately for a 4-param tool; the unexplained 'filename' parameter and unstated behavior on directories are the only gaps.

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 0%, so the description must compensate. It explains path (required), dest_folder's optionality and its dependency on default_download_dir, and the overwrite default — but never mentions 'filename', leaving one of four parameters entirely unexplained in both schema and description.

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?

Specific verb+resource ('Download a NAS file') with an explicit destination scope ('to a local directory on this machine'), which cleanly separates it from every sibling (list_files, search_files, get_file_info all operate NAS-side). No sibling name is needed because none of them perform a download.

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 the one prerequisite (provide the NAS file path) and a conditional for one optional parameter (dest_folder is optional if default_download_dir is configured), which is genuine operational guidance. However, it never says when to prefer this over alternatives or what conditions make it inappropriate, so usage is only implied.

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 annotations already declare this a safe read (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description adds genuine behavioral content beyond that: recursion into all subdirectories and the three metrics returned. It omits any warning about cost/latency on very large trees or permission-denied behavior, so it is not a 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?

Three short sentences, zero waste, with the core action front-loaded and the usage hint deferred to the end where it belongs.

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 description need not explain the return payload, and the annotations cover safety. It is nearly complete for a single-parameter read tool; the remaining gap is the absence of any caveat about slow scans on large directories.

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 0%, but there is only one parameter and the description implicitly constrains it to a directory rather than a file. It says nothing about absolute vs relative paths or symlink handling, so it adds only marginal meaning over the bare 'path: string' 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?

States a specific verb and resource ('Calculate the total size of a directory') with the recursive scope made explicit ('including all files and subdirectories'). It is plainly distinguishable from siblings like get_file_info and list_files, which do not aggregate sizes.

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?

'This is the best tool for answering how much space does X use questions' gives a clear usage context and implicitly routes the agent away from list_files/get_file_info. It does not name an alternative tool or state when not to use it, so it stops short of a 5.

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 destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the default field set returned, that 'unknown values are rejected', and that mount_point_type only appears for mount points — all useful invocation-time facts.

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, then a tight second sentence covering the optional field selector, its allowed values, and the default. Dense but every clause carries information; the parenthetical clarifications for 'type' and 'mount_point_type' are load-bearing, not 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-value shape need not be described. For a two-parameter read-only tool the description covers the non-obvious parameter thoroughly and states the default and rejection behavior; only the `paths` input format remains under-specified.

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 0%, so the description must carry the load, and it does for `additional`: it lists the accepted field values, explains 'type' as the extension type, notes mount_point_type is mount-only, and gives the default set. `paths` is left thinner — it is never stated whether paths are absolute, relative, or share-qualified — which keeps this from 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 detailed metadata for specific files or folders') and enumerates exactly what is returned: size, owner, timestamps, permissions, real path. That enumeration cleanly separates it from list_files/search_files/get_dir_size in practice, though no sibling is named explicitly, which caps it below a 5.

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 phrase 'for specific files or folders' implies the caller must already know the paths, which implicitly distinguishes this from listing or search tools. However, there is no explicit when-to-use statement, no mention of alternatives such as search_files or get_dir_size, and no stated prerequisites or failure conditions.

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 destructiveHint=false, so the safety profile is covered. The description adds the capability surface (globbing, filtering, sorting, pagination) but says nothing about recursion depth, hidden-file handling, or behavior on a missing path, which are the traits an agent would still need.

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?

Two sentences, zero filler, with the core action front-loaded ahead of the capability list. Every clause maps to a real feature of the tool.

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 read-only annotations and an output schema present, the description needn't explain returns or safety, and it covers the main behavioral knobs. It falls short only on edge-case behavior (recursion, defaults, error handling) for an 8-parameter tool.

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 0%, so the description carries the full burden and largely succeeds: 'glob pattern filtering' maps to pattern, 'file type filtering' to filetype, 'sorting' to sort_by/sort_direction, and 'pagination' to limit/offset. The 'additional' parameter and any glob syntax details are left unexplained, so it is not fully compensating.

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+resource (list files and folders) and scope (in a directory), plus the supported capability set. It does not differentiate itself from siblings like search_files or list_recycle_bin, which an agent could plausibly confuse for directory 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?

There is no explicit when-to-use or when-not-to-use guidance. The phrase 'in a directory' weakly implies directory-scoped enumeration versus a global search tool like search_files, but the agent is left to infer this; no alternative is named.

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 destructiveHint=false, so the safety profile is covered. The description adds the useful fact that entries are restorable deleted files, but says nothing about pagination, default limits, or how the recycle bin is scoped to a share.

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?

Two short sentences, front-loaded with the core action and free of filler. The second sentence is arguably redundant but adds a useful qualifier about restorability.

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 no explanation, and annotations cover safety. However, with five undocumented parameters at 0% coverage, a filtered/sorted list tool needs more detail about scoping, filtering, and sorting than two sentences provide.

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?

Five parameters exist with 0% schema description coverage, and the description documents none of them. Only the word 'shared folder' loosely implies the required 'share' parameter; limit, pattern, sort_by, and sort_direction are entirely unexplained, so the description fails to compensate for the coverage gap.

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 gives a specific verb and resource ('List the contents of a shared folder's recycle bin') and clarifies the resource further ('recently deleted files that can be restored'). It does not, however, distinguish this tool from close siblings like list_files or search_files, so an agent must infer the recycle-bin scope on its own.

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?

There is no explicit when-to-use or when-not-to-use guidance and no named alternative (e.g., list_files for live contents vs. this for deleted items). The phrase 'recently deleted files that can be restored' hints at the use case but leaves the selection decision 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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful semantics beyond that: the returned free space is per-volume and shared across all shares on it, which is a real interpretive trap the agent would otherwise misread. It doesn't mention auth requirements or pagination, keeping it short of a 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?

Three sentences, each load-bearing: purpose, role in the workflow, and a disambiguation of the returned free-space value. Front-loaded with the core action and free of 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?

Output schema exists so return values needn't be fully explained, and the description still clarifies the volume/free-space semantic. The only real gap is the undocumented parameters, which is a meaningful omission for a tool with sort and pass-through options.

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 0% across three parameters, including the opaque 'additional' array, so the description carries the full burden — and it says nothing about sort_by, sort_direction, or additional. With low coverage the description must compensate, and here it does not.

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 ('List all shared folders on the NAS') and immediately frames itself as the entry point for file navigation, which cleanly separates it from siblings like list_files, search_files, and get_dir_size. An agent knows exactly what this returns without opening the 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 sequencing guidance — 'call this first to discover available paths' — and an explicit alternative with its condition: use get_dir_size for per-share space usage. This is textbook when-to-use plus 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 destructiveHint=false, so the safety profile is established by structured data. The description adds useful semantics (substring-not-glob, default recursion, human-readable size formats) but says nothing about result caps/pagination behavior even though limit defaults to 500 in the schema. Adequate but not rich behavioral 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?

Dense and front-loaded: purpose first, then per-parameter clarification, then the alternative-tool routing. Every sentence earns its place, though the single long paragraph is packed more tightly than ideal for scanning.

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 12-parameter tool with no schema descriptions, the description covers the high-value parameters well and an output schema exists so return values need no explanation. It falls short only on the secondary parameters (exclude_pattern, additional, filetype, limit semantics).

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 0% across 12 parameters, so the description carries the burden and largely does: it explains pattern (keyword substring, not glob), extension (with an example), size_from/size_to (human-readable '500MiB'), and the three accepted mtime formats including naive-date-as-UTC. It leaves limit, filetype, recursive, exclude_pattern, additional, and folder_path undocumented, which is a real gap but not fatal to the common path.

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 (search), resource (files), and the four filter dimensions (keyword, extension, size, modification date), plus scope (recursive). It also names the sibling tools it is not (list_files, get_dir_size), so an agent can separate it from the other read tools 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?

The final sentence gives an explicit when-not rule with named alternatives: 'For directory contents or sizes, use list_files or get_dir_size instead.' Combined with the recursive-search framing, the agent knows when this tool is the right pick versus its siblings.

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