From 731abb0a1ea3e5dc0075c0ff95f0e21a27691b50 Mon Sep 17 00:00:00 2001 From: cliffhall Date: Wed, 18 Nov 2026 12:57:51 -0500 Subject: [PATCH] feat(filesystem): say what an empty search_files result searched, and 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 Signed-off-by: cliffhall --- .changeset/search-files-empty-result-hint.md | 5 ++ src/filesystem/README.md | 8 ++- .../__tests__/exclude-glob-prunes-dir.test.ts | 2 +- .../search-files-description.test.ts | 55 ++++++++++++++++++- .../__tests__/search-unreadable.test.ts | 2 +- src/filesystem/__tests__/server-tools.test.ts | 2 +- src/filesystem/server.ts | 25 ++++++++- 7 files changed, 91 insertions(+), 8 deletions(-) create mode 100644 .changeset/search-files-empty-result-hint.md diff --git a/.changeset/search-files-empty-result-hint.md b/.changeset/search-files-empty-result-hint.md new file mode 100644 index 0000000000..162ef9b4ad --- /dev/null +++ b/.changeset/search-files-empty-result-hint.md @@ -0,0 +1,5 @@ +--- +"@modelcontextprotocol/server-filesystem": patch +--- + +`search_files` no longer answers a search that matched nothing with a bare `No matches found`. The result still begins with those words, and now names the pattern and the directory searched, says 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 reaches subdirectories. The tool's description and its `pattern` input also gain realistic example patterns (`**/*.json`, `**/*report*`) next to the generic ones. diff --git a/src/filesystem/README.md b/src/filesystem/README.md index 0335ff5551..229d708b37 100644 --- a/src/filesystem/README.md +++ b/src/filesystem/README.md @@ -283,7 +283,9 @@ Files inside the allowed directories are also [resources](https://modelcontextpr - `path` (string): Starting directory - `pattern` (string): Glob matched, case-sensitively, against each entry's path relative to `path`: `*.ext` matches entries directly under `path`, - `**/*.ext` or `**/name` matches at any depth + `**/*.ext` or `**/name` matches at any depth. For example, `**/*.json` + finds every JSON file and `**/*report*` every entry with `report` in its + name - `excludePatterns` (string[]): Entries to leave out, read the same way as `directory_tree`'s. A bare name such as `node_modules` excludes an entry of that name at any depth and everything below it; it matches whole @@ -297,6 +299,10 @@ Files inside the allowed directories are also [resources](https://modelcontextpr entirely. - Glob-style pattern matching - Returns full paths to matches + - When nothing matches, the result begins `No matches found` and goes on to + name the pattern and the directory searched and to say how the pattern is + read. For a pattern with no `**`, which only matches at one depth, it also + suggests the `**/` form that matches at any depth - Bounded: see [Slow and very large trees](#slow-and-very-large-trees) - A subdirectory that cannot be read (no permission, say) is skipped, and the result says so: after the matches, a note that the search is incomplete diff --git a/src/filesystem/__tests__/exclude-glob-prunes-dir.test.ts b/src/filesystem/__tests__/exclude-glob-prunes-dir.test.ts index c520bacbb6..00c3d899ea 100644 --- a/src/filesystem/__tests__/exclude-glob-prunes-dir.test.ts +++ b/src/filesystem/__tests__/exclude-glob-prunes-dir.test.ts @@ -140,7 +140,7 @@ describe('excludePatterns ending in "/**" (#5445)', () => { excludePatterns: ["**/node_modules/**"], }); expect(result.isError).toBeFalsy(); - expect(textOf(result)).toBe("No matches found"); + expect(textOf(result)).toMatch(/^No matches found for pattern /); }); it("directory_tree does not list the excluded directory, even as empty", async () => { diff --git a/src/filesystem/__tests__/search-files-description.test.ts b/src/filesystem/__tests__/search-files-description.test.ts index 5c0401f6b7..57a5b8f48b 100644 --- a/src/filesystem/__tests__/search-files-description.test.ts +++ b/src/filesystem/__tests__/search-files-description.test.ts @@ -4,6 +4,13 @@ // the files, so the description now says the tool matches names, never // contents. These tests pin that wording and each matching rule it states, so // the description cannot drift from the behavior again. +// +// They also pin the realistic example patterns the description carries next to +// the generic ones, and what an empty result says (#5553): a bare "No matches +// found" gave a model nothing to correct a pattern with, so it repeated +// '*.ext' patterns that cannot reach a subdirectory. The empty result now +// names the pattern and the directory, restates how the pattern is read, and +// suggests the '**/' form when the pattern has no '**'. import fs from "fs/promises"; import path from "path"; @@ -61,8 +68,54 @@ describe("search_files description (#896, #3419)", () => { expect(description).not.toContain("working directory"); }); + it("gives realistic example patterns, each of which matches as described", async () => { + const { tools } = await client.listTools(); + const tool = tools.find((t) => t.name === "search_files"); + expect(tool?.description).toContain("'**/*.json'"); + expect(tool?.description).toContain("'**/*report*'"); + const properties = tool?.inputSchema.properties as Record< + string, + { description?: string } + >; + expect(properties.pattern.description).toContain("'**/*report*'"); + + await fs.writeFile(path.join(dir, "src", "config", "app.json"), ""); + await fs.writeFile(path.join(dir, "src", "q3-report-final.txt"), ""); + expect(await search("**/*.json")).toEqual([ + path.join(dir, "src", "config", "app.json"), + ]); + expect(await search("**/*report*")).toEqual([ + path.join(dir, "src", "q3-report-final.txt"), + ]); + }); + it("does not match a file's contents", async () => { - expect(await search("**/needle")).toEqual(["No matches found"]); + expect(await search("**/needle")).toEqual([ + `No matches found for pattern '**/needle' 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("suggests the '**/' form when an empty search's pattern has no '**'", async () => { + const result = await call(client, "search_files", { + path: dir, + pattern: "app*.md", + }); + expect(result.isError).toBeFalsy(); + const text = textOf(result); + expect(text).toBe( + `No matches found for pattern 'app*.md' 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 '**/app*.md' to match at any depth.", + ); + expect(result.structuredContent).toEqual({ content: text }); + // The suggested pattern is one that works. + expect(await search("**/app*.md")).toEqual([ + path.join(dir, "src", "app.md"), + ]); }); it("matches '*.ext' only directly under path", async () => { diff --git a/src/filesystem/__tests__/search-unreadable.test.ts b/src/filesystem/__tests__/search-unreadable.test.ts index 9b0d1fbe45..4febd94528 100644 --- a/src/filesystem/__tests__/search-unreadable.test.ts +++ b/src/filesystem/__tests__/search-unreadable.test.ts @@ -100,7 +100,7 @@ describe("search_files with an unreadable subdirectory (#5189)", () => { }); expect(result.isError).toBeFalsy(); const [matches, note] = textOf(result).split("\n\n"); - expect(matches).toBe("No matches found"); + expect(matches).toMatch(/^No matches found for pattern /); const [heading, ...listed] = note.split("\n"); expect(heading).toBe( "The search is incomplete: 2 directories could not be read, and any matches inside are missing:", diff --git a/src/filesystem/__tests__/server-tools.test.ts b/src/filesystem/__tests__/server-tools.test.ts index fb7152c54b..eadae875a4 100644 --- a/src/filesystem/__tests__/server-tools.test.ts +++ b/src/filesystem/__tests__/server-tools.test.ts @@ -2122,7 +2122,7 @@ describe("search_files", () => { path: dir, pattern: "*.none", }); - expect(textOf(result)).toBe("No matches found"); + expect(textOf(result)).toMatch(/^No matches found for pattern '\*\.none' /); }); it("silently skips a symlink that leaves the allowed directories", async () => { diff --git a/src/filesystem/server.ts b/src/filesystem/server.ts index f9a80d30be..67b03e8cf7 100644 --- a/src/filesystem/server.ts +++ b/src/filesystem/server.ts @@ -190,7 +190,8 @@ const SearchFilesArgsSchema = z.object({ .string() .describe( "Glob matched against each entry's path relative to path, never its content: " + - "'*.ts' matches directly under path, '**/*.ts' at any depth.", + "'*.ts' matches directly under path, '**/*.ts' at any depth, " + + "'**/*report*' any name containing 'report'.", ), excludePatterns: z .array(z.string()) @@ -1030,7 +1031,8 @@ export function createServer( description: "Find files and directories by NAME, not by content: this tool never reads or searches inside files. " + "It walks the tree under 'path' and matches a glob pattern against each entry's path relative to 'path' (case-sensitive). " + - "Use '*.ext' to match entries directly under 'path', and '**/*.ext' or '**/name' to match at any depth. " + + "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. " + "Returns full paths to all matching items. Great for finding files when you don't know their exact location. " + "Only searches within allowed directories.", inputSchema: jsonSchema2020(SearchFilesArgsSchema.shape), @@ -1063,7 +1065,24 @@ export function createServer( }, }, ); - let text = results.length > 0 ? results.join("\n") : "No matches found"; + // An empty result says what was searched and how the pattern is read, + // and how to widen a pattern that cannot reach subdirectories: a bare + // "No matches found" left a model repeating the same '*.ext' pattern + // (#5553). It stays one paragraph, opening with those three words. + let text: string; + if (results.length > 0) { + text = results.join("\n"); + } else { + text = + `No matches found for pattern '${args.pattern}' under ${args.path}. ` + + "The pattern is a glob matched case-sensitively against each entry's path " + + "relative to that directory: it matches names, never file contents."; + if (!args.pattern.includes("**")) { + text += + " It has no '**', so it only matches at one depth ('*.ext' only directly " + + `under the directory); try '**/${args.pattern}' to match at any depth.`; + } + } if (unreadable.length > 0) { text += `\n\nThe search is incomplete: ${unreadable.length} ` +