Skip to main content
Glama

Find exact text (every occurrence, like grep -n)

find
Read-only

Search exact strings across a repository and return every matching line with path, line number, context, and per-file counts. Locate identifiers, definitions, error messages, or config keys like grep.

Instructions

Every line in the repository containing an exact string, like grep -n: complete and unranked, written as grep writes it (path:line:text, one line per match, the enclosing definition in brackets when known), with the repo-wide total and the per-file counts after the matches (the grep -c answer). Literal text within one line, case-sensitive unless ignoreCase. Use it where you would grep: every use or definition of an identifier, an error message, a config key. Set defines to get only where a name is defined rather than everywhere it appears. Find a definition by its bare name with defines - refresh( lists every refresh declared - never by a signature you have composed: find matches characters, so a guessed line matches nothing. Each match comes in the block of code it sits in, with the 4 lines around it - the comment above it, the lines below - numbered as a file read is and merged where they meet, so what each match does or relies on is in the result and no file need be opened. chunks: true carries whole blocks; chunks: false the matching line alone, as grep -n does, and with context the lines before and after it (grep -B/-A). When a result names further pages, ask for every one of them in the same reply with skip. Never follow a find with a read per match. A wide result lists every matching place: the first lines with their text, the rest by path and line after them; a line's text is one sql statement away, and the per-file counts count them all. A count per project or per file - which projects use X, how many times each - is one sql statement, never a shell pipeline: SELECT split_part(path,'/',1) AS project, count(*) AS lines FROM token_match('chunks','content','','and') GROUP BY 1 ORDER BY 2 DESC (GROUP BY path for the count per file). Not for a file you already know - read it, with every other file you need, in one read call, or its lines are one sql statement away (SELECT start_line, content FROM chunks WHERE path = '...' ORDER BY start_line). For meaning or 'how does X work' use search; for rankings use sql. Several finds at once: pass queries. The result includes a 'usage' field, a one-line receipt of tokens returned, matches and files.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

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

Input Schema

NameRequiredDescriptionDefault
pathNoAbsolute path to the repository root to search. Defaults to the server's configured root; set it to target a specific repo when a session spans more than one. This is a different index; `under` narrows within one.
skipNoMatching lines to pass over before this result starts: the next page of a find its budget cut. A result that could not carry every match names the skip of each following page; ask for all of them in one reply, one call each, rather than one find per file.
limitNoMatching lines one result carries at most: a page, not a cap on the find. With more than this, the result names the skip of each following page; the result reports the total either way.
queryNoThe exact text to find, as it appears in the code - an identifier, a string, a key. Never a signature or a line you have not read: one character off and nothing matches.
tableNoWith `database`: the table to run over; its text column is the one searched.
underNoRepo-relative path prefix to scope to - one repository of a workspace, one subtree of a monorepo, one directory. The total and the per-file counts then describe that subtree, and the result echoes `under` so the numbers are not mistaken for the whole repository. Reach for it when a common name would return thousands of lines across everything: scoping is exact here, because find retrieves every match and cuts afterwards.
chunksNoUnset, each match comes in the block of code it sits in, trimmed to 4 lines around it, its lines numbered. true: the whole block - the chunk the index holds it in - for the body around a match; past two pages of whole blocks they are trimmed too, and the result says so. false: the matching line alone, as grep -n writes it - for a list of places or a count. A block holding several matches comes once, and overlapping blocks are not repeated. The text budget still applies; the matches of blocks past it are listed by path and line.
contextNoLines around each match to carry. Unset, each match comes in its block with 4 lines around it. With chunks true, each block keeps this many lines around its matches; given alone or with chunks false, the matching line comes with this many lines before and after it, as grep -B/-A shows. Up to 20; more than a few matches with context is a wide result.
definesNoKeep only lines inside a definition of the query - where the name is declared, not every place it is used. Answers 'where is X defined' in one call instead of reading use sites until one turns out to be the declaration. The result reports definedFrom, how many matching lines there were before the filter.
queriesNoSeveral exact strings in one call, found at the same time; the results come back in the same order, each under its query. Use it in place of one call per string.
databaseNoA database of the Infino account to run over instead of a repository: the names are what `tables` lists. With it, `path` is not read.
questionNoThe question you are answering, in the words it was asked. With it, over a hosted table, the platform's grader orders the hits for that question - a search takes a wider pool and returns the k it puts first - before they come back.
ignoreCaseNoMatch regardless of letter case. Default false: case-sensitive, like grep.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.6.0

TDQS

A4.4/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, so safety is covered; the description goes further by disclosing result shape (path:line:text, totals, per-file counts, 'usage' receipt), the 500-line page model with skip continuation, and trimming of blocks past the text budget. That is real behavioral value beyond the annotations, though the length and density make some of it hard to act on at call time.

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?

Purpose and the grep analogy are front-loaded, and nearly every sentence carries an operational instruction. It is nonetheless a single dense block that repeats the '... is one sql statement away' idea and the anti-pattern of reading per match more than once, which costs readability.

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?

For a 13-parameter tool with no output schema, the description covers the essentials: what the result looks like, how pagination works, how `chunks`/`context`/`defines` change output, what the 'usage' field is, and how to recover a line's text when trimmed. Nothing an agent needs in order to call it correctly appears 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 the baseline is 3; the description still adds operating guidance the schema does not, notably that queries must be literal (never a composed signature, '`refresh(` lists every refresh declared') and that every named page must be requested in the same reply via skip. It also distinguishes `path` from `under`, but largely restates schema-documented parameter behavior elsewhere.

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?

Names a specific verb and resource ('every line in the repository containing an exact string') and anchors it to a familiar analogue, grep -n, so the agent knows exactly what comes back. It explicitly separates itself from siblings: 'For meaning or "how does X work" use search; for rankings use sql.'

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?

Gives when-to-use ('every use or definition of an identifier, an error message, a config key'), when-not ('Not for a file you already know - read it... in one read call'), and named alternatives (search for meaning, sql for rankings/counts, read for known files). It also steers multi-string lookups to `queries` and paging to `skip` in one reply, closing the common misuse paths.

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