Skip to main content
Glama

Find files under folders

nas_file_find
Read-only

Search multiple NAS shared folders and return files or folders matching name, type, size, time, and depth filters in one request.

Instructions

Walk one or more folders and return entries matching the filters. kind selects plain files, folders, or a media category (image, video, audio, archive, doc, font, app). Sizes take a unit suffix such as 10K or 4M. since and until are Unix seconds and need time_field to say which timestamp they apply to. Roots must be shared folders or folders inside them; a volume root is reported as an invalid root. All roots are searched in one request, so matches are in the top-level entries[] of the result, and that key is absent when nothing matched. For finding files by name across a large area, nas_search_files is faster.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "roots": "<roots>"
    },
    "name": "nas_file_find"
  }
}

Input Schema

NameRequiredDescriptionDefault
kindNoOnly plain files, only folders, or only one media category.
nameNoFile name pattern with * and ?, for example *.jpg.
limitNoMaximum number of results; 0 means no limit.
rootsYesFolders to search in. Absolute NAS paths (1 to 20).
sinceNoOnly entries at or after this time. Unix time in seconds.
untilNoOnly entries at or before this time. Unix time in seconds.
max_sizeNoLargest file size to include. Bytes, or a number with K, M or G, for example 10K or 4M.
min_sizeNoSmallest file size to include. Bytes, or a number with K, M or G, for example 10K or 4M.
max_depthNoHow many folder levels to descend; omit for no limit.
time_fieldNoTimestamp that since/until apply to: creation, modification, access or deletion time.
timeout_secondsNoTime limit in seconds (default 120, max 1800). Raise it for large folders or files; a result cut off by the limit is incomplete.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the readOnly/openWorld annotations, the description discloses non-obvious behavior: volume roots are reported as an invalid root, all roots are searched in one request, matches land in top-level entries[] and that key is absent on no match, and a timeout-truncated result is incomplete. These are exactly the operational details annotations cannot express.

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

Conciseness5/5

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

Purpose is front-loaded, then constraints, then result shape, then the sibling redirect — a logical order with no filler sentences. Every clause conveys a usable fact (root rules, units, time_field pairing, entries[] key absence, timeout truncation).

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

Completeness5/5

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

For an 11-parameter read tool with no output schema, the description covers the important gaps: valid roots, how multiple roots are combined, where results appear and when the key is missing, and timeout-induced incompleteness. 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.

Parameters4/5

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

Schema coverage is 100%, so baseline would be 3; the description earns above that by explaining the coupling that the schema states only per-field — that since/until require time_field to indicate which timestamp applies. It also reiterates the kind categories and the size unit suffix in a compact, readable way.

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

Purpose5/5

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

The opening sentence gives a specific verb+resource+scope ('Walk one or more folders and return entries matching the filters'), and the final sentence explicitly contrasts it with nas_search_files for name-based lookups. An agent can distinguish this from nas_file_list or nas_search_files 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.

Usage Guidelines4/5

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

It routes the agent away for one case ('For finding files by name across a large area, nas_search_files is faster') and states root-validity preconditions, which is real when-to-use guidance. It stops short of explicit when-not-to-use conditions beyond that single alternative, so it is not a full 5.

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