find

[symbols]

Primary search over the workspace. Strict modes (literal, regex, word) are exhaustive with deterministic order; fuzzy is ranked top-N with frecency. target: auto routes by query shape, and every response echoes the resolved route in data.route.

Why this tool exists

Text search is the highest-frequency agent operation, and shell tools give unranked, unscoped output that ignores editor-fresh changes.

How it helps the agent

One tool covers ranked fuzzy discovery and exhaustive grep-grade audits, with scoping, pagination, previews, and a route echo that makes auto behavior observable.

Parameters

Name	Type	Required	Description
query	string	Yes	The search text, pattern, or path fragment. /re/ forces regex; "quoted" forces literal.
target	string	No	What to search: 'auto', 'files', 'content', 'symbols', 'structural', or 'semantic'. auto routes by query shape. structural runs ast-grep patterns and symbols returns a declaration outline (symbol name/kind/container); both answer natively for the nine linked grammars and degrade to a lexical search elsewhere, with meta.degraded naming the languages that had no grammar; semantic fuses embedding search with a lexical ranking over the same chunks. route.tier reports hybrid when both legs contributed and semantic when only the embeddings did. Its score orders one result set and is not a similarity. It is on by default, downloading the embedding model once per user on first start; until the tier is ready it degrades to lexical fuzzy with meta.degraded set, and --no-semantic turns it off.
match	string	No	Match mode: 'auto', 'fuzzy', 'literal', 'regex', or 'word'. Strict modes are exhaustive; fuzzy is ranked. auto picks fuzzy for files and literal for content; symbols use a deterministic name match (not fuzzy). 'word' searches whole words only, so a query that is merely part of a longer identifier matches nothing - use 'literal' for substring occurrences.
case	string	No	Case handling: 'auto' (smart-case: sensitive when the query has an uppercase character), 'sensitive', or 'insensitive'.
scope	json	No	Optional scope: pathPrefix (workspace-relative directory), globs (prefix with ! to exclude), and languages (tokens like rust, typescript, csharp).
skip	number	No	Pagination offset.
take	number	No	Maximum matches to return; clamped to the configured maximum (default 200).
maxPreviewChars	number	No	Preview truncation length per match.
pathStyle	string	No	'relative' (workspace-relative, forward-slash) or 'absolute'.
continuationToken	string	No	Resumes an exhaustive scan that stopped on its time budget. Only literal, regex, and word searches issue one. Pass it back with the same query and scope. It is refused if the query, the scope, or the index changed, and cannot be combined with skip.

Examples

Fuzzy file and identifier hop (ranked)

Request 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "find",
    "arguments": {
      "query": "usrctrl"
    }
  }
}

Exhaustive regex over content

Request 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "find",
    "arguments": {
      "query": "/fn handle_\\w+/",
      "target": "content"
    }
  }
}

Exhaustive word match scoped by globs

Request 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "find",
    "arguments": {
      "query": "timeout",
      "target": "content",
      "match": "word",
      "scope": {
        "globs": [
          "src/**",
          "!**/tests/**"
        ]
      }
    }
  }
}

Forced literal phrase

Request 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "find",
    "arguments": {
      "query": "\"exact phrase\""
    }
  }
}

Response Notes

Returns matches with workspace-relative path, 1-based line and column, and a trimmed preview; data.route echoes the resolved target and match, and paging carries skip/take/total. exhaustive: true confirms a strict search saw every match; when a limit is hit (match cap, oversized file, time budget) exhaustive flips to false with meta.partial set and the total marked as a floor - never silent truncation. data.coverage reports scannedFiles, inScopeFiles, and stoppedAt, so a scan cut short by the time budget names the file where coverage ended instead of looking like an absence - narrow the scope or raise limits.find-budget-ms in .glider/scout/config.toml and re-run. A zero-hit strict search is a valid empty result with a hint suggesting a fuzzy retry; Scout never silently falls back.