Skip to content

feat(filesystem): say what an empty search_files result searched, and add realistic example patterns - #5620

Open
cliffhall wants to merge 1 commit into
v2/mainfrom
v2/feat/5553-filesystem-search-files-examples
Open

cliffhall wants to merge 1 commit into
v2/mainfrom
v2/feat/5553-filesystem-search-files-examples

Conversation

@cliffhall

Copy link
Copy Markdown
Member

Closes #5553

Description

Two changes to the filesystem server's search_files tool, both proposed in #5553:

  1. An empty result now says what was searched and how to widen it. A search that matched nothing returned exactly 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.
  2. Realistic example patterns. The tool description and the pattern input description carry '**/*.json' and '**/*report*' next to the generic '*.ext' / '**/name'.

Server Details

filesystem (@modelcontextprotocol/server-filesystem): the search_files tool's description, its pattern input 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:

  • The issue's headline number (realistic examples took a 4B model from 3/12 to 9/12) was measured on server 2.0.0. The reporter re-measured on 2.3.0 and found realistic examples alone no longer change the refusal rate (1/24 on main against 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.
  • The empty-result hint is the part that stands on its own. A bare No matches found is the same text whether the name does not exist or the pattern could not reach it, so a caller that sent *.json for 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 pattern input 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's git server 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 the pattern input 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, in content and structuredContent alike, and the suggested pattern then finds the file. Three existing exact-string assertions on No matches found became prefix matches.

Inspector CLI 2.9.0, built server over stdio, a directory holding orders/A17.json and orders/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:

pattern v2/main this branch
order*.json No matches found No 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.
**/*.csv No matches found No 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.
**/*.json the two paths the two paths (unchanged)

tools/list on 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, only mcp__filesystem__search_files allowed) against the branch build. The client has no era switch, so the era could not be selected. Prompt: call search_files with pattern A*.json on that directory, then do whatever the result suggests. It reported: "Second pattern: **/A*.json. The first search with A*.json matched 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:gate exits 0.

Breaking Changes

None to configuration. The empty result's text is longer: a client comparing it for equality with No matches found needs 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

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Protocol Documentation
  • My changes follow MCP security best practices (the hint echoes back only the caller's own pattern and path arguments, after path has passed validation)
  • I have updated the server's README accordingly
  • I have added a changeset (npm run changeset) if this changes what a TypeScript server publishes (patch)
  • I have tested this with an LLM client
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling (not applicable: no new failure path; an empty result is still a successful result)
  • I have documented all environment variables and configuration options (not applicable: none added)

Additional context

The suggestion is given only when the pattern contains no **. It does not promise a match: **/order*.json still finds nothing in the directory above, because the files are named A17.json and B42.json, and the text says the pattern matches names.

🤖 Generated with Claude Code

… 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-bot

changeset-bot Bot commented Nov 18, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 731abb0

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
@modelcontextprotocol/server-filesystem Patch

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

@cliffhall
cliffhall requested a balanced review from Copilot November 18, 2026 18:42
@github-actions

Copy link
Copy Markdown
Contributor

filesystem: MCP interface diff

Base: 7f383a8e0f34 (Merge pull request #5597 from modelcontextprotocol/changeset-release/v2/main)
Head: the build in this checkout, at 18582b8ea359 (Merge 731abb0 into 7f383a8)

Diffed because it was named (--server).

⚠️ Interface changes detected in 1 part(s) of the interface. Review them below to confirm they are intended.

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.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 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

@cliffhall

Copy link
Copy Markdown
Member Author

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.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

filesystem: realistic examples in search_files' description stop small models refusing to search (measured; follow-up to #896 / #3419)

2 participants