Skip to main content
Glama

project_grep

Read-onlyIdempotent

Regex-search deployed authored source — every static source file and server function — and get back file:line matches in one call. The existing per-project call remains unchanged. Platform admins may instead pass scope:"live" (and omit project_id) to search every project currently serving production traffic (projects.status = 'deployed'). Release-pinned projects read their immutable release; other projects read their prod-slot authored source. Fleet responses report projects scanned/searched/skipped by reason, projects with no prod function script, and whether results were truncated. Every fleet hit carries the stable file/path/file_path, line/line_number, col/column, and text/matched_line compatibility fields.

pattern is a regular expression (not a literal substring). glob optionally scopes the search: a glob with no slash matches by filename (*.tsx → every .tsx file), one with a slash matches the path (api/** → just that folder).

Example:

{ "project_id": "my-saas", "pattern": "createClient\\(", "glob": "src/**" }
// Returns: {
//   project_id, env: "prod",
//   matches: [
//     { path: "src/lib/db.ts", line: 3, col: 18, text: "export const db = createClient(url, key)" }
//   ],
//   truncated: false, files_searched: 24
// }

Returns at most max_results matches (default 100, max 1000), capped per file too; truncated: true means a cap clipped the results — narrow the pattern or glob. Searches the live prod source by default. Explicit env: "dev" requires hosted preview access for signed-in accounts on every plan.

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": {
      "pattern": "<pattern>"
    },
    "name": "project_grep"
  }
}

Input Schema

NameRequiredDescriptionDefault
envNoWhich environment's source to search. Defaults to "prod" (live). Explicit "dev" requires hosted preview access for signed-in accounts on every plan.
globNoOptional path filter. No-slash globs match the filename ("*.ts"); slashed globs match the path ("api/**", "src/components/*.tsx").
scopeNoAdmin-only. Search every live project instead of one project; project_id is omitted.
patternYesA regular expression to search for (e.g. "export function \\w+", "TODO|FIXME"). Backreferences, lookaround, and non-ASCII characters inside [...] with case_insensitive are not supported; a search that runs too long returns SEARCH_PATTERN_TOO_SLOW (simplify the pattern or search plain text).
preview_idNoExact current candidate of preview_session_id. Both fields are required together.
project_idNoProject ID, slug, subdomain, or 'default'.
max_resultsNoCap on total matches returned. Default 100, max 1000.
case_insensitiveNoMatch case-insensitively. Default false.
preview_session_idNoExact open preview session paired with preview_id and env:"dev". It does not fall back to another source.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.4/5.0
Behavior5/5

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

Beyond the readOnly/idempotent annotations, it discloses substantial behavior: which source is read per project state (release-pinned vs prod-slot), that responses report scanned/searched/skipped projects and truncation, and the compatibility field aliases on fleet hits. It also surfaces real failure modes the annotations cannot — unsupported regex features (backreferences, lookaround) and SEARCH_PATTERN_TOO_SLOW.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

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

Front-loads the core purpose and the fleet-mode distinction, then layers regex/glob semantics, a compact worked example with return shape, and cap/truncation behavior. The example earns its space by conveying the response envelope that no output schema provides.

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 9-parameter tool with no output schema, the description covers mode selection, env access requirements, regex limitations, result caps, truncation semantics, and even the returned match/project fields. An agent can call this correctly without opening the schema.

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 baseline is 3, and the description adds real meaning on top: `pattern` is a regex not a literal, no-slash globs match filenames while slashed globs match paths, and caps apply per-file as well as overall. Much of this overlaps the schema's own parameter descriptions, and preview_id/preview_session_id pairing is left to the schema.

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?

States a specific verb and resource: regex-search over deployed authored source, returning `file:line` matches, with a per-project mode and an admin `scope:"live"` fleet mode. It never names a sibling tool (e.g. project_file_read or project_files_list) to differentiate against, so an agent must infer when grep is preferable to reading files.

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?

Clear conditions are given for the modes: default is the project's live prod source, `scope:"live"` is admin-only and requires omitting project_id, and `env:"dev"` requires hosted preview access. It also advises narrowing `pattern` or `glob` when `truncated: true`. No guidance is given on when to prefer this over sibling file-listing/reading tools.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources