Skip to main content
Glama
nucleusv

Linux MCP daemon

by nucleusv
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Go
Local

files/find

Read-onlyIdempotent

Search a directory tree (default /) by name, type, age, or size to locate files. Read-only; skips system directories when starting at root.

Instructions

Searches a directory tree (default /) by name, type, age or size, like find. Read-only; never follows symlinks; skips /proc, /sys, /dev and /run when the search starts at / or above them (not when path is inside one). Use files/list to see one known directory and disks/usage to see which folders take the space. All filters are ANDed and none is required. There is NO result cap: path: / without a filter lists every file on the host, so give name, type or max_depth; the 30 s worker timeout applies. Syntax: name is a case-sensitive glob on the base name only (*.log, not a path); type is one of f d l b c p s or a comma list (f,d); mtime in days: +7 older than 7 days, -1 within the last day, 7 exactly 7 days; size: +100M larger, -10k smaller (units b c w k M G, rounded up); max_depth 1 = direct children, omitted or 0 = unlimited. Unreadable directories are skipped silently. Text output: one SIZE PATH line per match, sorted by path (no size for directories; empty output = no match). output_format: json returns an array of objects (path, size in bytes, type).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameNoGlob on the file's base name only, case-sensitive, e.g. '*.log' (not a path pattern)
pathNoAbsolute starting directory (default /). A large tree with no filter can take longer than the 30 s worker limit
sizeNo'+100M' larger than 100 MiB, '-10k' smaller than 10 KiB; units b c w k M G, rounded up to the unit
typeNof file, d directory, l symlink, b, c, p, s; or a comma list such as 'f,d'
mtimeNoDays since modification: '+7' older than 7 days, '-1' within the last day, '7' exactly 7 days
max_depthNoLevels below path to descend (1 = direct children); omit or 0 for unlimited
privilegedNoRun as root. Needs a grant for this tool in mcp-sudo.yaml and a `paths:` entry covering the path, otherwise refused
output_formatNojson (yaml, table and wide return the same JSON) gives an array of objects with path, size, type; default is text
human_readableNoText output only: sizes like 1.5 KiB; default is bytes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changedv0.4.1
    • changedInput schema / properties / human_readable / description
      Previous value: -"Sizes like 1.5 KiB; default is bytes"New value: +"Text output only: sizes like 1.5 KiB; default is bytes"
    • changedInput schema / properties / max_depth / description
      Previous value: -"Maximum depth for directory recursion"New value: +"Levels below path to descend (1 = direct children); omit or 0 for unlimited"
    • changedInput schema / properties / mtime / description
      Previous value: -"Modification time (e.g. '+7' for older than 7 days)"New value: +"Days since modification: '+7' older than 7 days, '-1' within the last day, '7' exactly 7 days"
    • changedInput schema / properties / name / description
      Previous value: -"Glob pattern to match filenames"New value: +"Glob on the file's base name only, case-sensitive, e.g. '*.log' (not a path pattern)"
    • changedInput schema / properties / output_format / description
      Previous value: -"Desired output format. Defaults to text"New value: +"json (yaml, table and wide return the same JSON) gives an array of objects with path, size, type; default is text"
    • changedInput schema / properties / path / description
      Previous value: -"Starting directory for the search. Defaults to '/'"New value: +"Absolute starting directory (default /). A large tree with no filter can take longer than the 30 s worker limit"
    • changedInput schema / properties / privileged / description
      Previous value: -"Set to true to search as root"New value: +"Run as root. Needs a grant for this tool in mcp-sudo.yaml and a `paths:` entry covering the path, otherwise refused"
    • changedInput schema / properties / size / description
      Previous value: -"File size (e.g. '+100M' for larger than 100MB)"New value: +"'+100M' larger than 100 MiB, '-10k' smaller than 10 KiB; units b c w k M G, rounded up to the unit"
    • changedInput schema / properties / type / description
      Previous value: -"File type ('f' for file, 'd' for directory, 'l' for symlink)"New value: +"f file, d directory, l symlink, b, c, p, s; or a comma list such as 'f,d'"
  2. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, yet the description still adds substantial behavior: never follows symlinks, the /proc /sys /dev /run skip rule (and its path-dependent exception), the absence of a result cap, the 30 s worker timeout, and silent skipping of unreadable directories. This is exactly the contextual detail 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.

Conciseness4/5

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

Well front-loaded: purpose and safety first, alternatives next, then filter semantics, syntax, and output format. It is dense and every section earns its place, though the syntax recap is lengthy for a schema that already documents the same rules.

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?

With 9 optional params and no output schema, the description still specifies the filter combination rule, the destructive-risk caveat, and the exact return shape (per-line SIZE PATH sorted by path, empty output = no match; json array of path/size/type). 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 is 3, but the description adds non-schema semantics: all filters are ANDed and none is required, plus the relative-vs-absolute mtime/size operators and max_depth defaults. Most per-parameter syntax restates the schema, so it is value-adding but partly redundant.

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?

States a specific verb (searches) and resource (a directory tree) plus the filter axes (name, type, age, size) and the `find` analogy. It positively distinguishes itself from `files/list` (single known directory) and `disks/usage` (space consumers), so an agent can route 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.

Usage Guidelines5/5

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

Explicitly names the alternatives and their conditions ('Use `files/list` to see one known directory and `disks/usage` to see which folders take the space'), and warns when a filter is mandatory to avoid an unbounded scan. When-to-use and when-NOT-to-scan-without-a-filter are both covered.

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

Deploy Server

Other Tools