toolmenu 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +311 -0
  3. package/dist/cli.d.ts +2 -0
  4. package/dist/cli.js +283 -0
  5. package/dist/compare.d.ts +32 -0
  6. package/dist/compare.js +108 -0
  7. package/dist/config.d.ts +19 -0
  8. package/dist/config.js +27 -0
  9. package/dist/connect.d.ts +66 -0
  10. package/dist/connect.js +122 -0
  11. package/dist/diff.d.ts +58 -0
  12. package/dist/diff.js +404 -0
  13. package/dist/history.d.ts +88 -0
  14. package/dist/history.js +219 -0
  15. package/dist/index.d.ts +10 -0
  16. package/dist/index.js +9 -0
  17. package/dist/menu.d.ts +9 -0
  18. package/dist/menu.js +57 -0
  19. package/dist/report.d.ts +11 -0
  20. package/dist/report.js +278 -0
  21. package/dist/routes.d.ts +22 -0
  22. package/dist/routes.js +76 -0
  23. package/dist/rules/description.d.ts +28 -0
  24. package/dist/rules/description.js +158 -0
  25. package/dist/rules/determinism.d.ts +2 -0
  26. package/dist/rules/determinism.js +35 -0
  27. package/dist/rules/ids.d.ts +11 -0
  28. package/dist/rules/ids.js +138 -0
  29. package/dist/rules/index.d.ts +11 -0
  30. package/dist/rules/index.js +42 -0
  31. package/dist/rules/naming.d.ts +4 -0
  32. package/dist/rules/naming.js +145 -0
  33. package/dist/rules/rule.d.ts +33 -0
  34. package/dist/rules/rule.js +1 -0
  35. package/dist/rules/spec.d.ts +5 -0
  36. package/dist/rules/spec.js +102 -0
  37. package/dist/rules/write.d.ts +3 -0
  38. package/dist/rules/write.js +55 -0
  39. package/dist/semver.d.ts +11 -0
  40. package/dist/semver.js +41 -0
  41. package/dist/session.d.ts +90 -0
  42. package/dist/session.js +519 -0
  43. package/dist/snapshot.d.ts +16 -0
  44. package/dist/snapshot.js +42 -0
  45. package/dist/types.d.ts +49 -0
  46. package/dist/types.js +1 -0
  47. package/dist/version.d.ts +2 -0
  48. package/dist/version.js +3 -0
  49. package/dist/words.d.ts +14 -0
  50. package/dist/words.js +63 -0
  51. package/package.json +57 -0
  52. package/schemas/2024-11-05.json +2077 -0
  53. package/schemas/2025-03-26.json +2139 -0
  54. package/schemas/2025-06-18.json +2517 -0
  55. package/schemas/2025-11-25.json +4058 -0
  56. package/schemas/2026-07-28.json +3963 -0
package/dist/routes.js ADDED
@@ -0,0 +1,76 @@
1
+ import { readFile } from 'node:fs/promises';
2
+ import { parse } from 'yaml';
3
+ import { singular, words } from './words.js';
4
+ export async function loadRoutes(path) {
5
+ const data = parse(await readFile(path, 'utf8'));
6
+ if (!data || typeof data !== 'object' || Array.isArray(data)) {
7
+ throw new Error(`${path}: expected a map of keyword → { must_match, must_not_match }`);
8
+ }
9
+ for (const [keyword, value] of Object.entries(data)) {
10
+ const v = value;
11
+ for (const key of ['must_match', 'must_not_match']) {
12
+ if (v?.[key] !== undefined && !(Array.isArray(v[key]) && v[key].every((x) => typeof x === 'string'))) {
13
+ throw new Error(`${path}: "${keyword}.${key}" must be a list of tool names`);
14
+ }
15
+ }
16
+ }
17
+ return data;
18
+ }
19
+ /** Words that don't decide a route: "forms per team" needs form, team. */
20
+ const STOP = new Set(['a', 'an', 'the', 'of', 'for', 'per', 'by', 'to', 'in', 'on', 'at', 'from', 'with', 'and', 'or', 'my', 'our', 'your', 'every', 'each']);
21
+ /** The words of a keyword that have to be there for a tool to match it. */
22
+ export function routeWords(keyword) {
23
+ const all = words(keyword).map(singular);
24
+ const content = all.filter((w) => !STOP.has(w));
25
+ return content.length > 0 ? content : all;
26
+ }
27
+ /**
28
+ * How strongly each tool matches a keyword. Deterministic, no LLM, the way a
29
+ * keyword or BM25 tool search sees it (it can't read "not"):
30
+ * - name: 1 per route word in the tool name, plus 2 if the name has them all
31
+ * (a one-word route in the name scores 3);
32
+ * - description: 1 per mention of the exact phrase (up to 3), or 1 if the name
33
+ * and description have every word between them but never as the phrase.
34
+ * Singular and plural count as the same word.
35
+ */
36
+ export function routeScores(keyword, tools) {
37
+ const phrase = words(keyword).map(singular);
38
+ const wanted = routeWords(keyword);
39
+ const scores = new Map();
40
+ for (const tool of tools) {
41
+ const nameWords = new Set(words(tool.name).map(singular));
42
+ const hits = wanted.filter((w) => nameWords.has(w)).length;
43
+ const inName = wanted.length > 0 && hits === wanted.length;
44
+ const descWords = words(tool.description ?? '').map(singular);
45
+ let mentions = 0;
46
+ for (let i = 0; i + phrase.length <= descWords.length; i++) {
47
+ if (phrase.every((w, k) => descWords[i + k] === w))
48
+ mentions++;
49
+ }
50
+ const everywhere = new Set([...nameWords, ...descWords]);
51
+ const scattered = !inName && wanted.length > 0 && wanted.every((w) => everywhere.has(w)) ? 1 : 0;
52
+ // A name that only half-matches doesn't count unless the words are all there somewhere.
53
+ const name = inName ? hits + 2 : scattered ? hits : 0;
54
+ scores.set(tool.name, name + Math.max(Math.min(mentions, 3), scattered));
55
+ }
56
+ return scores;
57
+ }
58
+ /** Keyword words a tool has nowhere in its name or description. */
59
+ export function missingWords(keyword, tool) {
60
+ const have = new Set([...words(tool.name), ...words(tool.description ?? '')].map(singular));
61
+ return routeWords(keyword).filter((w) => !have.has(w));
62
+ }
63
+ /** The sentence where a tool's description mentions the keyword next to a "not", if it does. */
64
+ export function negatedMention(keyword, tool) {
65
+ const text = tool.description ?? '';
66
+ for (const sentence of text.split(/(?<=[.!?])\s+|\n+/)) {
67
+ const ws = words(sentence).map(singular);
68
+ const wanted = routeWords(keyword);
69
+ if (!wanted.every((w) => ws.includes(w)))
70
+ continue;
71
+ if (/\b(?:not|never|no|isn'?t|aren'?t|doesn'?t|don'?t|without|unlike|rather than|instead of)\b/i.test(sentence)) {
72
+ return sentence.trim().replace(/\s+/g, ' ');
73
+ }
74
+ }
75
+ return undefined;
76
+ }
@@ -0,0 +1,28 @@
1
+ import type { MenuTool } from '../types.js';
2
+ import type { Rule } from './rule.js';
3
+ export declare const CLIENT_LIMITS: Record<string, number>;
4
+ export declare const DEFAULT_CLIENT = "claude-code";
5
+ /** The cut in characters, and how to name it in a message. */
6
+ export declare function resolveLimit(setting: number | string | undefined): {
7
+ limit: number;
8
+ who: string;
9
+ };
10
+ interface Instruction {
11
+ at: number;
12
+ text: string;
13
+ }
14
+ /** Every instruction to the agent in a description, in order (several per sentence possible). */
15
+ export declare function instructions(text: string, otherTools: string[]): Instruction[];
16
+ /**
17
+ * The instructions a cut at `limit` hides, one per sentence. An instruction that
18
+ * starts before the cut but ends after it counts too: "Use task_getProgressT…"
19
+ * loses the tool name, which is the part that routes.
20
+ */
21
+ export declare function pastTheCut(text: string, otherTools: string[], limit: number): (Instruction & {
22
+ straddles: boolean;
23
+ })[];
24
+ /** Tool names or globs (`*`) a client sends in full, uncut. */
25
+ export declare function sentInFull(tool: MenuTool, patterns: string[] | undefined): boolean;
26
+ export declare const buried: Rule;
27
+ export declare const cut: Rule;
28
+ export {};
@@ -0,0 +1,158 @@
1
+ /*
2
+ * Clients that cut tool descriptions, and where. Only reported cuts, with sources:
3
+ * - claude-code: 2,048 characters, "… [truncated]" appended, silently (anthropics/claude-code#87650);
4
+ * the Claude Code changelog lists CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH to change it from 2.1.280.
5
+ * - amazon-q: 10,024 characters, with a warning (Amazon Q CLI 1.19; makenotion/notion-mcp-server#145).
6
+ * Other clients send the description in full or don't document a cut. Your own
7
+ * client may cut elsewhere: set descriptionLimit to its number.
8
+ */
9
+ export const CLIENT_LIMITS = { 'claude-code': 2048, 'amazon-q': 10024 };
10
+ export const DEFAULT_CLIENT = 'claude-code';
11
+ /** The cut in characters, and how to name it in a message. */
12
+ export function resolveLimit(setting) {
13
+ if (typeof setting === 'number')
14
+ return { limit: setting, who: `your client (descriptionLimit ${setting.toLocaleString('en-US')})` };
15
+ const client = setting ?? DEFAULT_CLIENT;
16
+ const limit = CLIENT_LIMITS[client] ?? CLIENT_LIMITS[DEFAULT_CLIENT];
17
+ const name = client === 'amazon-q' ? 'Amazon Q CLI' : 'Claude Code';
18
+ return { limit, who: `${name} (${limit.toLocaleString('en-US')} characters${setting === undefined ? ', the default: set descriptionLimit for your client' : ''})` };
19
+ }
20
+ /*
21
+ * An instruction tells the agent what to do or not do: "use X", "call this tool",
22
+ * "don't retry", "never guess one", "if the user asks…". A description of
23
+ * behaviour uses the same words without addressing the agent: "never throws",
24
+ * "instead of failing", "rather than erroring", "was never recognized". Only
25
+ * instructions count, and every one past the cut is checked, not just the first.
26
+ */
27
+ const VERBS = 'use|call|retry|guess|invent|make up|fabricate|hand[- ]?construct|construct|build|surface|pass|send|assume|query|search|fetch|ask|expose|show|display|look up|write|put|add|include|rely on|trust|confuse|mix up|treat';
28
+ const INSTRUCTION = [
29
+ new RegExp(String.raw `\b(?:don'?t|do not|never|must not|should not|avoid)\s+(?:${VERBS})\b`, 'gi'),
30
+ /\b(?:use|call|try|prefer)\s+(?:this tool|this one|that tool|the [\w-]+ tool)\b/gi,
31
+ /\buse this (?:tool )?(?:when|for|to|if|only)\b/gi,
32
+ /\bonly (?:use|call)\b/gi,
33
+ /\b(?:if|when) the user\b/gi,
34
+ /\bmeans call\b/gi,
35
+ /\bnot for\b/gi,
36
+ /\bdeprecated\b/gi,
37
+ /\b(?:before|after) (?:calling|using)\b/gi,
38
+ ];
39
+ function sentenceAround(text, at) {
40
+ const start = Math.max(0, Math.max(text.lastIndexOf('. ', at), text.lastIndexOf('\n', at)) + 1);
41
+ const ends = [text.indexOf('. ', at), text.indexOf('\n', at)].filter((i) => i !== -1);
42
+ const end = ends.length ? Math.min(...ends) + 1 : text.length;
43
+ return text.slice(start, end).trim().replace(/\s+/g, ' ');
44
+ }
45
+ /** Every instruction to the agent in a description, in order (several per sentence possible). */
46
+ export function instructions(text, otherTools) {
47
+ const found = new Map();
48
+ for (const re of INSTRUCTION)
49
+ for (const m of text.matchAll(re))
50
+ found.set(m.index ?? 0, m[0]);
51
+ // Naming another tool alongside use/call/instead is an instruction too:
52
+ // "call render_html first", "use get_progress_table instead", and the
53
+ // contrast "(get_a and get_b don't answer this)".
54
+ for (const name of otherTools) {
55
+ let at = text.indexOf(name);
56
+ while (at !== -1) {
57
+ if (/\b(use|call|instead|prefer|first|rather than|don'?t|doesn'?t|do not|does not|isn'?t|aren'?t|won'?t|unlike)\b/i.test(sentenceAround(text, at)))
58
+ found.set(at, name);
59
+ at = text.indexOf(name, at + name.length);
60
+ }
61
+ }
62
+ return [...found].sort((a, b) => a[0] - b[0]).map(([at, t]) => ({ at, text: t }));
63
+ }
64
+ /**
65
+ * The instructions a cut at `limit` hides, one per sentence. An instruction that
66
+ * starts before the cut but ends after it counts too: "Use task_getProgressT…"
67
+ * loses the tool name, which is the part that routes.
68
+ */
69
+ export function pastTheCut(text, otherTools, limit) {
70
+ const seen = new Set();
71
+ const out = [];
72
+ for (const i of instructions(text, otherTools)) {
73
+ if (i.at + i.text.length <= limit)
74
+ continue;
75
+ const sentence = sentenceAround(text, i.at);
76
+ if (seen.has(sentence))
77
+ continue;
78
+ seen.add(sentence);
79
+ out.push({ ...i, straddles: i.at < limit });
80
+ }
81
+ return out;
82
+ }
83
+ /** Tool names or globs (`*`) a client sends in full, uncut. */
84
+ export function sentInFull(tool, patterns) {
85
+ return (patterns ?? []).some((p) => new RegExp('^' + p.split('*').map((s) => s.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('.*') + '$').test(tool.name));
86
+ }
87
+ export const buried = {
88
+ id: 'description/buried',
89
+ severity: 'warn',
90
+ lesson: 'truncated description',
91
+ summary: 'Instructions to the agent sit past the point where your client cuts descriptions',
92
+ run(ctx) {
93
+ const { limit, who } = resolveLimit(ctx.descriptionLimit);
94
+ const names = ctx.menu.tools.map((t) => t.name);
95
+ const findings = [];
96
+ for (const tool of ctx.menu.tools) {
97
+ const text = tool.description ?? '';
98
+ if (text.length <= limit || sentInFull(tool, ctx.fullDescriptions))
99
+ continue;
100
+ const past = pastTheCut(text, names.filter((n) => n !== tool.name), limit);
101
+ if (past.length === 0)
102
+ continue;
103
+ const one = past.length === 1;
104
+ findings.push({
105
+ tool: tool.name,
106
+ message: `${tool.name}: the description is ${text.length.toLocaleString('en-US')} characters, and ${who} cuts it at ${limit.toLocaleString('en-US')}. ${one ? 'An instruction to the agent is' : `${past.length} instructions to the agent are`} past the cut${past[0].straddles ? `, the first cut mid-instruction (it starts at ${past[0].at.toLocaleString('en-US')})` : `, the first at ${past[0].at.toLocaleString('en-US')}`}, so the model never sees ${one ? 'it' : 'them'}. Move ${one ? 'it' : 'them'} into the first ${limit.toLocaleString('en-US')} characters, or list the tool in fullDescriptions if your client sends it uncut.`,
107
+ detail: past
108
+ .slice(0, 3)
109
+ .map((i) => {
110
+ const sentence = sentenceAround(text, i.at);
111
+ return `char ${i.at.toLocaleString('en-US')}${i.straddles ? ' (cut mid-instruction)' : ''}: “${sentence.length > 200 ? sentence.slice(0, 197) + '…' : sentence}”`;
112
+ })
113
+ .concat(past.length > 3 ? [`…and ${past.length - 3} more`] : []),
114
+ });
115
+ }
116
+ return findings;
117
+ },
118
+ };
119
+ /** A short cut to check against when the client's own cut isn't set: one real client cut at 280. */
120
+ const SHORT_CUT = 280;
121
+ export const cut = {
122
+ id: 'description/cut',
123
+ severity: 'info',
124
+ lesson: 'truncated description',
125
+ summary: 'Descriptions longer than your client sends, and instructions a shorter cut would hide',
126
+ run(ctx) {
127
+ const { limit, who } = resolveLimit(ctx.descriptionLimit);
128
+ const names = ctx.menu.tools.map((t) => t.name);
129
+ const others = (tool) => names.filter((n) => n !== tool.name);
130
+ const tools = ctx.menu.tools.filter((t) => !sentInFull(t, ctx.fullDescriptions));
131
+ const findings = [];
132
+ const long = tools.filter((tool) => {
133
+ const text = tool.description ?? '';
134
+ return text.length > limit && pastTheCut(text, others(tool), limit).length === 0;
135
+ });
136
+ if (long.length) {
137
+ findings.push({
138
+ message: `${long.length === 1 ? '1 description is' : `${long.length} descriptions are`} longer than ${who} sends, so the model gets a prefix that can read as complete: ${list(long, (t) => `${t.name} (${(t.description ?? '').length.toLocaleString('en-US')})`)}. Nothing past the cut reads as an instruction, but check what's there.`,
139
+ });
140
+ }
141
+ // With the default cut, say what a shorter client cut would hide.
142
+ if (ctx.descriptionLimit === undefined && limit > SHORT_CUT) {
143
+ const hidden = tools.filter((tool) => {
144
+ const text = tool.description ?? '';
145
+ return text.length > SHORT_CUT && pastTheCut(text, others(tool), SHORT_CUT).some((i) => i.at < limit);
146
+ });
147
+ if (hidden.length) {
148
+ findings.push({
149
+ message: `${hidden.length === 1 ? '1 description gives' : `${hidden.length} descriptions give`} the agent instructions after character ${SHORT_CUT}: ${list(hidden, (t) => t.name)}. ${who.split(' (')[0]} sends ${limit.toLocaleString('en-US')} characters, so they arrive there, but a client that cuts shorter never shows them (one real client cut at ${SHORT_CUT}). If yours cuts descriptions, set descriptionLimit to its cut.`,
150
+ });
151
+ }
152
+ }
153
+ return findings;
154
+ },
155
+ };
156
+ function list(tools, show) {
157
+ return tools.slice(0, 5).map(show).join(', ') + (tools.length > 5 ? `, and ${tools.length - 5} more` : '');
158
+ }
@@ -0,0 +1,2 @@
1
+ import type { Rule } from './rule.js';
2
+ export declare const nondeterministic: Rule;
@@ -0,0 +1,35 @@
1
+ import { compareMenus } from '../compare.js';
2
+ const LABELS = {
3
+ added: 'tool added',
4
+ removed: 'tool removed',
5
+ moved: 'order changed',
6
+ description: 'description changed',
7
+ inputSchema: 'inputSchema changed',
8
+ outputSchema: 'outputSchema changed',
9
+ annotations: 'annotations changed',
10
+ other: 'definition changed',
11
+ serialization: 'key order changed (same content, different bytes)',
12
+ };
13
+ export const nondeterministic = {
14
+ id: 'menu/nondeterministic',
15
+ severity: 'error',
16
+ lesson: '05',
17
+ summary: 'Two identical tools/list calls must return the same menu',
18
+ run(ctx) {
19
+ if (!ctx.secondList)
20
+ return [];
21
+ const changes = compareMenus(ctx.menu.tools, ctx.secondList);
22
+ if (changes.length === 0)
23
+ return [];
24
+ const onlyOrder = changes.every((c) => c.kind === 'moved');
25
+ return [
26
+ {
27
+ message: onlyOrder
28
+ ? 'Two identical tools/list calls returned the tools in a different order. Every conversation can miss the prompt cache. The spec says servers SHOULD return a deterministic order.'
29
+ : 'Two identical tools/list calls returned different menus. Every conversation can miss the prompt cache.',
30
+ detail: changes.slice(0, 10).map((c) => `${LABELS[c.kind]}: ${c.tool} (position ${c.position})`)
31
+ .concat(changes.length > 10 ? [`…and ${changes.length - 10} more`] : []),
32
+ },
33
+ ];
34
+ },
35
+ };
@@ -0,0 +1,11 @@
1
+ import type { MenuTool } from '../types.js';
2
+ import type { Rule } from './rule.js';
3
+ interface IdParam {
4
+ param: string;
5
+ /** Which kind of thing it identifies (singular noun), when we can tell. */
6
+ kind?: string;
7
+ }
8
+ /** Inputs that look like opaque IDs the agent has to supply. */
9
+ export declare function idParams(tool: MenuTool): IdParam[];
10
+ export declare const authoredIds: Rule;
11
+ export {};
@@ -0,0 +1,138 @@
1
+ import { COLLECTION_VERBS, LOOKUP_VERBS, VERBS, commonWords, nouns, singular, words } from '../words.js';
2
+ // form_id, form-id, formId, formID. Not uid or paid: the suffix needs a boundary.
3
+ // Not "key" either: in real menus it's as often a keyboard key as an identifier.
4
+ const ID_SUFFIX = /^(.+?)[_-](id|ids|uuid|uuids)$/i;
5
+ const CAMEL_ID = /^([a-z][a-zA-Z0-9]*?)(Id|Ids|ID|IDs|Uuid)$/;
6
+ const BARE_ID = /^(id|ids|uid|uuid)$/i;
7
+ const CREATE_VERBS = new Set(['create', 'add', 'new', 'insert', 'post', 'upsert', 'start', 'run', 'submit', 'duplicate', 'copy']);
8
+ // Words that join alternatives in a name: projectSlugOrId → project.
9
+ const JOINERS = new Set(['or', 'and', 'slug', 'name', 'handle']);
10
+ // Qualifiers in front of the kind: creatorRegionId and newRegionId are region IDs.
11
+ const QUALIFIERS = new Set([
12
+ 'creator', 'new', 'old', 'target', 'source', 'parent', 'child', 'from', 'to', 'destination', 'current',
13
+ 'previous', 'next', 'owner', 'assigned', 'assignee', 'primary', 'default', 'other', 'related', 'base', 'root',
14
+ ]);
15
+ // A description that tells the agent not to make the value up.
16
+ const DONT_INVENT = /\b(do not|don't|never|avoid|must not)\s+(invent|make up|guess|fabricate|generate)\b/i;
17
+ // "Omit this in the normal case": optional, and the agent is told to leave it out.
18
+ const OMIT = /\b(omit|leave out|leave (it|this) (out|empty|unset|blank))\b/i;
19
+ /**
20
+ * The agent is told not to make this value up, in the parameter's description
21
+ * or in a sentence of the tool's description that names the parameter
22
+ * ("don't invent a sessionId").
23
+ */
24
+ function toldNotToInvent(tool, param, schema) {
25
+ const own = typeof schema?.description === 'string' ? schema.description : '';
26
+ if (DONT_INVENT.test(own) || OMIT.test(own))
27
+ return true;
28
+ const spaced = param.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/[_-]+/g, ' ').toLowerCase();
29
+ return (tool.description ?? '')
30
+ .split(/(?<=[.!?])\s+|\n+/)
31
+ .some((sentence) => {
32
+ const lower = sentence.toLowerCase();
33
+ return (lower.includes(param.toLowerCase()) || lower.includes(spaced)) && DONT_INVENT.test(sentence);
34
+ });
35
+ }
36
+ /** Inputs that look like opaque IDs the agent has to supply. */
37
+ export function idParams(tool) {
38
+ const params = [];
39
+ const props = tool.inputSchema?.properties ?? {};
40
+ for (const [param, schema] of Object.entries(props)) {
41
+ if (!looksLikeIdValue(schema))
42
+ continue;
43
+ const match = CAMEL_ID.exec(param) ?? ID_SUFFIX.exec(param);
44
+ const bare = BARE_ID.test(param);
45
+ const opaqueFormat = schema.format === 'uuid' || (typeof schema.pattern === 'string' && /\[0-9a-f|\[a-f0-9/i.test(schema.pattern));
46
+ if (!match && !bare && !opaqueFormat)
47
+ continue;
48
+ const kindWords = match?.[1] ? words(match[1]).map(singular).filter((w) => !JOINERS.has(w)) : [];
49
+ while (kindWords.length > 1 && QUALIFIERS.has(kindWords[0]))
50
+ kindWords.shift();
51
+ const prefix = kindWords.join('_');
52
+ // A bare `id` doesn't say what it identifies (naming/vague-id covers that), so no kind is guessed.
53
+ params.push({ param, kind: prefix || undefined });
54
+ }
55
+ return params;
56
+ }
57
+ function looksLikeIdValue(schema) {
58
+ if (schema.enum)
59
+ return false; // a fixed set of values is chosen, not invented
60
+ const type = schema.type;
61
+ return type === undefined || type === 'string' || type === 'integer' || (Array.isArray(type) && type.includes('string'));
62
+ }
63
+ /** Does some other tool look like it hands out IDs of this kind? */
64
+ function isReturnedBySomeTool(kind, self, tools, common) {
65
+ return tools.some((other) => {
66
+ if (other.name === self.name)
67
+ return false;
68
+ const w = words(other.name).map(singular).filter((x) => !common.has(x));
69
+ const verbs = w.filter((x) => VERBS.has(x));
70
+ const subject = nouns(other.name).filter((x) => !common.has(x));
71
+ // The kind in its name, as a noun or a word run (data_source), or as the verb itself (searchId ← search).
72
+ const mentionsKind = w.join('_').split('_').includes(kind) || `_${w.join('_')}_`.includes(`_${kind}_`);
73
+ const lookup = verbs.some((v) => LOOKUP_VERBS.has(v));
74
+ const collection = verbs.some((v) => COLLECTION_VERBS.has(v)) || w.includes('children');
75
+ const needsSameId = idParams(other).some((p) => p.kind === kind);
76
+ // A list or search for that kind; a get that doesn't itself need the ID.
77
+ if (lookup && mentionsKind && (collection || !needsSameId))
78
+ return true;
79
+ // A search that names nothing in particular: that's how agents find IDs of any kind.
80
+ if (collection && subject.length === 0)
81
+ return true;
82
+ // Creating a thing returns its ID.
83
+ if (verbs.some((v) => CREATE_VERBS.has(v)) && mentionsKind && !needsSameId)
84
+ return true;
85
+ // Or an output schema that carries the ID.
86
+ return outputMentions(other.outputSchema, kind);
87
+ });
88
+ }
89
+ function outputMentions(schema, kind, depth = 0, parent = '') {
90
+ if (!schema || depth > 6)
91
+ return false;
92
+ for (const [name, child] of Object.entries(schema.properties ?? {})) {
93
+ const n = words(name).map(singular).join('_');
94
+ if (n === `${kind}_id` || n === `${kind}_uuid` || (n === 'id' && singular(parent) === kind))
95
+ return true;
96
+ if (outputMentions(child, kind, depth + 1, name))
97
+ return true;
98
+ }
99
+ if (schema.items && outputMentions(schema.items, kind, depth + 1, parent))
100
+ return true;
101
+ return false;
102
+ }
103
+ export const authoredIds = {
104
+ id: 'ids/authored',
105
+ severity: 'warn',
106
+ lesson: '01',
107
+ summary: 'IDs the agent must supply should come from some other tool',
108
+ run(ctx) {
109
+ const findings = [];
110
+ const common = commonWords(ctx.menu.tools.map((t) => t.name));
111
+ for (const tool of ctx.menu.tools) {
112
+ for (const { param, kind } of idParams(tool)) {
113
+ if (!kind || isReturnedBySomeTool(kind, tool, ctx.menu.tools, common))
114
+ continue;
115
+ const schema = tool.inputSchema?.properties?.[param];
116
+ if (saysWhereItComesFrom(schema, ctx.menu.tools, tool.name))
117
+ continue;
118
+ // Optional, and the description already tells the agent not to invent it.
119
+ const optional = !(tool.inputSchema?.required ?? []).includes(param);
120
+ if (optional && toldNotToInvent(tool, param, schema))
121
+ continue;
122
+ findings.push({
123
+ tool: tool.name,
124
+ message: `${tool.name}.${param}: looks like a ${kind} ID the agent must supply, but no tool appears to return one (no list/search/get tool for "${kind}", no output schema with a ${kind} ID). The agent may invent it. Heuristic.`,
125
+ });
126
+ }
127
+ }
128
+ return findings;
129
+ },
130
+ };
131
+ const PROVENANCE = /\b(from|returned by|obtained|output of|result of|as (listed|shown|returned))\b/i;
132
+ /** The parameter's description says where the value comes from, or names the tool that gives it. */
133
+ function saysWhereItComesFrom(schema, tools, self) {
134
+ const text = typeof schema?.description === 'string' ? schema.description : '';
135
+ if (!text)
136
+ return false;
137
+ return PROVENANCE.test(text) || tools.some((t) => t.name !== self && text.includes(t.name));
138
+ }
@@ -0,0 +1,11 @@
1
+ import type { Finding, Severity } from '../types.js';
2
+ import type { Rule, RuleContext } from './rule.js';
3
+ export type { Rule, RuleContext } from './rule.js';
4
+ export declare const MENU_RULES: Rule[];
5
+ export interface RuleSettings {
6
+ /** Per-rule severity override, or 'off'. */
7
+ rules?: Record<string, Severity | 'off'>;
8
+ /** Tool names or globs (`*`) whose findings are dropped. */
9
+ ignore?: string[];
10
+ }
11
+ export declare function runRules(rules: Rule[], ctx: RuleContext, settings?: RuleSettings): Finding[];
@@ -0,0 +1,42 @@
1
+ import { SEVERITY_RANK } from '../types.js';
2
+ import { buried, cut } from './description.js';
3
+ import { nondeterministic } from './determinism.js';
4
+ import { authoredIds } from './ids.js';
5
+ import { route, sharedWord, vagueId } from './naming.js';
6
+ import { cacheHints, deprecated, discover, schema } from './spec.js';
7
+ import { noDryRun, unannotated } from './write.js';
8
+ export const MENU_RULES = [
9
+ nondeterministic,
10
+ vagueId,
11
+ sharedWord,
12
+ route,
13
+ authoredIds,
14
+ buried,
15
+ cut,
16
+ noDryRun,
17
+ unannotated,
18
+ schema,
19
+ discover,
20
+ deprecated,
21
+ cacheHints,
22
+ ];
23
+ export function runRules(rules, ctx, settings = {}) {
24
+ const ignore = (settings.ignore ?? []).map(globToRegExp);
25
+ const findings = [];
26
+ for (const rule of rules) {
27
+ const configured = settings.rules?.[rule.id];
28
+ if (configured === 'off')
29
+ continue;
30
+ if (rule.since && (!ctx.protocolVersion || ctx.protocolVersion < rule.since))
31
+ continue;
32
+ for (const f of rule.run(ctx)) {
33
+ if (f.tool && ignore.some((re) => re.test(f.tool)))
34
+ continue;
35
+ findings.push({ rule: rule.id, ...f, severity: configured ?? f.severity ?? rule.severity });
36
+ }
37
+ }
38
+ return findings.sort((a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity]);
39
+ }
40
+ function globToRegExp(glob) {
41
+ return new RegExp('^' + glob.split('*').map((s) => s.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('.*') + '$');
42
+ }
@@ -0,0 +1,4 @@
1
+ import type { Rule } from './rule.js';
2
+ export declare const vagueId: Rule;
3
+ export declare const sharedWord: Rule;
4
+ export declare const route: Rule;
@@ -0,0 +1,145 @@
1
+ import { commonWords, nouns, singular, words } from '../words.js';
2
+ import { missingWords, negatedMention, routeScores } from '../routes.js';
3
+ const VAGUE_IDS = /^(id|ids|uuid|uuids|identifier|identifiers|ref)$/i;
4
+ export const vagueId = {
5
+ id: 'naming/vague-id',
6
+ severity: 'warn',
7
+ lesson: '04',
8
+ summary: 'ID parameters say which kind of thing they identify',
9
+ run(ctx) {
10
+ const findings = [];
11
+ for (const tool of ctx.menu.tools) {
12
+ for (const param of Object.keys(tool.inputSchema?.properties ?? {})) {
13
+ if (VAGUE_IDS.test(param)) {
14
+ findings.push({
15
+ tool: tool.name,
16
+ message: `${tool.name}.${param}: says "${param}" but not which kind of thing it identifies. Name it after the thing (e.g. form_id) so the agent doesn't pass the wrong ID.`,
17
+ });
18
+ }
19
+ }
20
+ }
21
+ return findings;
22
+ },
23
+ };
24
+ export const sharedWord = {
25
+ id: 'naming/shared-word',
26
+ severity: 'info',
27
+ lesson: '04',
28
+ summary: 'The same noun used for different things across tools',
29
+ run(ctx) {
30
+ const byNoun = new Map();
31
+ const common = commonWords(ctx.menu.tools.map((t) => t.name));
32
+ const subject = (name) => nouns(name).filter((n) => !common.has(n));
33
+ for (const tool of ctx.menu.tools) {
34
+ for (const noun of new Set(subject(tool.name))) {
35
+ byNoun.set(noun, [...(byNoun.get(noun) ?? []), tool]);
36
+ }
37
+ }
38
+ // A word that opens the name of every tool it appears in is a group prefix
39
+ // (task_*, content_*, user_*): a naming convention, not a collision.
40
+ const firstWord = (name) => words(name).find((w) => !common.has(w));
41
+ const groups = [];
42
+ for (const [noun, tools] of byNoun) {
43
+ if (tools.length > 1 && tools.every((t) => singular(firstWord(t.name) ?? '') === noun))
44
+ continue;
45
+ // Tools where the noun is qualified differently and neither qualifier set
46
+ // contains the other: list_team_audits vs get_audit_trail.
47
+ const qualifiers = tools.map((t) => ({ tool: t.name, rest: new Set(subject(t.name).filter((n) => n !== noun)) }));
48
+ const clashes = new Set();
49
+ for (let i = 0; i < qualifiers.length; i++) {
50
+ for (let j = i + 1; j < qualifiers.length; j++) {
51
+ const a = qualifiers[i].rest;
52
+ const b = qualifiers[j].rest;
53
+ const aInB = [...a].every((n) => b.has(n));
54
+ const bInA = [...b].every((n) => a.has(n));
55
+ if (!aInB && !bInA) {
56
+ clashes.add(qualifiers[i].tool);
57
+ clashes.add(qualifiers[j].tool);
58
+ }
59
+ }
60
+ }
61
+ if (clashes.size > 0)
62
+ groups.push({ noun, tools: [...clashes] });
63
+ }
64
+ if (groups.length === 0)
65
+ return [];
66
+ // One summary, not one finding per word: on a big server these are
67
+ // review prompts, and a wall of them hides the findings that matter.
68
+ const shown = groups.slice(0, 8);
69
+ return [
70
+ {
71
+ message: `${groups.length === 1 ? `"${groups[0].noun}" names` : `${groups.length} words name`} different things across tools. Worth a look where an agent could route a question to the wrong one; pin the ones that matter with routes.yml.`,
72
+ detail: shown.map((g) => `"${g.noun}": ${g.tools.join(', ')}`).concat(groups.length > shown.length ? [`…and ${groups.length - shown.length} more (--json lists all)`] : []),
73
+ words: groups,
74
+ },
75
+ ];
76
+ },
77
+ };
78
+ export const route = {
79
+ id: 'naming/route',
80
+ severity: 'error',
81
+ lesson: '04',
82
+ summary: 'routes.yml expectations still hold',
83
+ run(ctx) {
84
+ if (!ctx.routes)
85
+ return [];
86
+ const findings = [];
87
+ const names = new Set(ctx.menu.tools.map((t) => t.name));
88
+ const gated = Boolean(ctx.capabilities.tools?.listChanged);
89
+ for (const [keyword, expectation] of Object.entries(ctx.routes)) {
90
+ const mustMatch = expectation.must_match ?? [];
91
+ const mustNot = expectation.must_not_match ?? [];
92
+ for (const name of [...mustMatch, ...mustNot]) {
93
+ if (!names.has(name)) {
94
+ // A server that announces list changes may unlock the tool later.
95
+ findings.push(gated
96
+ ? { tool: name, severity: 'info', message: `routes.yml "${keyword}" names ${name}, which isn't in the menu yet. The server can change its menu, so it may appear after an unlock; if it was renamed or removed, update routes.yml. Check this route against the full menu.` }
97
+ : { tool: name, message: `routes.yml "${keyword}" names ${name}, which isn't in the menu. Renamed or removed?` });
98
+ }
99
+ }
100
+ const scores = routeScores(keyword, ctx.menu.tools);
101
+ const byName = new Map(ctx.menu.tools.map((t) => [t.name, t]));
102
+ const why = (bad) => {
103
+ const said = negatedMention(keyword, byName.get(bad));
104
+ return said
105
+ ? ` Its description says “${said.length > 160 ? said.slice(0, 157) + '…' : said}”: a disclaimer still puts the words in the tool, and keyword search can't read "not".`
106
+ : '';
107
+ };
108
+ for (const good of mustMatch.filter((n) => names.has(n))) {
109
+ const goodScore = scores.get(good) ?? 0;
110
+ if (goodScore === 0) {
111
+ const missing = missingWords(keyword, byName.get(good));
112
+ findings.push({
113
+ tool: good,
114
+ message: missing.length > 0
115
+ ? `"${keyword}" doesn't match ${good} at all: ${missing.map((w) => `"${w}"`).join(', ')} ${missing.length === 1 ? "isn't" : "aren't"} in its name or description.`
116
+ : `"${keyword}" doesn't match ${good} at all.`,
117
+ });
118
+ continue;
119
+ }
120
+ for (const bad of mustNot.filter((n) => names.has(n))) {
121
+ const badScore = scores.get(bad) ?? 0;
122
+ if (badScore >= goodScore) {
123
+ findings.push({
124
+ tool: good,
125
+ message: `"${keyword}" matches ${bad} (score ${badScore}) at least as well as ${good} (score ${goodScore}). An agent could route it to the wrong tool.${why(bad)}${badScore === goodScore && !why(bad) ? ' Neither the names nor the descriptions separate them: pick a route word only the right tool has, or give it one.' : ''}`,
126
+ });
127
+ }
128
+ }
129
+ }
130
+ // With nothing to beat, must_not_match means: no match at all.
131
+ if (mustMatch.length === 0) {
132
+ for (const bad of mustNot.filter((n) => names.has(n))) {
133
+ const badScore = scores.get(bad) ?? 0;
134
+ if (badScore > 0) {
135
+ findings.push({
136
+ tool: bad,
137
+ message: `"${keyword}" matches ${bad} (score ${badScore}), which routes.yml says must not match it.${why(bad)}`,
138
+ });
139
+ }
140
+ }
141
+ }
142
+ }
143
+ return findings;
144
+ },
145
+ };