fix(filesystem): improve search_files description and performance #3419

Summary

The search_files tool description is ambiguous — LLMs frequently confuse it with a content search (grep) when it's actually a name-based file finder. This causes failed searches and poor user experience.

Originally raised in issues #896, #735, #1067, and extensively explored in PR #897 by @sebastien-rosset.

Proposed Changes

Based on the work in PR #897, adapted for the current registerTool() architecture:

1. Improve search_files tool description to clearly state it searches by file/directory name, not file contents. Clarify that it supports glob patterns and substring matching.

2. Improve search performance with parallel BFS directory traversal (breadth-first, processing directories in batches) instead of recursive DFS, for better performance in deeply nested directory trees.

3. Add comprehensive test coverage for the search function, including:

   • Glob pattern matching
   • Case sensitivity behavior
   • Exclude patterns
   • Directory traversal
   • Error handling for inaccessible directories

Context

PR #897 implemented these improvements thoroughly but is now stale (merge conflicts after the Nov 2025 architecture refactoring). The valuable ideas and approach should be carried forward in a fresh PR targeting the current codebase (searchFilesByName in lib.ts, registerTool() in index.ts).

Credit: @sebastien-rosset for the original research, implementation, and LLM testing that validated these improvements.

Related

• PR Rename "search_files" to "search_files_by_name" #897 (original implementation, to be closed after this is picked up)
• Issues Confusing search_files function description leads to misunderstanding of its purpose #896, "search_files" tool of Filesystem example MCP server does not work as expected #735, File server tool not finding files. #1067