Skip to content

Commit 5bfe0ae

Browse files
cliffhallclaude
andcommitted
feat(filesystem, memory): say when to use each list and delete tool
Rewrite the descriptions of list_directory and list_directory_with_sizes (filesystem) and delete_entities and delete_relations (memory) so each says when to use it and names its sibling. delete_relations also states the exact-match rule on from, to and relationType, and points to open_nodes for reading the stored relationType first. Names, schemas and annotations are unchanged. The READMEs follow, with new tests that read the descriptions through tools/list, and a patch changeset per server. Closes #5071 Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent 281b167 commit 5bfe0ae

9 files changed

Lines changed: 218 additions & 18 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@modelcontextprotocol/server-filesystem": patch
3+
---
4+
5+
The `list_directory` and `list_directory_with_sizes` descriptions now say when to use each one and name the other: `list_directory` for the names directly inside a path (and `directory_tree` for a recursive view), `list_directory_with_sizes` when sizes matter, sorted by name or by size, largest first, with the totals at the end.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@modelcontextprotocol/server-memory": patch
3+
---
4+
5+
The `delete_entities` and `delete_relations` descriptions now say when to use each one and name the other: `delete_entities` removes whole entities with their observations and every relation that touches them, while `delete_relations` removes a link and keeps both entities. `delete_relations` also states that a relation is deleted only on an exact match of `from`, `to` and `relationType`, and points to `open_nodes` for reading the stored type first.

‎src/filesystem/README.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -200,14 +200,16 @@ Files inside the allowed directories are also [resources](https://modelcontextpr
200200
- Succeeds silently if directory exists
201201
202202
- **list_directory**
203-
- List directory contents with [FILE] or [DIR] prefixes
203+
- List the entries directly inside a directory, one per line, with [FILE] or [DIR] prefixes
204204
- Input: `path` (string)
205+
- For sizes or a size-sorted listing, use `list_directory_with_sizes`; for a recursive view, use `directory_tree`
205206
206207
- **list_directory_with_sizes**
207-
- List directory contents with [FILE] or [DIR] prefixes, including file sizes
208+
- List the entries directly inside a directory with [FILE] or [DIR] prefixes, including file sizes
209+
- Use it when sizes matter (finding the largest files, say); for names only, use `list_directory`, which returns less text
208210
- Inputs:
209211
- `path` (string): Directory path to list
210-
- `sortBy` (string, optional): Sort entries by "name" or "size" (default: "name")
212+
- `sortBy` (string, optional): Sort entries by "name" or "size" (default: "name"; "size" lists the largest first)
211213
- Returns detailed listing with file sizes and summary statistics
212214
- Shows total files, directories, and combined size
213215
- An entry that cannot be stat'd (unreadable, a dangling symlink, or a symlink leaving the allowed directories) is listed with size `unknown` and left out of the combined size
Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
// What the list_directory and list_directory_with_sizes descriptions tell a
2+
// model (#5071). The two used to be the same text apart from ", including
3+
// sizes", so neither said when to pick it over the other. Each now names its
4+
// sibling; these tests read the descriptions through tools/list, check that
5+
// every tool they point to is registered, and check the one claim the
6+
// server-tools suite does not already cover: list_directory is not recursive.
7+
import fs from "fs/promises";
8+
import path from "path";
9+
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
10+
import type { Tool } from "@modelcontextprotocol/client";
11+
import {
12+
call,
13+
connect,
14+
makeTempDir,
15+
quietStderr,
16+
textOf,
17+
type Connected,
18+
} from "./helpers.js";
19+
20+
let dir: string;
21+
let conn: Connected;
22+
let tools: Tool[];
23+
24+
beforeEach(async () => {
25+
quietStderr();
26+
dir = await makeTempDir("mcp-fs-list-desc-");
27+
conn = await connect([dir]);
28+
({ tools } = await conn.client.listTools());
29+
});
30+
31+
afterEach(async () => {
32+
vi.restoreAllMocks();
33+
await conn.close();
34+
await fs.rm(dir, { recursive: true, force: true });
35+
});
36+
37+
function descriptionOf(name: string): string {
38+
const description = tools.find((t) => t.name === name)?.description;
39+
if (description === undefined) throw new Error(`no description: ${name}`);
40+
return description;
41+
}
42+
43+
describe("list tool descriptions (#5071)", () => {
44+
it("list_directory names list_directory_with_sizes and directory_tree", () => {
45+
const description = descriptionOf("list_directory");
46+
expect(description).toContain("use list_directory_with_sizes instead");
47+
expect(description).toContain("use directory_tree");
48+
expect(description).toContain("directly inside a path");
49+
});
50+
51+
it("list_directory_with_sizes names list_directory, sortBy and the totals", () => {
52+
const description = descriptionOf("list_directory_with_sizes");
53+
expect(description).toContain("use list_directory");
54+
expect(description).toContain("sorted by name or by size, largest first");
55+
expect(description).toContain("(sortBy)");
56+
expect(description).toContain("followed by the totals");
57+
});
58+
59+
it("names only tools the server registers", () => {
60+
const names = new Set(tools.map((t) => t.name));
61+
for (const tool of ["list_directory", "list_directory_with_sizes"]) {
62+
for (const named of descriptionOf(tool).match(/\b[a-z]+_[a-z_]+\b/g) ??
63+
[]) {
64+
expect(names, `${tool} names ${named}`).toContain(named);
65+
}
66+
}
67+
});
68+
69+
it("list_directory lists only the entries directly inside the path", async () => {
70+
await fs.mkdir(path.join(dir, "sub"));
71+
await fs.writeFile(path.join(dir, "sub", "nested.txt"), "");
72+
const text = textOf(
73+
await call(conn.client, "list_directory", { path: dir }),
74+
);
75+
expect(text).toBe("[DIR] sub");
76+
});
77+
});

‎src/filesystem/server.ts‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -650,10 +650,11 @@ export function createServer(
650650
{
651651
title: "List Directory",
652652
description:
653-
"Get a detailed listing of all files and directories in a specified path. " +
654-
"Results clearly distinguish between files and directories with [FILE] and [DIR] " +
655-
"prefixes. This tool is essential for understanding directory structure and " +
656-
"finding specific files within a directory. Only works within allowed directories.",
653+
"List the files and directories directly inside a path, each marked [FILE] or [DIR]. " +
654+
"Use it to see what a directory contains; when you also need each entry's size or " +
655+
"want entries sorted by size, use list_directory_with_sizes instead, and for a " +
656+
"recursive view use directory_tree. Returns one line per entry. Only works within " +
657+
"allowed directories.",
657658
inputSchema: jsonSchema2020(ListDirectoryArgsSchema.shape),
658659
outputSchema: jsonSchema2020({ content: z.string() }),
659660
annotations: {
@@ -684,10 +685,11 @@ export function createServer(
684685
{
685686
title: "List Directory with Sizes",
686687
description:
687-
"Get a detailed listing of all files and directories in a specified path, including sizes. " +
688-
"Results clearly distinguish between files and directories with [FILE] and [DIR] " +
689-
"prefixes. This tool is useful for understanding directory structure and " +
690-
"finding specific files within a directory. Only works within allowed directories.",
688+
"List the files and directories directly inside a path with each file's size, " +
689+
"marked [FILE] or [DIR], sorted by name or by size, largest first (sortBy). Use it " +
690+
"when sizes matter, such as finding the largest files; for names only, use " +
691+
"list_directory, which returns less text. Returns one line per entry, followed by " +
692+
"the totals. Only works within allowed directories.",
691693
inputSchema: jsonSchema2020(ListDirectoryWithSizesArgsSchema.shape),
692694
outputSchema: jsonSchema2020({ content: z.string() }),
693695
annotations: {

‎src/memory/README.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -85,9 +85,10 @@ Example:
8585
- Fails if entity doesn't exist
8686

8787
- **delete_entities**
88-
- Remove entities and their relations
88+
- Remove whole entities, with all their observations
8989
- Input: `entityNames` (string[])
90-
- Cascading deletion of associated relations
90+
- Cascading deletion of every relation that points to or from a deleted entity
91+
- To remove a link between two entities and keep both, use `delete_relations`; to remove facts from an entity, use `delete_observations`
9192
- No error if an entity doesn't exist; the response reports which names were not found
9293

9394
- **delete_observations**
@@ -99,12 +100,13 @@ Example:
99100
- No error if an observation doesn't exist; the response reports how many were deleted
100101

101102
- **delete_relations**
102-
- Remove specific relations from the graph
103+
- Remove specific relations from the graph, keeping the entities they connect (to remove an entity itself, use `delete_entities`)
103104
- Input: `relations` (array of objects)
104105
- Each object contains:
105106
- `from` (string): Source entity name
106107
- `to` (string): Target entity name
107108
- `relationType` (string): Relationship type
109+
- A relation is deleted only when `from`, `to` and `relationType` all match a stored one exactly; read the stored `relationType` with `open_nodes` (or `search_nodes`) first if unsure
108110
- No error if a relation doesn't exist; the response reports how many were deleted
109111

110112
- **read_graph**
Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
// What the delete_entities and delete_relations descriptions tell a model
2+
// (#5071). Both tools are destructive and share the same annotations, so the
3+
// description is the only place the difference between them lives: each one
4+
// names its sibling, and delete_relations states the exact-match rule that
5+
// otherwise turns a guessed relationType into "Deleted 0 of 1". These tests
6+
// read the descriptions through tools/list, check that every tool they point
7+
// to is registered, and check the behavior each one states.
8+
import { afterEach, beforeEach, describe, expect, it } from "vitest";
9+
import type { Tool } from "@modelcontextprotocol/client";
10+
import { call, connect, makeTempGraph } from "./helpers.js";
11+
import type { Connection } from "./helpers.js";
12+
13+
let conn: Connection;
14+
let cleanup: () => Promise<void>;
15+
let tools: Tool[];
16+
17+
beforeEach(async () => {
18+
const graph = await makeTempGraph();
19+
cleanup = graph.cleanup;
20+
conn = await connect(graph.filePath);
21+
({ tools } = await conn.client.listTools());
22+
});
23+
24+
afterEach(async () => {
25+
await conn.close();
26+
await cleanup();
27+
});
28+
29+
function descriptionOf(name: string): string {
30+
const description = tools.find((t) => t.name === name)?.description;
31+
if (description === undefined) throw new Error(`no description: ${name}`);
32+
return description;
33+
}
34+
35+
async function seed(): Promise<void> {
36+
await call(conn.client, "create_entities", {
37+
entities: [
38+
{ name: "Alice", entityType: "person", observations: ["likes tea"] },
39+
{ name: "Acme", entityType: "company", observations: [] },
40+
],
41+
});
42+
await call(conn.client, "create_relations", {
43+
relations: [{ from: "Alice", to: "Acme", relationType: "works at" }],
44+
});
45+
}
46+
47+
describe("delete tool descriptions (#5071)", () => {
48+
it("delete_entities names delete_relations and delete_observations", () => {
49+
const description = descriptionOf("delete_entities");
50+
expect(description).toContain("use delete_relations");
51+
expect(description).toContain("use delete_observations");
52+
expect(description).toContain(
53+
"every relation that points to or from them and all their observations",
54+
);
55+
});
56+
57+
it("delete_relations names delete_entities and states the exact-match rule", () => {
58+
const description = descriptionOf("delete_relations");
59+
expect(description).toContain("use delete_entities");
60+
expect(description).toContain("keep the entities they connect");
61+
expect(description).toContain("exactly on all three fields");
62+
expect(description).toContain("call open_nodes (or search_nodes) first");
63+
});
64+
65+
it("names only tools the server registers", () => {
66+
const names = new Set(tools.map((t) => t.name));
67+
for (const tool of ["delete_entities", "delete_relations"]) {
68+
for (const named of descriptionOf(tool).match(/\b[a-z]+_[a-z_]+\b/g) ??
69+
[]) {
70+
expect(names, `${tool} names ${named}`).toContain(named);
71+
}
72+
}
73+
});
74+
75+
it("delete_entities removes the entity's relations too", async () => {
76+
await seed();
77+
await call(conn.client, "delete_entities", { entityNames: ["Acme"] });
78+
const graph = await call(conn.client, "read_graph");
79+
expect(graph.structuredContent).toMatchObject({
80+
entities: [{ name: "Alice" }],
81+
relations: [],
82+
});
83+
});
84+
85+
it("delete_relations deletes only an exact match and keeps the entities", async () => {
86+
await seed();
87+
const miss = await call(conn.client, "delete_relations", {
88+
relations: [{ from: "Alice", to: "Acme", relationType: "works_at" }],
89+
});
90+
expect(miss.structuredContent).toMatchObject({ success: true });
91+
expect(
92+
(await call(conn.client, "read_graph")).structuredContent,
93+
).toMatchObject({ relations: [{ relationType: "works at" }] });
94+
95+
await call(conn.client, "delete_relations", {
96+
relations: [{ from: "Alice", to: "Acme", relationType: "works at" }],
97+
});
98+
expect(
99+
(await call(conn.client, "read_graph")).structuredContent,
100+
).toMatchObject({
101+
entities: [{ name: "Alice" }, { name: "Acme" }],
102+
relations: [],
103+
});
104+
});
105+
});

‎src/memory/__tests__/tools.test.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -230,7 +230,7 @@ const expectedTools = [
230230
name: "delete_entities",
231231
title: "Delete Entities",
232232
description:
233-
"Delete multiple entities and their associated relations from the knowledge graph",
233+
"Delete whole entities from the knowledge graph, together with every relation that points to or from them and all their observations. Use it only to remove an entity entirely; to remove a link between two entities and keep both, use delete_relations, and to remove facts from an entity, use delete_observations. Cannot be undone.",
234234
inputSchema: {
235235
type: "object",
236236
properties: {
@@ -285,7 +285,8 @@ const expectedTools = [
285285
{
286286
name: "delete_relations",
287287
title: "Delete Relations",
288-
description: "Delete multiple relations from the knowledge graph",
288+
description:
289+
"Delete specific relations (from, to, relationType) from the knowledge graph and keep the entities they connect. Each relation must match an existing one exactly on all three fields; if unsure, call open_nodes (or search_nodes) first to read the stored relationType. Use it to remove a link between two entities; to remove an entity itself, use delete_entities. Cannot be undone.",
289290
inputSchema: {
290291
type: "object",
291292
properties: {

‎src/memory/index.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1107,7 +1107,7 @@ export function createServer(
11071107
{
11081108
title: "Delete Entities",
11091109
description:
1110-
"Delete multiple entities and their associated relations from the knowledge graph",
1110+
"Delete whole entities from the knowledge graph, together with every relation that points to or from them and all their observations. Use it only to remove an entity entirely; to remove a link between two entities and keep both, use delete_relations, and to remove facts from an entity, use delete_observations. Cannot be undone.",
11111111
inputSchema: z.object({
11121112
entityNames: z
11131113
.array(z.string())
@@ -1196,7 +1196,8 @@ export function createServer(
11961196
"delete_relations",
11971197
{
11981198
title: "Delete Relations",
1199-
description: "Delete multiple relations from the knowledge graph",
1199+
description:
1200+
"Delete specific relations (from, to, relationType) from the knowledge graph and keep the entities they connect. Each relation must match an existing one exactly on all three fields; if unsure, call open_nodes (or search_nodes) first to read the stored relationType. Use it to remove a link between two entities; to remove an entity itself, use delete_entities. Cannot be undone.",
12001201
inputSchema: z.object({
12011202
relations: z
12021203
.array(RelationSchema)

0 commit comments

Comments
 (0)