get_file_tree

What It Does

get_file_tree returns the directory structure of a codebase with metadata that raw find or ls -R cannot provide: symbol counts per file, file sizes, and language detection. It answers “what is in this directory?” with enough context to decide where to look next.

A typical find -type f | sort gives you file paths. get_file_tree tells you that src/services/risk.service.ts has 47 symbols (a complex file worth investigating) while src/utils/constants.ts has 3 (probably not interesting). This metadata drives navigation decisions without requiring any file reads.

Best Practice: First Call

In unfamiliar codebases, get_file_tree should be your first call. It costs 2K-10K tokens depending on project size (capped at 250 entries) and provides the orientation needed to make all subsequent searches targeted.

Without this map, an agent typically makes 3-5 exploratory grep calls to understand project structure. With it, the agent knows immediately where services, components, tests, and utilities live.

Key Parameters

• path_prefix — scope to a subdirectory (e.g., src/lib/services). Always use when you know the area of interest.
• compact — returns a flat list instead of a tree structure. Default true. Saves tokens for large directories.
• name_pattern — filter files by name (e.g., *.service.ts, route.ts). Returns only matching files, dramatically reducing output for targeted exploration.
• min_symbols — only show files with at least N symbols. Useful for finding complex files (min_symbols=20).

Token Cost

Project size	Approximate tokens
Small (<100 files)	~2,000
Medium (100-500 files)	~4,000
Large (500+ files)	~8,000 (capped at 250 entries)

The 250-entry cap prevents pathological output for monorepos. If a directory has more than 250 entries, use path_prefix to scope to a subdirectory or name_pattern to filter by file type.

Comparison With Native

get_file_tree costs slightly more tokens than a raw find command for the same directory. The additional cost comes from the symbol count metadata embedded in each line. However, this metadata eliminates the need for follow-up calls to understand file complexity, making the total workflow cheaper.

Approach	First call	Follow-up calls needed	Total cost
find -type f	~1,500 tok	3-5 greps for orientation	~6,000 tok
get_file_tree	~3,000 tok	0-1 targeted reads	~3,500 tok

In Combo Workflows

get_file_tree appears in the ft-st and st-ft-st combo patterns. The typical flow is: get the file tree to understand structure, then search_text to find specific code within the identified directories. The reverse (st-ft-st) happens when a text search reveals an unfamiliar directory that needs exploration.

When to Use Something Else

Use get_repo_outline when you need a higher-level summary — directory counts and symbol kind distributions rather than individual files.

Use suggest_queries for the cheapest possible orientation (~240 tokens) — it returns example queries and top files without the full tree.

Use get_file_outline when you already know which file to examine and need its internal structure.