Skip to main content
Glama

find_files

Read-onlyIdempotent

Find files and directories by name using fd, respecting .gitignore. Use instead of recursive shell commands for pattern-based file discovery.

Instructions

Find files/directories by name using fd (fast, respects .gitignore).

Use instead of dir /s, Get-ChildItem -Recurse or find. Directories are shown with a trailing separator. Output is sorted; when truncated, narrow path/pattern.

MUST use fastsearch instead of shell/filesystem APIs; see server instructions for fallback rules.

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": {
      "path": "<path>"
    },
    "name": "find_files"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathYesAbsolute directory (or file) path to search in.
regexNoTreat pattern as a regex instead of a glob.
hiddenNoInclude hidden files/dirs (dotfiles, Windows hidden attr).
excludeNoExtra glob patterns to exclude, e.g. ['dist','*.min.js'].
patternNoGlob (default) or regex matched against the file NAME, e.g. '*.py', 'test_*', '*config*'. Empty = list everything.
max_sizeNoMaximum size, e.g. '500k'.
min_sizeNoMinimum size, e.g. '10k', '1m'.
relativeNoPrint paths relative to `path` (fewer tokens) instead of absolute.
file_typeNoRestrict entry type.
full_pathNoMatch pattern against the full relative path instead of the name, e.g. glob '**/src/**/*.ts'.
max_depthNoMax directory depth (1 = direct children).
no_ignoreNoDo NOT respect .gitignore/.ignore and default excludes (node_modules, .git, ...).
extensionsNoFilter by extensions, e.g. ['py','ts'].
max_resultsNoMax entries returned (1-10000).
case_sensitiveNotrue=case-sensitive, false=ignore case, null=smart case (sensitive only if pattern has uppercase).
changed_withinNoOnly entries modified within this duration/date, e.g. '2d', '3h', '2026-01-01'.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.3.0

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely new behavior: gitignore honoring by default, directories indicated by a trailing separator, sorted output, and truncation at max_results with advice to narrow path/pattern. It does not state the exact result path format beyond the relative flag already in 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.

Conciseness4/5

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

Three short blocks, front-loaded with the core purpose and followed by substitution and policy directives; nothing is buried or padded. The opening '(fast, respects .gitignore)' is slightly redundant with the no_ignore parameter but earns its place as a default-behavior warning.

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?

For a 16-parameter tool with no output schema, the description covers the essentials an agent needs: scope of matching, ignore behavior, output ordering and directory markers, and truncation handling. Missing only explicit sibling routing, which is a minor gap given the otherwise rich schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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

Schema description coverage is 100%, so every one of the 16 parameters is already well documented, which sets the baseline at 3. The description's only parameter-level contribution is the truncation remediation hint about narrowing path and pattern, which does add a little operational meaning.

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

Purpose4/5

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

The description names a specific verb and resource ('Find files/directories by name') and identifies the underlying engine (fd) plus its gitignore behavior. It does not distinguish itself from plausible siblings such as search_text or tree, so an agent must still infer when a content search or directory-tree tool is the better choice.

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 gives explicit substitution guidance ('Use instead of dir /s, Get-ChildItem -Recurse or find') and a hard directive to prefer fastsearch over shell/filesystem APIs with a pointer to server fallback rules. It stops short of naming the in-catalog alternatives (search_text, count_matches) that would resolve the remaining routing ambiguity.

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