Grep-Result Tool Output
For search or discovery tools, return matching lines or snippets rather than full directory trees or file contents. Let the model request specifics only when needed.
How It Works
A search tool returns only the lines that match the query, with file paths and line numbers. The model sees a compact list of hits and can then request the full content of specific files if it needs more context.
Benefits
- avoids sending large files or full directory listings when only a small portion is relevant
- lets the model direct its attention to specific locations
- reduces noise from irrelevant content
Example
Instead of returning the full content of 10 files:
{
"matches": [
{"file": "src/auth.py", "line": 42, "text": "def verify_token(token):"},
{"file": "src/middleware.py", "line": 15, "text": "token = request.headers.get('Authorization')"}
]
}
Anti-patterns
- Returning full file contents for every search hit.
- Sending complete directory trees when the model only asked for a specific symbol.
- Including file metadata (permissions, size, timestamps) that the model did not request.
See Also
- Diff-Based Tool Output — another minimal-output tool design pattern.
- Selective Context Inclusion — grep results are a form of selective inclusion for search.
- Structured Tool Output — grep results are often returned as structured JSON.
- Context Isolation via Subagents — the model-mediated version of the same goal: a subagent reads the haystack and returns the needles.
- Output Spooling to Disk — what the agent does when the tool returns everything anyway: spool it and query the file.