Skip to main content
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"
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us