toolmenu 0.20.0 → 0.20.1

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.
package/README.md CHANGED
@@ -399,6 +399,7 @@ server, or from the spec itself. If a rule can't point to one, it doesn't ship.
399
399
  | `ids/handle-lifetime` | info | 2026-07-28: a tool that creates a handle another tool takes back (`start_session` → `session_id`) doesn't say how long it lasts (heuristic) |
400
400
  | `write/unannotated` | warn | Tools named like writes (`delete_`, `send_`…) with no annotations, as one summary grouped by the annotation each name suggests |
401
401
  | `naming/shared-word` | info | Nouns that name different things across tools (`list_team_audits` vs `get_audit_trail`), as one summary |
402
+ | `write/read-only-mismatch` | warn | A tool marked `readOnlyHint: true` whose name says it writes (`create_my_account`): clients act on the hint, and `--auto` doesn't call it on the hint alone (heuristic) |
402
403
  | `write/no-dry-run` | info | Destructive tools with no dry-run parameter or preview tool, as one summary |
403
404
  | `spec/discover` | info | The server only speaks the 2025 protocol, so 2026-07-28 rules are skipped |
404
405
  | `spec/deprecated`, `spec/cache-hints` | info | 2026-07-28: deprecated features still advertised; `ttlMs: 0`, or `cacheScope: "public"` on a server that took credentials |
package/dist/auto.js CHANGED
@@ -3,7 +3,7 @@ import { isMap, isNode, isScalar, parseDocument } from 'yaml';
3
3
  import { synthesizeArgs } from './args.js';
4
4
  import { createdKinds, handleParams } from './rules/handles.js';
5
5
  import { MAX_UNLOCKS, unlockers } from './session.js';
6
- import { COLLECTION_VERBS, LOOKUP_VERBS, verbOf, WRITE_VERBS } from './words.js';
6
+ import { COLLECTION_VERBS, commonWords, leadingVerb, LOOKUP_VERBS, verbOf, WRITE_VERBS } from './words.js';
7
7
  /** Marked or named as a write: never called on the user's word. Says why, or undefined. */
8
8
  export function writeSign(tool) {
9
9
  const a = tool.annotations ?? {};
@@ -42,7 +42,11 @@ export function autoScenario(menu, options = {}) {
42
42
  else
43
43
  assumed.add(name);
44
44
  }
45
- const readOnly = (t) => t.annotations?.readOnlyHint === true || assumed.has(t.name);
45
+ // The server's readOnlyHint, but not against a name that says it writes: a hosted
46
+ // server marked create_my_ideal_account read-only (write/read-only-mismatch).
47
+ const common = commonWords(menu.tools.map((t) => t.name));
48
+ const namedWrite = (t) => WRITE_VERBS.has(leadingVerb(t.name, common) ?? '');
49
+ const readOnly = (t) => (t.annotations?.readOnlyHint === true && !namedWrite(t)) || assumed.has(t.name);
46
50
  const { perTool, ignored: unusedValues } = resolveValues(menu, options.values ?? {});
47
51
  ignored.push(...unusedValues);
48
52
  const candidates = [];
@@ -63,7 +67,9 @@ export function autoScenario(menu, options = {}) {
63
67
  continue;
64
68
  const a = tool.annotations ?? {};
65
69
  if (!readOnly(tool)) {
66
- const write = writeSign(tool);
70
+ const write = a.readOnlyHint === true && namedWrite(tool)
71
+ ? `the server marks it readOnlyHint, but its name starts with "${leadingVerb(tool.name, common)}", a write: not called on the hint alone`
72
+ : writeSign(tool);
67
73
  skipped.push(write || a.readOnlyHint !== undefined ? { tool: tool.name, reason: 'not read-only', ...(write ? { why: write } : {}) } : { tool: tool.name, reason: 'unmarked' });
68
74
  continue;
69
75
  }
package/dist/catalog.js CHANGED
@@ -294,6 +294,10 @@ const FAILED_AS = {
294
294
  what: ['wanted credentials before it would list its commands', 'wanted credentials before they would list their commands'],
295
295
  fix: "Rerun with the server's credentials (--env for a stdio server, --header for HTTP); if these routers aren't yours to watch, ignore this.",
296
296
  },
297
+ payment: {
298
+ what: ['asked for payment before it would list its commands', 'asked for payment before they would list their commands'],
299
+ fix: "Listing these routers' commands costs money here; rerun with an account that has credit if they're yours to watch, or ignore this.",
300
+ },
297
301
  environment: {
298
302
  what: ["needs something this machine doesn't have", "need something this machine doesn't have"],
299
303
  fix: 'Install what the error names where toolmenu starts the server (the same container or CI image), then rerun.',
package/dist/explain.d.ts CHANGED
@@ -124,3 +124,11 @@ export interface ExplainContext {
124
124
  * when there's nothing to add (a refusal for too many requests keeps its own path).
125
125
  */
126
126
  export declare function explain(error: unknown, trace: Trace, context: ExplainContext): unknown;
127
+ /**
128
+ * A proxy this machine sets that Node's built-in fetch ignores: it reads HTTPS_PROXY
129
+ * only with NODE_USE_ENV_PROXY=1 (Node 22.21 and later). Behind such a proxy, every
130
+ * host looks like it doesn't resolve.
131
+ */
132
+ export declare function ignoredProxy(env?: NodeJS.ProcessEnv, host?: string): string | undefined;
133
+ /** What to do about an ignored proxy, for this Node. */
134
+ export declare function proxyAdvice(proxy: string, version?: string): string;
package/dist/explain.js CHANGED
@@ -164,7 +164,10 @@ const HELP_ROW = /^[ \t]*(?:[a-z][\w.-]*(?: [a-z][\w-]*)?(?: [[<][^\]>]*[\]>])*|
164
164
  /** Help output, even when the "Usage:" line scrolled out of the stderr kept: three table rows or more. */
165
165
  const helpRows = (text) => text.split('\n').filter((l) => HELP_ROW.test(l)).length >= 3;
166
166
  // The subcommands that usually start the MCP server, most specific first.
167
- const SUBCOMMANDS = ['mcp start', 'mcp serve', 'server start', 'mcp', 'stdio', 'serve', 'server', 'start'];
167
+ const SUBCOMMANDS = ['mcp start', 'mcp serve', 'server start', 'mcp', 'stdio', 'serve', 'server', 'start', 'run'];
168
+ // A CLI that names its commands when it gets none: "Unknown command: undefined. Expected
169
+ // 'init' or 'run'." (@cloudflare/mcp-server-cloudflare 0.2.0).
170
+ const EXPECTED_COMMANDS = /\b(?:unknown|invalid|missing|no) (?:sub)?command\b[^\n]*?\bexpected:?\s+((?:["'`][a-z][\w-]*["'`](?:,?\s*(?:or\s+)?)?)+)/i;
168
171
  // An HTTP server's address in its log: "MCP server listening on http://localhost:3001/mcp",
169
172
  // "StreamableHTTP endpoint available at http://127.0.0.1:3333/mcp".
170
173
  const HTTP_URL = /\b(?:listening|available|running|serving|started)\b[^\n]{0,60}?(https?:\/\/[^\s"'<>]+)/gi;
@@ -202,6 +205,10 @@ function offeredSubcommand(text) {
202
205
  for (const m of text.matchAll(/\{([^{}\n]*)\}/g))
203
206
  for (const w of m[1].split(','))
204
207
  offered.add(w.trim());
208
+ const expected = EXPECTED_COMMANDS.exec(text);
209
+ if (expected)
210
+ for (const m of expected[1].matchAll(/["'`]([a-z][\w-]*)["'`]/g))
211
+ offered.add(m[1]);
205
212
  let inUsage = false;
206
213
  for (const line of text.split('\n')) {
207
214
  if (!line.trim()) {
@@ -236,7 +243,7 @@ export function startupHint(trace, command, { exited = true } = {}) {
236
243
  const where = url ?? `http://localhost:${port}/mcp`;
237
244
  return `The server started an HTTP server (${where}) instead of talking on its stdin and stdout. Start it in stdio mode (${flag ? `its output mentions ${flag}` : 'often --stdio or --transport stdio'}), or run toolmenu against the address while the server runs: toolmenu snapshot ${where}`;
238
245
  }
239
- if (exited && (USAGE.some((re) => re.test(text)) || helpRows(text))) {
246
+ if (exited && (USAGE.some((re) => re.test(text)) || helpRows(text) || EXPECTED_COMMANDS.test(text))) {
240
247
  const sub = offeredSubcommand(text);
241
248
  return `The command printed its usage and exited: it wants a subcommand or an argument it wasn't given. ${sub ? `Its usage lists “${sub}”: try ${command} ${sub}` : 'Its usage (above) or its docs say what starts the MCP server: add that after the command.'}`;
242
249
  }
@@ -460,6 +467,28 @@ function rejectedCredentials(stderrText) {
460
467
  return REJECTED.exec(stderrText)?.[0];
461
468
  }
462
469
  const REJECTED_NEXT = "Check the API key or token the server was given (--env, or its config): it's likely wrong, expired or for another account. This is a reading of the server's log, not certain: read its stderr above.";
470
+ /**
471
+ * A proxy this machine sets that Node's built-in fetch ignores: it reads HTTPS_PROXY
472
+ * only with NODE_USE_ENV_PROXY=1 (Node 22.21 and later). Behind such a proxy, every
473
+ * host looks like it doesn't resolve.
474
+ */
475
+ export function ignoredProxy(env = process.env, host) {
476
+ if (env.NODE_USE_ENV_PROXY === '1')
477
+ return undefined;
478
+ // A host NO_PROXY exempts goes direct either way: its DNS failure is its own.
479
+ const exempt = (env.NO_PROXY ?? env.no_proxy ?? '').split(',').map((h) => h.trim().replace(/^\*?\./, '').toLowerCase()).filter(Boolean);
480
+ if (host && exempt.some((h) => h === '*' || host.toLowerCase() === h || host.toLowerCase().endsWith(`.${h}`)))
481
+ return undefined;
482
+ return ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy'].find((k) => env[k]);
483
+ }
484
+ /** What to do about an ignored proxy, for this Node. */
485
+ export function proxyAdvice(proxy, version = process.versions.node) {
486
+ const [major, minor] = version.split('.').map(Number);
487
+ const supported = major > 22 || (major === 22 && minor >= 21);
488
+ return supported
489
+ ? `This machine sets ${proxy}, but Node's fetch only goes through it with NODE_USE_ENV_PROXY=1: rerun as NODE_USE_ENV_PROXY=1 toolmenu ….`
490
+ : `This machine sets ${proxy}, but Node's fetch doesn't go through it, and Node ${version} can't be told to: Node 22.21 or later reads it with NODE_USE_ENV_PROXY=1.`;
491
+ }
463
492
  function firstLine(text) {
464
493
  return clean(text.split('\n')[0], 300);
465
494
  }
@@ -477,9 +506,19 @@ function explainHttp(error, trace, context, target) {
477
506
  const innermost = chain.at(-1);
478
507
  // The network, before any HTTP answer.
479
508
  if (code === 'ENOTFOUND' || code === 'EAI_AGAIN') {
480
- return new ConnectError(code === 'ENOTFOUND' ? `Couldn't find ${host}: the name doesn't resolve (DNS: ENOTFOUND).` : `Couldn't look up ${host}: DNS failed for now (EAI_AGAIN).`, [['url', target.url], ['stage', first]], code === 'ENOTFOUND'
481
- ? "Check the host name for typos. If it's right, the server may have moved or shut down: look up its current URL in its docs or registry entry."
482
- : 'Check this machine\'s network and DNS, then retry.', stage, { cause: error });
509
+ const proxy = ignoredProxy(process.env, host);
510
+ return new ConnectError(code === 'ENOTFOUND' ? `Couldn't find ${host}: the name doesn't resolve (DNS: ENOTFOUND).` : `Couldn't look up ${host}: DNS failed for now (EAI_AGAIN).`, [['url', target.url], ['stage', first], ...(proxy ? [['proxy', `${proxy} is set, but Node's fetch doesn't use it`]] : [])], proxy
511
+ ? proxyAdvice(proxy)
512
+ : code === 'ENOTFOUND'
513
+ ? "Check the host name for typos. If it's right, the server may have moved or shut down: look up its current URL in its docs or registry entry."
514
+ : 'Check this machine\'s network and DNS, then retry.', stage, { cause: error });
515
+ }
516
+ // A proxy that won't open the tunnel (undici: "Proxy response (502) !== 200 when HTTP Tunneling").
517
+ const tunnel = chain.map((e) => /Proxy response \((\d+)\) !== 200 when HTTP Tunneling/.exec(e.message)).find(Boolean);
518
+ if (tunnel) {
519
+ return new ConnectError(`The proxy couldn't open a connection to ${host}: it answered the tunnel request with HTTP ${tunnel[1]}.`, [['url', target.url], ['stage', first]], tunnel[1] === '403' || tunnel[1] === '407'
520
+ ? `The proxy refused ${host}: check what HTTPS_PROXY's policy allows, or run from a machine that can reach it directly.`
521
+ : `The proxy couldn't reach ${host} (often: the host is down or doesn't answer). Check that the server is up, e.g. curl -I ${target.url}, then retry.`, stage, { cause: error });
483
522
  }
484
523
  if (code === 'ECONNREFUSED') {
485
524
  return new ConnectError(`Nothing is listening at ${host}:${port}: the connection was refused (ECONNREFUSED).`, [['url', target.url], ['stage', first]], `Start the server, or check the host and port${url.port ? '' : ` (no port in the URL means ${port})`}.`, stage, { cause: error });
@@ -1,4 +1,4 @@
1
- export type FailureClass = 'auth' | 'environment' | 'network' | 'not-found' | 'client' | 'invalid-arguments' | 'other';
1
+ export type FailureClass = 'auth' | 'payment' | 'environment' | 'network' | 'not-found' | 'client' | 'invalid-arguments' | 'other';
2
2
  /** Failures of the setup (credentials, this machine, the network), not of the server. */
3
3
  export declare const SETUP_FAILURES: Set<FailureClass>;
4
4
  /**
package/dist/failures.js CHANGED
@@ -5,7 +5,7 @@
5
5
  * as a finding.
6
6
  */
7
7
  /** Failures of the setup (credentials, this machine, the network), not of the server. */
8
- export const SETUP_FAILURES = new Set(['auth', 'environment', 'network', 'not-found', 'client']);
8
+ export const SETUP_FAILURES = new Set(['auth', 'payment', 'environment', 'network', 'not-found', 'client']);
9
9
  // A tool that asks the client for something toolmenu doesn't offer: "Cannot request
10
10
  // input 'roots' (roots/list): the request's client capabilities do not declare the
11
11
  // required capability" (server-everything's get-roots-list), sampling, elicitation.
@@ -22,6 +22,11 @@ const ENVIRONMENT = /could not find [^.]{0,40}executable|is not found at \/|\bno
22
22
  // Netlify" (Netlify), "The API key you provided was rejected" (Pinecone), "Admin
23
23
  // auth is missing", "Runtime credentials are missing" (securenow). Not a bare
24
24
  // "token": plenty of errors mention one.
25
+ // Hosted servers ask the user to sign in in their own words: "Sign in to Ideal (or create
26
+ // your creator account) to continue", "Connect your Novamris account to read its saved chart".
27
+ const SIGN_IN = /\bsign in to\b|\blog ?in to (?:continue|use)\b|\bconnect your [\w .'-]{1,40}? account\b/i;
28
+ // A paid tool: "Payment required: $0.50 over MPP" (a hosted server), HTTP 402, no credits left.
29
+ const PAYMENT = /\bpayment required\b|\b(?:HTTP|status(?: code)?) 402\b|\binsufficient (?:credits?|balance|funds)\b/i;
25
30
  const AUTH = /\b(?:auth|authentication|credentials?|api[ _-]?key|access token)\b (?:is |are )?missing\b|\bno (?:authentication|auth|credentials?|api[ _-]?keys?|access tokens?|auth tokens?) (?:was |were )?(?:found|provided|configured|set|given)\b|\b(401|403)\b|unauthori[sz]ed|unauth(enticated|error)|forbidden|bad credentials|authori[sz]ation expired|re-?authori[sz]e|not authenticated|not logged (?:in|into)\b(?! to the browser)|authentication (token|failed|required|error)|(invalid|expired|revoked) (api[ _-]?key|access token|token|credentials)|(token|api[ _-]?key|credentials) (is |are )?(not valid|invalid|expired)|(api[ _-]?key|access token|credentials)\b[^.]{0,30}\b(was|were|is|are) (rejected|refused|revoked)|valid (access )?token/i;
26
31
  const NETWORK = /\b(ECONNREFUSED|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|ECONNRESET|EHOSTUNREACH)\b|socket hang up|getaddrinfo|network error/i;
27
32
  // "Either 'page_id' OR both 'title' and 'space_key' must be provided" (Atlassian),
@@ -164,7 +169,9 @@ export function classifyFailure(text, options = {}) {
164
169
  return 'client';
165
170
  if (ENVIRONMENT.test(text))
166
171
  return 'environment';
167
- if (AUTH.test(text))
172
+ if (PAYMENT.test(text))
173
+ return 'payment';
174
+ if (AUTH.test(text) || SIGN_IN.test(text))
168
175
  return 'auth';
169
176
  if (NETWORK.test(text))
170
177
  return 'network';
@@ -176,6 +183,7 @@ export function classifyFailure(text, options = {}) {
176
183
  }
177
184
  export const FAILURE_LABELS = {
178
185
  auth: 'authentication',
186
+ payment: 'payment (a paid tool)',
179
187
  environment: 'something missing on this machine',
180
188
  network: 'the network',
181
189
  'not-found': 'a 404 on a call that named nothing (usually the account or site behind the credentials)',
@@ -194,6 +202,8 @@ export function setupFailureAdvice(classes, transport) {
194
202
  const steps = [];
195
203
  if (set.has('auth') || set.has('not-found'))
196
204
  steps.push(`If the errors are about credentials, rerun with real ones (${credentials}); a test account is enough.`);
205
+ if (set.has('payment'))
206
+ steps.push('If a tool asks for payment, it can\'t be checked without paying: leave it out of the scenario, or run with an account that has credit.');
197
207
  if (set.has('environment'))
198
208
  steps.push('If something is missing on this machine (a browser, a binary, a module), install it where the server runs, or run the server in its own container image.');
199
209
  if (set.has('client'))
@@ -8,7 +8,7 @@ import { handleLifetime } from './handles.js';
8
8
  import { authVariance, cacheScopePublic } from './identities.js';
9
9
  import { route, sharedWord, vagueId } from './naming.js';
10
10
  import { cacheHints, deprecated, discover, duplicateName, schema, serverInfo, toolsCapability } from './spec.js';
11
- import { noDryRun, unannotated } from './write.js';
11
+ import { noDryRun, readOnlyMismatch, unannotated } from './write.js';
12
12
  import { gated } from './gated.js';
13
13
  import { xMcpHeader } from './headers.js';
14
14
  import { schemaRef } from './refs.js';
@@ -32,6 +32,7 @@ export const MENU_RULES = [
32
32
  lateInstruction,
33
33
  noDryRun,
34
34
  unannotated,
35
+ readOnlyMismatch,
35
36
  schema,
36
37
  xMcpHeader,
37
38
  schemaRef,
@@ -47,7 +47,7 @@ export const listSchema = {
47
47
  if (r.first.error) {
48
48
  const said = r.first.error.replace(/[.\s]+$/, '');
49
49
  const failure = classifyFailure(r.first.error, { code: r.first.code });
50
- if (r.first.code === -32601 || /method not found/i.test(r.first.error)) {
50
+ if (r.first.code === -32601 || /method not (?:found|supported|implemented)/i.test(r.first.error)) {
51
51
  // A server that declares resources but answers one of their methods with Method not found.
52
52
  findings.push({
53
53
  severity: 'info',
@@ -1,3 +1,10 @@
1
1
  import { type Rule } from './rule.js';
2
2
  export declare const unannotated: Rule;
3
+ /**
4
+ * readOnlyHint: true on a tool whose name says it writes (create_, delete_, send_…).
5
+ * The spec's readOnlyHint means "the tool does not modify its environment", and
6
+ * clients and agents act on it: run it without asking, retry it, call it to explore.
7
+ * Seen on a hosted server: create_my_ideal_account, marked read-only.
8
+ */
9
+ export declare const readOnlyMismatch: Rule;
3
10
  export declare const noDryRun: Rule;
@@ -1,11 +1,16 @@
1
- import { WRITE_VERBS, nouns, verbOf, words } from '../words.js';
1
+ import { WRITE_VERBS, commonWords, leadingVerb, nouns, words } from '../words.js';
2
2
  import { count, kept, names } from './rule.js';
3
3
  const DRY_RUN_PARAMS = /^(dry[_-]?run|preview|validate[_-]?only|simulate|plan|what[_-]?if)$/i;
4
4
  const PREVIEW_WORDS = new Set(['preview', 'validate', 'plan', 'simulate', 'dry']);
5
5
  /** Write verbs that only add something; the others delete or overwrite. A guess from the name. */
6
6
  const ADDITIVE_VERBS = new Set(['create', 'add', 'insert', 'send', 'post', 'publish', 'submit', 'upload', 'assign', 'invite', 'approve']);
7
- function isWriteByName(tool) {
8
- return WRITE_VERBS.has(verbOf(tool.name) ?? '');
7
+ /**
8
+ * Named like a write: the name leads with a write verb, after a prefix most of the
9
+ * menu's tools share. Not a verb further in: percent_change computes a change, and
10
+ * score_status_update scores one (both seen on scanned servers).
11
+ */
12
+ function isWriteByName(tool, common = new Set()) {
13
+ return WRITE_VERBS.has(leadingVerb(tool.name, common) ?? '');
9
14
  }
10
15
  function hasAnnotations(tool) {
11
16
  return !!tool.annotations && Object.keys(tool.annotations).length > 0;
@@ -17,10 +22,11 @@ export const unannotated = {
17
22
  lesson: '02',
18
23
  summary: 'Tools that look like writes carry annotations',
19
24
  run(ctx) {
20
- const bare = kept(ctx.menu.tools, ctx).filter((t) => isWriteByName(t) && !hasAnnotations(t));
25
+ const common = commonWords(ctx.menu.tools.map((t) => t.name));
26
+ const bare = kept(ctx.menu.tools, ctx).filter((t) => isWriteByName(t, common) && !hasAnnotations(t));
21
27
  if (bare.length === 0)
22
28
  return [];
23
- const additive = (t) => ADDITIVE_VERBS.has(verbOf(t.name));
29
+ const additive = (t) => ADDITIVE_VERBS.has(leadingVerb(t.name, common));
24
30
  // One finding, not one per tool: the same gap in 53 tools is one thing to fix.
25
31
  if (bare.length === 1) {
26
32
  const [tool] = bare;
@@ -29,12 +35,12 @@ export const unannotated = {
29
35
  {
30
36
  tool: tool.name,
31
37
  confidence: 'unsure',
32
- message: `${tool.name} is named like a write ("${verbOf(tool.name)}") and has no annotations. ${WHY}`,
38
+ message: `${tool.name} is named like a write ("${leadingVerb(tool.name, common)}") and has no annotations. ${WHY}`,
33
39
  fix: `Add annotations: { readOnlyHint: false, destructiveHint: ${!adds} } to ${tool.name} (${adds ? 'true if it can also delete or overwrite' : 'false if it only adds'}), or { readOnlyHint: true } if it changes nothing.`,
34
40
  },
35
41
  ];
36
42
  }
37
- const verbs = [...new Set(bare.map((t) => `${verbOf(t.name)}…`))];
43
+ const verbs = [...new Set(bare.map((t) => `${leadingVerb(t.name, common)}…`))];
38
44
  const overwrites = bare.filter((t) => !additive(t)).map((t) => t.name);
39
45
  const adds = bare.filter(additive).map((t) => t.name);
40
46
  return [
@@ -50,6 +56,34 @@ export const unannotated = {
50
56
  ];
51
57
  },
52
58
  };
59
+ /**
60
+ * readOnlyHint: true on a tool whose name says it writes (create_, delete_, send_…).
61
+ * The spec's readOnlyHint means "the tool does not modify its environment", and
62
+ * clients and agents act on it: run it without asking, retry it, call it to explore.
63
+ * Seen on a hosted server: create_my_ideal_account, marked read-only.
64
+ */
65
+ export const readOnlyMismatch = {
66
+ id: 'write/read-only-mismatch',
67
+ severity: 'warn',
68
+ summary: 'Tools marked read-only whose names say they write',
69
+ run(ctx) {
70
+ const common = commonWords(ctx.menu.tools.map((t) => t.name));
71
+ const lead = (t) => leadingVerb(t.name, common);
72
+ const odd = kept(ctx.menu.tools, ctx).filter((t) => t.annotations?.readOnlyHint === true && WRITE_VERBS.has(lead(t) ?? ''));
73
+ if (!odd.length)
74
+ return [];
75
+ const one = odd.length === 1;
76
+ return [
77
+ {
78
+ ...(one ? { tool: odd[0].name } : {}),
79
+ confidence: 'unsure',
80
+ message: `${one ? `${odd[0].name} is` : `${count(odd.length, 'tool')} are`} marked readOnlyHint: true but named like ${one ? 'a write' : 'writes'} (${names([...new Set(odd.map((t) => `${lead(t)}…`))], 6)}). readOnlyHint says a tool doesn't change anything, and clients act on it: one may run ${one ? 'it' : 'them'} without asking the user, or call ${one ? 'it' : 'them'} just to look. If ${one ? 'it changes' : 'they change'} anything, even state on the server, the hint is wrong.`,
81
+ ...(one ? {} : { detail: [odd.map((t) => t.name).join(', ')] }),
82
+ fix: `Where the tool changes anything, set readOnlyHint: false (and destructiveHint to whether it deletes or overwrites); where it truly only reads, a name without the write verb says so to agents too.`,
83
+ },
84
+ ];
85
+ },
86
+ };
53
87
  export const noDryRun = {
54
88
  id: 'write/no-dry-run',
55
89
  severity: 'info',
package/dist/words.d.ts CHANGED
@@ -15,5 +15,11 @@ export declare function article(word: string): 'a' | 'an';
15
15
  export declare function commonWords(names: string[]): Set<string>;
16
16
  /** The tool's verb: the first word that is one, skipping prefixes like `API-`. */
17
17
  export declare function verbOf(name: string): string | undefined;
18
+ /**
19
+ * The verb a name leads with, after any prefix most of the menu's tools share
20
+ * (copilot_studio_clear_read_cache → clear): the verb of what the tool does, not one
21
+ * in its object (score_status_update scores; "update" is what it scores).
22
+ */
23
+ export declare function leadingVerb(name: string, common?: Set<string>): string | undefined;
18
24
  /** The nouns in a tool name, singular: `list_team_audits` → team, audit. */
19
25
  export declare function nouns(name: string): string[];
package/dist/words.js CHANGED
@@ -68,6 +68,15 @@ export function commonWords(names) {
68
68
  export function verbOf(name) {
69
69
  return words(name).find((w) => VERBS.has(w));
70
70
  }
71
+ /**
72
+ * The verb a name leads with, after any prefix most of the menu's tools share
73
+ * (copilot_studio_clear_read_cache → clear): the verb of what the tool does, not one
74
+ * in its object (score_status_update scores; "update" is what it scores).
75
+ */
76
+ export function leadingVerb(name, common = new Set()) {
77
+ const first = words(name).find((w) => !common.has(w));
78
+ return first !== undefined && VERBS.has(first) ? first : undefined;
79
+ }
71
80
  /** The nouns in a tool name, singular: `list_team_audits` → team, audit. */
72
81
  export function nouns(name) {
73
82
  return words(name)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "toolmenu",
3
- "version": "0.20.0",
3
+ "version": "0.20.1",
4
4
  "description": "Lint your MCP server's tool menu for changes that confuse agents or break caches.",
5
5
  "author": "Nikša Perović (https://niksa.me)",
6
6
  "main": "dist/index.js",