modelcontextprotocol / modelcontextprotocol/servers
Confusing `search_files` function description leads to misunderstanding of its purpose
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 90.5k
- Forks
- 11.7k
- Avg merge
- 2d 2h
- Merged PRs (30d)
- 5
Description
Describe the bug
The description of the search_files function is ambiguous and easily misinterpreted. It suggests it might search file contents (like grep) when it actually only searches file and directory names. Claude itself is misinterpreting the function to search content in files, rather than file names matching input patterns.
Why it's confusing
The function description starts with "Recursively search for files and directories matching a pattern." This phrasing is ambiguous - it could mean either:
- Search for files/directories whose names match a pattern (actual behavior)
- Search recursively through directories for files containing content that matches a pattern (grep-like behavior many users expect)
This ambiguity leads to confusion when users (and Claude) attempt to use the function to search file contents and receive "No matches found" despite knowing the content exists in the files.
To Reproduce
- Install Claude desktop for Mac Version 0.8.1
- Install and configure the
filesystemserver. Cleanup npm cache just to be sure the latest version is installed. - Ask Claude desktop to search for content in files. Or ask Claude to refactor code, which typically leads Claude to try to "grep" content recursively in a directory.
- Notice Claude uses the
search_filesfunction to find content inside the files. Notice no matching content is found.
{
"path": "/Users/my_userid/my_project_path/",
"pattern": "mysearch"
}
No matches found
Expected behavior
Claude should not use the search_files function to search for content.
Additional context
Both Claude and human users may misinterpret this function as a content search tool (like grep) rather than a file/directory name matcher. The suggested description makes the distinction clear from the beginning and explicitly notes that it doesn't search file contents.
Suggested functions
-
search_files_by_name:
"Find files and directories whose names match a pattern. Searches recursively
through all subdirectories from the starting path. The search is case-insensitive
and matches partial file or directory names. Returns full paths to all items with
matching names. Great for finding files when you don't know their exact location.
Only searches within allowed directories." -
search_file_contents:
"Search for text patterns within file contents. Recursively examines all files
under the specified directory and returns paths to files containing the search
pattern. Functions similar to 'grep' command. The search can be case-sensitive
or insensitive based on parameters. Returns matching file paths along with line
numbers and context. Only searches within allowed directories."
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Locate the filesystem server entry point that defines the search_files tool and read its current description and schema. Update the wording so it clearly says the tool matches file and directory names, not file contents, then verify the documented behavior matches the existing name-search results.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 64/100