Skip to main content

Documentation Index

Fetch the complete documentation index at: https://septemberai.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

The Engine ships several built-in file-search tools — grep, find, and a higher-level file_search that combines pattern matching with semantic relevance ranking. Together they give the agent the ability to work in a codebase or document collection it didn’t author.

​
What’s available

ToolPurpose
grepRegex search across files. Returns matching lines with file path and line number. Fast, exact.
findFilesystem traversal by name pattern, type, time, size.
read_fileRead a specific file by path. Returns the contents (with size cap).
file_searchSemantic + keyword hybrid search across a directory. Useful when you don’t know the exact pattern.
The agent picks among them based on what it knows.

​
Allowed paths

All file tools respect ALLOWED_ROOTS. The agent can search and read within the configured roots; everything else is invisible. There is no “how do I escape this” — landlock enforces the boundary at the kernel.

​
Patterns

​
grep before read_file

When the agent is hunting for a symbol: 
1. grep "def handle_login" src/  → returns auth.py:42
2. read_file src/auth.py        → reads the function
This is two cheap calls instead of one expensive (read every file) call.

​
find before grep

When the agent doesn’t know which directory to search: 
1. find . -name "*.py" -newer 7d → recent Python files
2. grep ... in those files only

​
file_search for fuzzy intent

When the user’s question is conceptual (“where do we handle rate limits?”) and there’s no obvious string to grep for: 
1. file_search "rate limit handling" → ranked list of relevant files
2. read_file the top-ranked one
file_search uses the same hybrid scoring as memory search — vector similarity + keyword. Useful for codebases, documentation, content libraries.

​
Output limits

Tools cap output to keep context tidy:
  • grep truncates at ~100 matches by default. Tighten the pattern if you want more.
  • read_file caps at ~50 KB. Larger files are paginated; the agent asks for next pages.
  • file_search returns the top 10–20 results with snippets, not full files.

​
Pitfalls

  • Searching the world. A grep -r "x" / scans everything readable and wastes time. Use find first to scope.
  • Reading a 5 MB file. Pagination handles it, but the agent often doesn’t realize it’s reading a giant file until it’s burned context on the first page. Use find -size to check before reading.
  • Binary files. grep and read_file skip binaries; the agent sees an empty/error result. If the agent is confused, it usually guessed at a filename that turned out to be binary.

​
See also