Repository navigation
feat(filesystem): say what an empty search_files result searched, and add realistic example patterns - #5620
feat(filesystem): say what an empty search_files result searched, and add realistic example patterns#5620cliffhall wants to merge 1 commit into
Conversation
… add realistic example patterns
A search that matched nothing returned a bare "No matches found", which
gives a caller nothing to correct its pattern with: a model that passed
'*.json' for a file in a subdirectory had no signal that the pattern
cannot reach it. The result still begins with those words, and now names
the pattern and the directory, restates that the pattern is a
case-sensitive glob over names relative to that directory (never file
contents), and, for a pattern with no '**', suggests the '**/' form that
matches at any depth.
The tool description and the pattern input also carry realistic example
patterns ('**/*.json', '**/*report*') next to the generic ones.
Closes #5553
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Signed-off-by: cliffhall <cliff@futurescale.com>
🦋 Changeset detectedLatest commit: 731abb0 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
| Tools | Prompts | Resources | Resource templates | |
|---|---|---|---|---|
| Base | 16 | 0 | 0 | 1 |
| Head | 16 | 0 | 0 | 1 |
tools
--- base/tools.json
+++ target/tools.json
- tools[search_files].description: "Find files and directories by NAME, not by content: this tool never reads or searches inside files. ..."
+ tools[search_files].description: "Find files and directories by NAME, not by content: this tool never reads or searches inside files. ..."
- tools[search_files].inputSchema.properties.pattern.description: "Glob matched against each entry's path relative to path, never its content: '*.ts' matches directly ..."
+ tools[search_files].inputSchema.properties.pattern.description: "Glob matched against each entry's path relative to path, never its content: '*.ts' matches directly ..."
Updated by this run for 731abb0a1ea3e5dc0075c0ff95f0e21a27691b50.
There was a problem hiding this comment.
🟢 Approval recommended
No active review issues block the empty-search guidance changes.
No open issues 🎉
What changed in this PR
Improves the filesystem server’s search_files guidance for empty searches, addressing #5553 without changing matching behavior or the tool’s schema. The PR does not claim to resolve small-model search refusals.
Changes:
- Expands empty results with the searched pattern, directory, matching rules, and a
**/suggestion when the pattern contains no**. - Adds realistic glob examples to tool guidance and documents the new response.
- Adds protocol-level coverage, updates existing assertions, and includes a patch changeset.
| File | Description |
|---|---|
src/filesystem/server.ts |
Adds empty-result guidance and realistic pattern examples. |
src/filesystem/README.md |
Documents examples and expanded empty results. |
src/filesystem/__tests__/server-tools.test.ts |
Updates the empty-result assertion. |
src/filesystem/__tests__/search-unreadable.test.ts |
Preserves coverage of incomplete-search notes with the new text. |
src/filesystem/__tests__/search-files-description.test.ts |
Tests examples, empty-result wording, and suggested-pattern behavior. |
src/filesystem/__tests__/exclude-glob-prunes-dir.test.ts |
Updates the empty-result assertion for excluded directories. |
.changeset/search-files-empty-result-hint.md |
Records the filesystem package’s patch release changes. |
Review effort: Balanced
|
Copilot round 1: clean (approval recommended, no comments, no suppressed comments). The review loop ends here on the first clean round; nothing was pushed after it. |
Closes #5553
Description
Two changes to the filesystem server's
search_filestool, both proposed in #5553:No matches found. The result still begins with those three words, and now names the pattern and the directory, restates that the pattern is a case-sensitive glob over names relative to that directory (never file contents), and, when the pattern has no**(so it only matches at one depth), suggests the**/<pattern>form that matches at any depth.patterninput description carry'**/*.json'and'**/*report*'next to the generic'*.ext'/'**/name'.Server Details
filesystem(@modelcontextprotocol/server-filesystem): thesearch_filestool's description, itspatterninput description, and the text of its empty result. No tool, argument or schema is added, removed or renamed.Motivation and Context
#5553, and the reporter's later correction on it, which changes what this PR can claim:
mainagainst 2/12 with examples). This PR does not claim to fix the "small model refuses to search" behavior, and nobody has a measured fix for it on current code. The examples are included as a small clarity improvement, which is how the reporter describes them too.No matches foundis the same text whether the name does not exist or the pattern could not reach it, so a caller that sent*.jsonfor a file in a subdirectory gets no signal to change the pattern. The reporter's traces show a model repeating non-recursive patterns after it (on 2.0.0, whose description said "Recursively search"). The 2.2.0 description already states the rule; this puts it at the point of failure as well, for a caller that did not take it from the description.The idea of adding the examples to the
patterninput description as well as the tool description comes from @shivamm-gupta's prototype on the issue. This PR is written independently and does not include that prototype'sgitserver change (#5552).How Has This Been Tested?
Not measured: the effect on a small model. No local small model was available here (no Ollama or other local runtime), so the reporter's A/B was not re-run. The reporter offered on the issue to run candidate wording through the same suite.
Tests (
src/filesystem/__tests__/search-files-description.test.ts, through an MCP client over the in-memory transport): the description and thepatterninput carry the examples and each example matches as described; an empty search with a**pattern returns the base text; an empty search with no**returns the base text plus the suggestion, incontentandstructuredContentalike, and the suggested pattern then finds the file. Three existing exact-string assertions onNo matches foundbecame prefix matches.Inspector CLI 2.9.0, built server over stdio, a directory holding
orders/A17.jsonandorders/B42.json, each run with--protocol-era legacy(2025-11-25) and--protocol-era modern(2026-07-28), all exit 0 and identical text in both eras:patternv2/mainorder*.jsonNo matches foundNo matches found for pattern 'order*.json' under <dir>. The pattern is a glob matched case-sensitively against each entry's path relative to that directory: it matches names, never file contents. It has no '**', so it only matches at one depth ('*.ext' only directly under the directory); try '**/order*.json' to match at any depth.**/*.csvNo matches foundNo matches found for pattern '**/*.csv' under <dir>. The pattern is a glob matched case-sensitively against each entry's path relative to that directory: it matches names, never file contents.**/*.jsontools/liston the branch shows the new description:… Use '*.ext' to match entries directly under 'path', and '**/*.ext' or '**/name' to match at any depth: for example, '**/*.json' finds every JSON file and '**/*report*' every entry with 'report' in its name. …LLM client: Claude Code 2.1.327 headless (
claude -p --model haiku --strict-mcp-config, onlymcp__filesystem__search_filesallowed) against the branch build. The client has no era switch, so the era could not be selected. Prompt: callsearch_fileswith patternA*.jsonon that directory, then do whatever the result suggests. It reported: "Second pattern:**/A*.json. The first search withA*.jsonmatched nothing because it only checks the top level … The tool's error message suggested**/A*.json", and returned<dir>/orders/A17.json. This is a capable model, so it shows the result is read and acted on, not that a small model's behavior changes.npm run local:gateexits 0.Breaking Changes
None to configuration. The empty result's text is longer: a client comparing it for equality with
No matches foundneeds a prefix match instead. It still begins with those words and is still a single paragraph, followed as before by the "search is incomplete" note when directories could not be read.Types of changes
Checklist
patternandpatharguments, afterpathhas passed validation)npm run changeset) if this changes what a TypeScript server publishes (patch)Additional context
The suggestion is given only when the pattern contains no
**. It does not promise a match:**/order*.jsonstill finds nothing in the directory above, because the files are namedA17.jsonandB42.json, and the text says the pattern matches names.🤖 Generated with Claude Code