Skip to content

Commit 2a73097

Browse files
cliffhallclaude
andcommitted
feat: describe every tool input property (#3669)
A model reads a property's description to decide what to pass; with none it guesses from the name. 19 filesystem properties, 4 memory properties and everything's resourceType advertised no description. Every filesystem path argument now states how it is resolved and that it must stay inside the allowed directories, and excludePatterns states the matching rule, which differs between directory_tree (a bare name matches at any depth) and search_files (it matches like pattern). read_file advertises ReadTextFileArgsSchema instead of an inline copy of it. A new input-descriptions test in each TypeScript server walks every tools/list input schema, nested properties included, and fails on any property with no description, so a tool added later keeps the rule. The filesystem one also pins the two excludePatterns rules the descriptions state. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent 281b167 commit 2a73097

12 files changed

Lines changed: 501 additions & 64 deletions

File tree

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
"@modelcontextprotocol/server-filesystem": patch
3+
"@modelcontextprotocol/server-memory": patch
4+
"@modelcontextprotocol/server-everything": patch
5+
---
6+
7+
Describe every tool input property in tools/list (#3669). Every filesystem path argument now says how it is resolved and that it must stay inside the allowed directories, and `excludePatterns` says how its globs match (which differs between `directory_tree` and `search_files`). The memory server's top-level array arguments, and the everything server's `resourceType`, gain descriptions, and `get-resource-reference`'s `resourceId` no longer claims to fetch only text resources.
Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
// Every property of every tool input schema the server advertises in
2+
// tools/list carries a description (#3669). A model reads these to decide what
3+
// to pass, and with no description it guesses from the property name alone.
4+
// This is the reference implementation other server authors copy, so the rule
5+
// is pinned for every tool, existing or added later, and for nested
6+
// properties (array items, object fields) as well as top-level ones.
7+
8+
import { afterEach, describe, expect, it } from "vitest";
9+
import { ALL_CAPABILITIES, connect, type Session } from "./harness.js";
10+
11+
/** A JSON Schema node, as much of it as the walk reads. */
12+
type SchemaNode = {
13+
description?: unknown;
14+
properties?: Record<string, SchemaNode>;
15+
items?: SchemaNode | SchemaNode[];
16+
anyOf?: SchemaNode[];
17+
oneOf?: SchemaNode[];
18+
allOf?: SchemaNode[];
19+
};
20+
21+
/**
22+
* The path of every property under `node`, at any depth, that has no
23+
* non-empty description: the properties of nested objects and of array
24+
* items count, since a model fills those in too.
25+
*/
26+
function undescribed(node: SchemaNode, path: string): string[] {
27+
const missing: string[] = [];
28+
for (const [key, child] of Object.entries(node.properties ?? {})) {
29+
const at = `${path}.${key}`;
30+
if (
31+
typeof child.description !== "string" ||
32+
child.description.trim() === ""
33+
) {
34+
missing.push(at);
35+
}
36+
missing.push(...undescribed(child, at));
37+
}
38+
const items = node.items;
39+
for (const item of Array.isArray(items) ? items : items ? [items] : []) {
40+
missing.push(...undescribed(item, `${path}[]`));
41+
}
42+
for (const branch of [
43+
...(node.anyOf ?? []),
44+
...(node.oneOf ?? []),
45+
...(node.allOf ?? []),
46+
]) {
47+
missing.push(...undescribed(branch, path));
48+
}
49+
return missing;
50+
}
51+
52+
let session: Session | undefined;
53+
54+
afterEach(async () => {
55+
await session?.close();
56+
session = undefined;
57+
});
58+
59+
describe("tool input descriptions (#3669)", () => {
60+
it("describes every input property of every tool", async () => {
61+
// Every capability, so the tools gated on one are listed too.
62+
session = await connect({ capabilities: ALL_CAPABILITIES });
63+
const { tools } = await session.client.listTools();
64+
expect(tools.length).toBeGreaterThan(0);
65+
const missing = tools.flatMap((tool) =>
66+
undescribed(tool.inputSchema as SchemaNode, tool.name),
67+
);
68+
expect(missing).toEqual([]);
69+
});
70+
});

‎src/everything/__tests__/surface.test.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -509,11 +509,12 @@ describe("tools/list", () => {
509509
"properties": {
510510
"resourceId": {
511511
"default": 1,
512-
"description": "ID of the text resource to fetch",
512+
"description": "ID of the text or blob resource to fetch, a positive integer",
513513
"type": "number",
514514
},
515515
"resourceType": {
516516
"default": "Text",
517+
"description": "Whether to reference a text resource or a blob resource",
517518
"enum": [
518519
"Text",
519520
"Blob",

‎src/everything/tools/get-resource-reference.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,12 @@ import { TOOL_ICONS } from "../server/icons.js";
1515
const GetResourceReferenceSchema = z.object({
1616
resourceType: z
1717
.enum([RESOURCE_TYPE_TEXT, RESOURCE_TYPE_BLOB])
18-
.default(RESOURCE_TYPE_TEXT),
18+
.default(RESOURCE_TYPE_TEXT)
19+
.describe("Whether to reference a text resource or a blob resource"),
1920
resourceId: z
2021
.number()
2122
.default(1)
22-
.describe("ID of the text resource to fetch"),
23+
.describe("ID of the text or blob resource to fetch, a positive integer"),
2324
});
2425

2526
// Tool configuration

‎src/filesystem/README.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -246,7 +246,9 @@ Files inside the allowed directories are also [resources](https://modelcontextpr
246246
- `pattern` (string): Glob matched, case-sensitively, against each entry's
247247
path relative to `path`: `*.ext` matches entries directly under `path`,
248248
`**/*.ext` or `**/name` matches at any depth
249-
- `excludePatterns` (string[]): Exclude any patterns. An excluded entry is
249+
- `excludePatterns` (string[]): Globs for entries to skip, matched like
250+
`pattern`, so a bare name skips only the top-level entry: use
251+
`**/node_modules` to skip that name at any depth. An excluded entry is
250252
skipped before it is resolved or read, so excluding a slow folder keeps
251253
the search out of it entirely.
252254
- Glob-style pattern matching
@@ -261,7 +263,10 @@ Files inside the allowed directories are also [resources](https://modelcontextpr
261263
- Get recursive JSON tree structure of directory contents
262264
- Inputs:
263265
- `path` (string): Starting directory
264-
- `excludePatterns` (string[]): Exclude any patterns. Glob formats are supported.
266+
- `excludePatterns` (string[]): Globs for entries to leave out, with their
267+
contents, matched against each entry's path relative to `path`. A
268+
pattern with no `*` also matches that name at any depth, so
269+
`node_modules` leaves out every `node_modules` directory.
265270
- `depth` (positive integer, optional): How many levels to descend. `1`
266271
lists only the entries directly in `path`, `2` adds their children, and
267272
so on. Omitted, the whole tree is returned
Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
// Every property of every tool input schema the server advertises in
2+
// tools/list carries a description (#3669). A model reads these to decide what
3+
// to pass, and with no description it guesses from the property name alone.
4+
// This is the reference implementation other server authors copy, so the rule
5+
// is pinned for every tool, existing or added later, and for nested
6+
// properties (array items, object fields) as well as top-level ones. The
7+
// excludePatterns descriptions state matching rules that differ between
8+
// directory_tree and search_files, so those rules are pinned here as well.
9+
10+
import fs from "fs/promises";
11+
import path from "path";
12+
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
13+
import {
14+
call,
15+
connect,
16+
makeTempDir,
17+
quietStderr,
18+
textOf,
19+
type Connected,
20+
} from "./helpers.js";
21+
22+
/** A JSON Schema node, as much of it as the walk reads. */
23+
type SchemaNode = {
24+
description?: unknown;
25+
properties?: Record<string, SchemaNode>;
26+
items?: SchemaNode | SchemaNode[];
27+
anyOf?: SchemaNode[];
28+
oneOf?: SchemaNode[];
29+
allOf?: SchemaNode[];
30+
};
31+
32+
/**
33+
* The path of every property under `node`, at any depth, that has no
34+
* non-empty description: the properties of nested objects and of array
35+
* items count, since a model fills those in too.
36+
*/
37+
function undescribed(node: SchemaNode, path: string): string[] {
38+
const missing: string[] = [];
39+
for (const [key, child] of Object.entries(node.properties ?? {})) {
40+
const at = `${path}.${key}`;
41+
if (
42+
typeof child.description !== "string" ||
43+
child.description.trim() === ""
44+
) {
45+
missing.push(at);
46+
}
47+
missing.push(...undescribed(child, at));
48+
}
49+
const items = node.items;
50+
for (const item of Array.isArray(items) ? items : items ? [items] : []) {
51+
missing.push(...undescribed(item, `${path}[]`));
52+
}
53+
for (const branch of [
54+
...(node.anyOf ?? []),
55+
...(node.oneOf ?? []),
56+
...(node.allOf ?? []),
57+
]) {
58+
missing.push(...undescribed(branch, path));
59+
}
60+
return missing;
61+
}
62+
63+
let dir: string;
64+
let conn: Connected;
65+
66+
beforeEach(async () => {
67+
// The server logs its roots decision to stderr on every connect.
68+
quietStderr();
69+
dir = await makeTempDir("mcp-fs-descriptions-");
70+
conn = await connect([dir]);
71+
});
72+
73+
afterEach(async () => {
74+
vi.restoreAllMocks();
75+
await conn.close();
76+
await fs.rm(dir, { recursive: true, force: true });
77+
});
78+
79+
describe("tool input descriptions (#3669)", () => {
80+
it("describes every input property of every tool", async () => {
81+
const { tools } = await conn.client.listTools();
82+
expect(tools.length).toBeGreaterThan(0);
83+
const missing = tools.flatMap((tool) =>
84+
undescribed(tool.inputSchema as SchemaNode, tool.name),
85+
);
86+
expect(missing).toEqual([]);
87+
});
88+
});
89+
90+
describe("excludePatterns, as the descriptions state it (#3669)", () => {
91+
beforeEach(async () => {
92+
// A node_modules at the top level and one nested a level down.
93+
await fs.mkdir(path.join(dir, "node_modules"));
94+
await fs.writeFile(path.join(dir, "node_modules", "top.txt"), "");
95+
await fs.mkdir(path.join(dir, "pkg", "node_modules"), { recursive: true });
96+
await fs.writeFile(path.join(dir, "pkg", "node_modules", "deep.txt"), "");
97+
await fs.writeFile(path.join(dir, "pkg", "keep.txt"), "");
98+
});
99+
100+
async function search(excludePatterns: string[]): Promise<string[]> {
101+
const result = await call(conn.client, "search_files", {
102+
path: dir,
103+
pattern: "**/*.txt",
104+
excludePatterns,
105+
});
106+
return textOf(result).split("\n").sort();
107+
}
108+
109+
it("directory_tree: a name with no '*' is left out at any depth", async () => {
110+
const result = await call(conn.client, "directory_tree", {
111+
path: dir,
112+
excludePatterns: ["node_modules"],
113+
});
114+
const text = textOf(result);
115+
expect(text).not.toContain("node_modules");
116+
expect(text).toContain("keep.txt");
117+
});
118+
119+
it("search_files: a bare name skips only the top-level entry", async () => {
120+
expect(await search(["node_modules"])).toEqual([
121+
path.join(dir, "pkg", "keep.txt"),
122+
path.join(dir, "pkg", "node_modules", "deep.txt"),
123+
]);
124+
});
125+
126+
it("search_files: '**/node_modules' skips that name at any depth", async () => {
127+
expect(await search(["**/node_modules"])).toEqual([
128+
path.join(dir, "pkg", "keep.txt"),
129+
]);
130+
});
131+
});

‎src/filesystem/__tests__/server-tools.test.ts‎

Lines changed: 17 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -230,7 +230,11 @@ describe("server identity and tool list", () => {
230230
expect(strip(byName.read_text_file.inputSchema)).toEqual({
231231
type: "object",
232232
properties: {
233-
path: { type: "string" },
233+
path: {
234+
type: "string",
235+
description:
236+
"The file to read as text. Absolute, or relative to an allowed directory; it must resolve inside the allowed directories.",
237+
},
234238
tail: {
235239
type: "integer",
236240
minimum: 0,
@@ -247,12 +251,23 @@ describe("server identity and tool list", () => {
247251
},
248252
required: ["path"],
249253
});
254+
// The deprecated alias advertises read_text_file's schema, not a copy.
255+
expect(byName.read_file.inputSchema).toEqual(
256+
byName.read_text_file.inputSchema,
257+
);
250258
expect(strip(byName.edit_file.inputSchema)).toEqual({
251259
type: "object",
252260
properties: {
253-
path: { type: "string" },
261+
path: {
262+
type: "string",
263+
description:
264+
"The text file to edit. Absolute, or relative to an allowed directory; it must resolve inside the allowed directories.",
265+
},
254266
edits: {
255267
type: "array",
268+
description:
269+
"The replacements to make, applied in order, each to the result of the ones before it. " +
270+
"If any one has no match, none is written.",
256271
items: {
257272
type: "object",
258273
properties: {

0 commit comments

Comments
 (0)