Search Tools

Tools for finding files by name pattern and searching file contents by regular expression.

Claude Code provides two dedicated search tools — GlobTool and GrepTool — plus a meta-search tool ToolSearchTool for discovering the right built-in tool to use. These tools are faster, safer, and more token-efficient than shelling out to find or grep via BashTool.

GlobTool

Find files by name or path pattern

GrepTool

Search file contents with regex (powered by ripgrep)

ToolSearchTool

Discover which built-in tool to use for a task

---

GlobTool

Finds files whose paths match a glob pattern. Results are sorted by modification time (most recently changed first) to surface relevant files quickly.

Tool name: Glob
Read-only: yes
Concurrency-safe: yes
Destructive: no

Parameters

pattern · string · required

The glob pattern to match file paths against. Supports *, **, ?, and brace expansions, e.g. "**/*.ts", "src/**/*.{ts,tsx}", "*.config.js".

path · string

Directory to search in. Defaults to the current working directory when omitted. Must be a valid directory path — do not pass "undefined" or "null".

Return value

filenames · string[]

Relative paths (relative to the current working directory) of matching files.

numFiles · number

Total number of files returned.

truncated · boolean

true when results were capped (default cap: 100 files). Use a more specific pattern or path to narrow the search.

durationMs · number

Wall-clock time to execute the search in milliseconds.

Usage examples

Find all TypeScript files in a project:

{
  "tool": "Glob",
  "input": {
    "pattern": "**/*.ts"
  }
}

Find config files in a specific directory:

{
  "tool": "Glob",
  "input": {
    "pattern": "*.config.{js,ts,mjs}",
    "path": "/home/user/project"
  }
}

When results are truncated, add a path to constrain the search scope or make the glob pattern more specific (e.g. "src/**/*.test.ts" instead of "**/*.test.ts").

---

GrepTool

Searches file contents for a regular expression pattern. Internally uses ripgrep (rg) for high performance, with automatic exclusion of VCS directories (.git, .svn, .hg, .bzr, .jj, .sl).

Tool name: Search
Read-only: yes
Concurrency-safe: yes
Destructive: no

Parameters

pattern · string · required

A regular expression pattern to search for. Full ripgrep regex syntax is supported.

path · string

File or directory to search in (rg PATH). Defaults to the current working directory.

glob · string

Glob pattern to filter which files are searched, e.g. "*.js" or "*.{ts,tsx}". Maps to rg --glob.

output_mode · string · default: "files_with_matches"

Controls the format of results:

• "files_with_matches" — list of file paths that contain at least one match (default)
• "content" — matched lines with optional surrounding context lines
• "count" — number of matches per file

-B · number

Lines of context before each match (rg -B). Only used when output_mode is "content".

-A · number

Lines of context after each match (rg -A). Only used when output_mode is "content".

-C · number

Lines of context before and after each match (rg -C). Alias for context. Overrides -B/-A when specified. Only used when output_mode is "content".

context · number

Alias for -C. Lines of symmetric context around each match.

-n · boolean · default: "true"

Show line numbers in "content" mode output (rg -n).

-i · boolean · default: "false"

Case-insensitive search (rg -i).

type · string

Restrict search to a ripgrep file type (rg --type). Examples: "js", "py", "rust", "go", "java". More efficient than glob for standard language types.

head_limit · number · default: "250"

Limit output to the first N lines/entries, equivalent to | head -N. Pass 0 for unlimited (use sparingly — large results consume significant context).

offset · number · default: "0"

Skip the first N lines/entries before applying head_limit. Equivalent to | tail -n +N | head -N. Use together with head_limit for pagination.

multiline · boolean · default: "false"

Enable multiline mode where . matches newlines and patterns can span lines (rg -U --multiline-dotall).

Return value

mode · string

The output mode that was used: "files_with_matches", "content", or "count".

filenames · string[]

Matching file paths (relative to CWD). Populated for "files_with_matches" mode. Sorted by most recently modified.

numFiles · number

Number of files returned.

content · string

Matched output as a string. Populated for "content" and "count" modes.

numLines · number

Number of output lines. Populated for "content" mode.

numMatches · number

Total match count across all files. Populated for "count" mode.

appliedLimit · number

The head_limit that was applied, set only when truncation actually occurred.

appliedOffset · number

The offset that was applied, set when offset > 0.

ripgrep under the hood

GrepTool delegates to ripgrep (rg) and mirrors its semantics closely. Key behaviours:

• Lines are capped at 500 characters to avoid bloating results with minified files or base64 blobs.
• VCS directories are excluded automatically via --glob !.git --glob !.svn etc.
• Permission-based ignore patterns from Claude Code settings are forwarded as additional --glob !... rules.
• In "files_with_matches" mode, results are sorted by file modification time before head_limit is applied.

Usage examples

Find all files containing a React hook:

{
  "tool": "Search",
  "input": {
    "pattern": "useEffect",
    "output_mode": "files_with_matches",
    "type": "tsx"
  }
}

Show matching lines with context in a specific directory:

{
  "tool": "Search",
  "input": {
    "pattern": "TODO|FIXME|HACK",
    "path": "/home/user/project/src",
    "output_mode": "content",
    "context": 2,
    "head_limit": 100
  }
}

Case-insensitive search with pagination:

{
  "tool": "Search",
  "input": {
    "pattern": "deprecated",
    "output_mode": "content",
    "-i": true,
    "head_limit": 50,
    "offset": 50
  }
}

---

ToolSearchTool

A meta-tool that searches the descriptions of all available built-in tools to help the model find the right tool for a given task. Useful when an unfamiliar task might be covered by a lesser-known built-in.

Tool name: ToolSearch
Read-only: yes
Concurrency-safe: yes
Destructive: no

Parameters

query · string · required

A natural-language description of the task you want to accomplish. The tool matches against the searchHint field registered on each built-in tool.

Return value

An ordered list of tool names and their descriptions ranked by relevance to query.

Usage example

{
  "tool": "ToolSearch",
  "input": {
    "query": "read a specific resource from an MCP server"
  }
}