Skip to main content
Glama

grep

Read-onlyIdempotent

Search indexed project files by literal string or regular expression to find log messages, config keys, or error text.

Instructions

Fast literal or regex string search across the project's indexed file set. Use this for log-message lookups, config-key searches, error-message tracing, or any time you know the exact characters you want to find. Use 'search' instead for semantic intent queries. Skips binary files; respects .gitignore via the indexed walker.

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": "grep"
  }
}

Input Schema

NameRequiredDescriptionDefault
globNoOptional file glob filter, e.g. "src/**/*.ts" or "*.md". Comma-separated for multiple.
rootNoAbsolute project root. Omit only where this session started; required elsewhere and on every subagent call.
regexNoTreat pattern as a line-based regular expression (set true for A|B alternation). Default: false, literal match.
patternYesLiteral string to search for (or regex when regex=true).
target_pathNoOptional subdirectory to scope the search.
context_charsNoCharacter window within the matched line; surrounding lines are clipped to this width. 40–400, default: 160. Use context_lines for nearby lines.
context_linesNoLines before and after each match (0–10, default: 0). Overlapping ranges are deduplicated; L<line>- marks context, L<line>:<column> marks a hit.
case_sensitiveNoMatch case-sensitively. Default: false.
max_file_bytesNoSkip files larger than this (bytes). Default: 1000000.
max_total_matchesNoMax total matches across all files. Default: 200.
max_matches_per_fileNoMax matches per file. Default: 10.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.6.0
    • changedInput schema / properties / root / description
      Previous value: -"Absolute project root. Required with linked worktrees; subagents must pass their own worktree root on every call."New value: +"Absolute project root. Omit only where this session started; required elsewhere and on every subagent call."
  2. First observedv1.4.0

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real behavior beyond that: binary files are skipped and .gitignore is respected via the indexed walker, which tells the agent what results it will not see. It stops short of describing result ordering, truncation behavior, or output shape, which keeps it below a 5.

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?

Three sentences, front-loaded with the core capability and closed with the key behavioral caveats (binary skip, gitignore). The middle sentence's list of example use cases is slightly padded but still earns its place as routing guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter read tool with full schema coverage and no output schema, the description covers purpose, routing, and search-scope caveats adequately. The only gap is return-format expectations, but the context_lines parameter description already explains the L<line> marker convention, so the burden is largely met elsewhere.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and all 11 parameters are individually documented in the schema, so the baseline is 3. The description only echoes the pattern/regex duality and adds no syntax, format, or default guidance beyond what the schema already states.

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?

The description opens with a specific verb and resource ("Fast literal or regex string search across the project's indexed file set") and immediately scopes it to indexed files, which distinguishes it from a filesystem-wide grep. It also names the sibling tool it is not ("Use 'search' instead for semantic intent queries"), so an agent can route between them without opening either schema.

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?

It gives concrete when-to-use cases (log-message lookups, config-key searches, error-message tracing, known exact characters) and an explicit when-not-to-use with the named alternative, 'search', for semantic intent queries. That is the full routing rule, not an implication.

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