Skip to main content
Glama

Search files by name

nas_search_files
Read-only

Search the NAS index for files and folders by name, then narrow results by path, type, size, date, or tags to locate specific items.

Instructions

Search the NAS index for files and folders whose name contains the query (case-insensitive). It matches names, not file content. Give paths to limit the search to folders; subfolders are included unless recursive is false. The call waits for the search to finish and returns the first sorted page in data.results.ordered_items[], plus data.task_id. When data.next_offset is present there are more results: page through them with nas_search_results using the same sort_by and order. When data.task_removed is not true the search task is still stored on the NAS; release it with nas_search_results action "remove" when you are done. file_size and the time fields are strings. A search without paths or query can take minutes; narrow it first.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "nas_search_files"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoResults per page (max 500).
orderNoSort direction.
pathsNoAbsolute NAS folders to search in.
queryNoPart of the file or folder name.
suffixNoFile extension without the dot, for example pdf.
classesNoOnly these kinds of entries.
sort_byNoSort key. Use the same sort_by and order on every page of one search.name
tag_idsNoOnly files carrying these tag IDs.
max_sizeNoLargest file size. Bytes, or a number with K, M or G, for example 10K or 4M.
min_sizeNoSmallest file size. Bytes, or a number with K, M or G, for example 10K or 4M.
recursiveNoInclude subfolders of paths.
max_resultsNoStop searching after this many matches.
modified_toNoModified at or before this time. Unix time in seconds.
modified_fromNoModified at or after this time. Unix time in seconds.
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.6/5.0
Behavior4/5

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

Annotations already declare readOnly, openWorld and non-destructive, but the description goes well beyond them: it discloses that the call blocks until the search finishes, describes the returned fields, the pagination sentinel data.next_offset, the lingering task lifecycle via data.task_removed, the string typing of file_size and time values, and that a timeout-truncated result is incomplete. The only gap is that it does not say whether a timed-out task can be resumed or must be re-run.

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?

Dense and front-loaded: capability first, then scope semantics, then return shape, then pagination and cleanup, then the performance warning. Despite its length, every sentence carries operational information needed to call a 15-parameter search correctly.

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

Completeness4/5

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

With 15 optional parameters and no output schema, the description has to describe the return payload, which it does (data.results.ordered_items[], data.task_id, data.next_offset, data.task_removed). It mostly omits guidance on filter interaction, e.g. how suffix, classes, tag_ids and size/time bounds combine or whether they apply to folders, leaving some ambiguity for an agent building a filtered query.

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 the baseline is 3, but the description adds genuine meaning: query is a name substring, paths restrict scope to folders and implies subfolders are included, and sort_by/order must stay consistent across pages of one search. It does not explain suffix/classes/tag_ids/size or time filters, but those are already documented in the schema.

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 first sentence names a specific verb (search) and resource (NAS index for files and folders) and scopes it to name matching, then explicitly negates the likely wrong assumption with "It matches names, not file content." An agent can distinguish this from file-content or path-based siblings 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 Guidelines5/5

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

It gives explicit when-to-use context (narrow first because a search without paths or query can take minutes), states that paths limit scope and recursive controls subfolder inclusion, and routes continuation to nas_search_results with matching sort_by and order. It also says when to call the sibling's remove action, which is a real post-use step rather than vague advice.

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