agent-tool

Overview Schema Source Related Servers Discussions Admin

grep

Search files and directories using regular expressions with context, glob filters, and output modes. Avoids binary files and respects ignored paths for targeted results.

Instructions

Regex-search encoding-aware files or directories. Supports context, glob filters, content/file/count modes, ignored-path controls, and bounded pageable output. Directory searches skip detected binaries; explicit files are searched.

Input Schema

TableJSON Schema

Name	Required	Description
`glob`	No	Directory file filter, e.g. *.go
`path`	No	File or directory; defaults to workspace/MCP root/CWD
`after`	No	Lines after; overrides context
`before`	No	Lines before; overrides context
`cursor`	No	Continuation cursor; incompatible with context lines
`context`	No	Lines before/after; max 1000
`pattern`	Yes	Regular expression
`file_path`	No	Alias for path
`recursive`	No	Recurse; default true
`ignore_case`	No	Ignore case
`max_results`	No	Matches per page; default 100, max 100000
`output_mode`	No	content (default), files_with_matches, or count
`output_format`	No	compact (default) or classic path:line:text
`include_hidden`	No	Include hidden directories
`max_line_chars`	No	Per-line cap; default 4000, max 32768
`relative_paths`	No	Paths relative to root; directory default true
`include_ignored`	No	Include ignored/generated/vendor paths
`max_output_chars`	No	Output cap; default 32768, max 131072

Schema Changelog

Changes observed during successful MCP inspections.

Changed17 schema fields changedv0.9.7Sep 16, 2026

changedInput schema / properties / after / description

Previous value: -"Lines after each match. Overrides context. Default: 0, Max: 1000"New value: +"Lines after; overrides context"

changedInput schema / properties / before / description

Previous value: -"Lines before each match. Overrides context. Default: 0, Max: 1000"New value: +"Lines before; overrides context"

changedInput schema / properties / context / description

Previous value: -"Lines before and after each match (like grep -C). Default: 0, Max: 1000"New value: +"Lines before/after; max 1000"

changedInput schema / properties / cursor / description

Previous value: -"Opaque continuation cursor returned by a previous grep call. Not supported with context lines"New value: +"Continuation cursor; incompatible with context lines"

changedInput schema / properties / glob / description

Previous value: -"Glob pattern to filter files (e.g. *.go). Only used when path is a directory"New value: +"Directory file filter, e.g. *.go"

changedInput schema / properties / ignore_case / description

Previous value: -"Case-insensitive search. Default: false"New value: +"Ignore case"

changedInput schema / properties / include_hidden / description

Previous value: -"Search hidden directories. Explicitly provided hidden roots are always searched. Default: false"New value: +"Include hidden directories"

changedInput schema / properties / include_ignored / description

Previous value: -"Search common generated/vendor directories instead of skipping them. Default: false"New value: +"Include ignored/generated/vendor paths"

changedInput schema / properties / max_line_chars / description

Previous value: -"Maximum characters per matching/context line. Default: 4000, Max: 32768"New value: +"Per-line cap; default 4000, max 32768"

changedInput schema / properties / max_output_chars / description

Previous value: -"Maximum total result characters. Default: 32768, Max: 131072"New value: +"Output cap; default 32768, max 131072"

changedInput schema / properties / max_results / description

Previous value: -"Maximum matching lines/files per page. Default: 100, Max: 100000"New value: +"Matches per page; default 100, max 100000"

changedInput schema / properties / output_format / description

Previous value: -"Content layout: compact (group matches by file, default) or classic (path:line:text on every line)"New value: +"compact (default) or classic path:line:text"

changedInput schema / properties / output_mode / description

Previous value: -"Output mode: content (default), files_with_matches, or count"New value: +"content (default), files_with_matches, or count"

changedInput schema / properties / path / description

Previous value: -"File or directory to search. Defaults to configured workspace, MCP client root, or current directory"New value: +"File or directory; defaults to workspace/MCP root/CWD"

changedInput schema / properties / pattern / description

Previous value: -"Regular expression pattern to search for"New value: +"Regular expression"

changedInput schema / properties / recursive / description

Previous value: -"Recurse into subdirectories. Default: true"New value: +"Recurse; default true"

changedInput schema / properties / relative_paths / description

Previous value: -"Return paths relative to the search root. Default: true for directory searches"New value: +"Paths relative to root; directory default true"

Changed21 schema fields changedv0.9.5Aug 25, 2026

changedInput schema / properties / after / description

Previous value: -"Lines of context after each match (like grep -A). Overrides context. Default: 0"New value: +"Lines after each match. Overrides context. Default: 0, Max: 1000"

addedInput schema / properties / after / type
```
Added value: +"integer"
```

changedInput schema / properties / before / description

Previous value: -"Lines of context before each match (like grep -B). Overrides context. Default: 0"New value: +"Lines before each match. Overrides context. Default: 0, Max: 1000"

addedInput schema / properties / before / type
```
Added value: +"integer"
```

changedInput schema / properties / context / description

Previous value: -"Lines of context before and after each match (like grep -C). Default: 0"New value: +"Lines before and after each match (like grep -C). Default: 0, Max: 1000"

addedInput schema / properties / context / type
```
Added value: +"integer"
```

addedInput schema / properties / cursor

Added value: +{
+  "description": "Opaque continuation cursor returned by a previous grep call. Not supported with context lines",
+  "type": "string"
+}

changedInput schema / properties / ignore_case / description

Previous value: -"Case insensitive search: true or false. Default: false"New value: +"Case-insensitive search. Default: false"

addedInput schema / properties / ignore_case / type
```
Added value: +"boolean"
```

addedInput schema / properties / include_hidden

Added value: +{
+  "description": "Search hidden directories. Explicitly provided hidden roots are always searched. Default: false",
+  "type": "boolean"
+}

addedInput schema / properties / include_ignored

Added value: +{
+  "description": "Search common generated/vendor directories instead of skipping them. Default: false",
+  "type": "boolean"
+}

addedInput schema / properties / max_line_chars

Added value: +{
+  "description": "Maximum characters per matching/context line. Default: 4000, Max: 32768",
+  "type": "integer"
+}

addedInput schema / properties / max_output_chars

Added value: +{
+  "description": "Maximum total result characters. Default: 32768, Max: 131072",
+  "type": "integer"
+}

changedInput schema / properties / max_results / description

Previous value: -"Maximum number of matching lines/files to return. Default: 100"New value: +"Maximum matching lines/files per page. Default: 100, Max: 100000"

addedInput schema / properties / max_results / type
```
Added value: +"integer"
```

addedInput schema / properties / output_format

Added value: +{
+  "description": "Content layout: compact (group matches by file, default) or classic (path:line:text on every line)",
+  "type": "string"
+}

changedInput schema / properties / output_mode / description

Previous value: -"Output mode: 'content' (matching lines with path:line:text, default), 'files_with_matches' (file paths only), 'count' (match count per file)"New value: +"Output mode: content (default), files_with_matches, or count"

changedInput schema / properties / path / description

Previous value: -"File or directory to search in (absolute path). Defaults to current directory"New value: +"File or directory to search. Defaults to configured workspace, MCP client root, or current directory"

changedInput schema / properties / recursive / description

Previous value: -"Recurse into subdirectories: true or false. Default: true"New value: +"Recurse into subdirectories. Default: true"

addedInput schema / properties / recursive / type
```
Added value: +[
+  "null",
+  "boolean"
+]
```

addedInput schema / properties / relative_paths

Added value: +{
+  "description": "Return paths relative to the search root. Default: true for directory searches",
+  "type": [
+    "null",
+    "boolean"
+  ]
+}

Addedv0.8.7May 6, 2026
RemovedApr 30, 2026

Changed6 schema fields changedv0.7.12Mar 26, 2026

addedInput schema / properties / after

Added value: +{
+  "description": "Lines of context after each match (like grep -A). Overrides context. Default: 0",
+  "type": "integer"
+}

addedInput schema / properties / before

Added value: +{
+  "description": "Lines of context before each match (like grep -B). Overrides context. Default: 0",
+  "type": "integer"
+}

addedInput schema / properties / context

Added value: +{
+  "description": "Lines of context before and after each match (like grep -C). Default: 0",
+  "type": "integer"
+}

changedInput schema / properties / max_results / description

Previous value: -"Maximum number of matching lines to return. Default: 100"New value: +"Maximum number of matching lines/files to return. Default: 100"

addedInput schema / properties / output_mode

Added value: +{
+  "description": "Output mode: 'content' (matching lines with path:line:text, default), 'files_with_matches' (file paths only), 'count' (match count per file)",
+  "type": "string"
+}

changedOutput schema / (root)

Previous value: -{
-  "additionalProperties": false,
-  "properties": {
-    "count": {
-      "type": "integer"
-    },
-    "matches": {
-      "items": {
-        "type": "string"
-      },
-      "type": [
-        "null",
-        "array"
-      ]
-    }
-  },
-  "required": [
-    "matches",
-    "count"
-  ],
-  "type": "object"
-}New value: +null

First observedv0.4.2Mar 14, 2026

TDQS

A4/5.0

Behavior4/5

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

With no annotations, the description carries the full burden and does a strong job: it discloses encoding-awareness, binary skipping in directories, bounded pagination, ignored-path controls, and output modes. It does not mention rate limits or auth, but for a read-only search tool, this is comprehensive. No contradiction with annotations since none exist.

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?

Two sentences, front-loaded with the core purpose, and every clause adds value (modes, filters, output behavior, binary handling). No fluff, well-structured for quick parsing.

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?

Despite 18 parameters and no output schema, the description covers the major behavioral areas (search scope, filters, pagination, binary handling). It does not explicitly mention incompatibilities like cursor vs. context, but those are captured in the schema. The description is sufficient for an agent to understand the tool's role and invoke it correctly.

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%, so the schema already documents every parameter. The description adds high-level context (e.g., 'context, glob filters, content/file/count modes') that maps to parameters but does not explain each individually. It does not go beyond the schema, so a baseline 3 is appropriate.

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 clearly states a specific verb ('Regex-search') and resource ('encoding-aware files or directories'), and enumerates key features that distinguish it from siblings like glob (which finds filenames) and read (which reads content). It leaves no ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage via feature list but does not explicitly state when to use grep versus alternatives (e.g., 'use for content search, not filename matching'). It does clarify directory vs. explicit file behavior, but lacks direct routing guidance or exclusions, so the agent must infer from sibling names.

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

Deploy Server

grep

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools