An AI agent that can search files and use tools is genuinely useful — it can answer questions about a codebase, find relevant documents, extract information, and chain multiple operations to solve problems.
This guide shows you how to build one from scratch, with practical patterns you can extend to your own use case.
Quick answer
Define tools for file listing, content search, and file reading. Connect them to an agent loop that decides which tool to call, processes the result, and continues until it has enough information to answer the question.
- You want to build a question-answering agent over a codebase or document set.
- You need an agent that can explore files dynamically rather than relying on pre-indexed content.
- You are learning how agent loops and tool use work in practice.
The agent loop pattern
Every tool-using agent follows the same basic loop: receive a question, decide which tool to call, process the result, and either call another tool or return an answer.
The key design decision is how much autonomy to give the agent. Start conservative — let it call tools but limit the number of steps, and always show the user what tools were called.
Essential file tools
For a file search agent, you need three core tools: list files (by pattern or directory), search content (grep-like text search), and read file (get the full content of a specific file).
These three tools are enough for an agent to navigate a codebase — it lists files to orient itself, searches for relevant terms, then reads the specific files it needs.
- list_files: accepts a directory and optional glob pattern, returns file paths
- search_content: accepts a query string and optional file pattern, returns matching lines with file paths
- read_file: accepts a file path, returns the file contents
Building the tools
Each tool is a function with a clear schema. The schema tells the agent what parameters to pass and what to expect back.
Keep the return values simple and consistent. For file listing, return paths. For search, return matching lines with context. For file reading, return the content with line numbers.
# Core file tools
def list_files(directory: str = ".", pattern: str = "*") -> str:
"""List files in a directory matching a glob pattern."""
import glob, os
files = glob.glob(os.path.join(directory, "**", pattern), recursive=True)
return "\n".join(files[:50])
def search_content(query: str, file_pattern: str = "*") -> str:
"""Search for text in files matching a pattern."""
# Use subprocess to call grep/rg for efficiency
...
def read_file(file_path: str) -> str:
"""Read and return the contents of a file."""
with open(file_path) as f:
return f.read()Connecting tools to the agent
Wire the tools into your agent framework. If using the Anthropic SDK, pass them as tool definitions. If using LangChain or a similar framework, register them as tools in the agent executor.
The critical step is writing good tool descriptions. The agent reads these descriptions to decide which tool to call, so vague descriptions lead to wrong tool choices.
Handling multi-step reasoning
The interesting part of file search agents is multi-step reasoning. The agent might search for a function name, find it in three files, read each one, then synthesise the answer.
Set a reasonable step limit (5-10 tool calls) and log each step. If the agent hits the limit without answering, it likely needs better tools or a more specific question.
Worked example: codebase Q&A agent
You build an agent with file tools and ask it 'How does the authentication middleware work?' The agent searches for 'auth' in the codebase, finds three relevant files, reads them, and returns a summary explaining the authentication flow with references to specific files and functions.
Common mistakes
- Giving the agent too many tools at once — start with the three core file tools.
- Writing vague tool descriptions that make the agent guess.
- Not setting a step limit, which can lead to runaway tool-calling loops.
When to use something else
If you need MCP-based tool servers instead of building tools directly, see MCP servers for AI agents. For RAG over documents instead of live file search, see building a RAG app.
Frequently asked questions
What is the core loop of a file-search agent?
Receive a question, decide which tool to call, run it, process the result, then either call another tool or answer. Repeat until it has enough information to respond.
What tools does a file-search agent need?
Three core ones: list files by pattern or directory, search content (grep-like), and read a file's full contents. Most file questions decompose into these.
How does the agent decide which tool to call?
From the tool descriptions and schemas plus the conversation. Clear, specific descriptions and tight parameter schemas are what make the choice reliable.
How do I stop the agent reading the whole repo?
Make search cheap and reads targeted: have it search first to find candidates, then read only the top files. Cap iterations and result sizes so it cannot spiral.
How should tools return results to the agent?
Structured and trimmed — file paths with line matches for search, not entire files. Give the model the minimum it needs to decide the next step.
How is this different from RAG?
RAG retrieves chunks by embedding similarity up front; an agent actively searches and reads files step by step, deciding what to look at next. Use an agent when the path to the answer is not known in advance.
Related guides on this site
These guides cover related agent patterns, tool calling, and document retrieval approaches.