toolmenu 0.17.0 → 0.17.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
@@ -383,7 +383,7 @@ server, or from the spec itself. If a rule can't point to one, it doesn't ship.
383
383
  | `spec/tools-capability` | error | The server doesn't declare the `tools` capability, so clients (the official SDK included) never ask for its tools |
384
384
  | `menu/duplicate-name` | error | Two tools with the same name: only one can be called, and some clients reject the list |
385
385
  | `naming/route` | error | A `routes.yml` expectation broke: a keyword now matches the wrong tool at least as well as the right one |
386
- | `description/buried` | warn | Instructions to the agent ("use X instead", "don't retry", "never guess one") past the point where your client cuts descriptions: 2,048 characters in Claude Code, or your `descriptionLimit`. From a real failure: a client cut at 280 characters, and the line that decided routing was at 1,222 |
386
+ | `description/buried` | warn | Instructions to the agent ("use X instead", "don't retry", "never guess one") past the point where your client cuts descriptions: in Claude Code 16,384 characters for a tool loaded through tool search (its default) and 4,096 for one that loads up front, or your `descriptionLimit`. From a real failure: a client cut at 280 characters, and the line that decided routing was at 1,222 |
387
387
  | `description/cut` | info | Descriptions longer than the client sends, with nothing that reads as an instruction past the cut, as one summary that shows where each one is cut. The model gets a prefix that can read as complete |
388
388
  | `description/late-instruction` | info | With the default cut: instructions after character 280, which a client that cuts descriptions short would hide, as one summary. Set `descriptionLimit` and `description/buried` checks your real cut instead. (Before 0.13 this was part of `description/cut`; that id's setting still applies.) |
389
389
  | `naming/vague-id` | warn | Parameters called just `id` that don't say *which* thing, as one summary with a suggested name |
@@ -431,10 +431,12 @@ meant to steer away from, and toolmenu says so.
431
431
  ```
432
432
 
433
433
  `descriptionLimit` is where your client cuts tool descriptions: a number, or a client
434
- whose cut has been reported: `"claude-code"` (2,048, the default: reported in
435
- [anthropics/claude-code#87650](https://github.com/anthropics/claude-code/issues/87650);
436
- the [Claude Code changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)
437
- lists `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` to change it from 2.1.280) or
434
+ whose cut has been reported: `"claude-code"` (the default: Claude Code's own docs,
435
+ [code.claude.com/docs/en/mcp](https://code.claude.com/docs/en/mcp), read 2026-11-02:
436
+ 16,384 characters for a tool loaded through tool search, which is on by default, and
437
+ 4,096 for a tool that loads up front, marked `_meta["anthropic/alwaysLoad"]: true`;
438
+ the cut was 2,048 before v2.1.296), `"claude-code-upfront"` (4,096 for every tool:
439
+ Claude Code with tool search off) or
438
440
  `"amazon-q"` (10,024, reported in
439
441
  [makenotion/notion-mcp-server#145](https://github.com/makenotion/notion-mcp-server/issues/145)).
440
442
  Clients that send descriptions in full don't need a setting beyond that. If your own
package/dist/auto.js CHANGED
@@ -89,6 +89,12 @@ export function autoScenario(menu, options = {}) {
89
89
  continue;
90
90
  }
91
91
  candidates.push({ tool, args: filled.args, rank: rank(tool, filled.args), valued: Object.values(filled.sources).includes('value') });
92
+ // An optional handle (inspect_session { view, session_id? }): the call above
93
+ // leaves it out; one more call passes one that can't exist. Not when the user
94
+ // gave a value for it (it's in args then).
95
+ const optional = modern ? optionalHandleProbe(tool, menu.tools, filled.args) : undefined;
96
+ if (optional)
97
+ candidates.push({ tool, args: optional.args, rank: 4, valued: false, probe: optional.probe });
92
98
  }
93
99
  candidates.sort((x, y) => x.rank - y.rank);
94
100
  const chosen = candidates.slice(0, maxCalls);
@@ -249,6 +255,38 @@ function rank(tool, args) {
249
255
  * checks), only when every other required value is filled, and only for a kind
250
256
  * some tool in the menu creates, so it is a handle the server mints.
251
257
  */
258
+ /** The value a probe passes for a handle: one no server minted. Undefined when the schema rules a guess out (an enum, not a string, a pattern neither made-up value passes). */
259
+ function madeUpHandle(schema, kind) {
260
+ if (!schema || (schema.type !== undefined && schema.type !== 'string') || schema.enum || 'const' in schema)
261
+ return undefined;
262
+ const value = schema.format === 'uuid' || /uuid/i.test(String(schema.pattern ?? '')) ? '00000000-0000-4000-8000-000000000000' : `toolmenu-unknown-${kind}`;
263
+ if (typeof schema.pattern !== 'string')
264
+ return value;
265
+ // A pattern is the server's own check: the made-up handle must pass it (a nil
266
+ // UUID passes most UUID patterns), or the error would be about the format.
267
+ const uuid = '00000000-0000-4000-8000-000000000000';
268
+ for (const candidate of [value, uuid]) {
269
+ try {
270
+ if (new RegExp(schema.pattern, 'u').test(candidate))
271
+ return candidate;
272
+ }
273
+ catch {
274
+ return undefined;
275
+ }
276
+ }
277
+ return undefined;
278
+ }
279
+ /** The one optional handle parameter of a tool, of a kind the menu creates, filled with a made-up handle on top of `args`. */
280
+ function optionalHandleProbe(tool, tools, args) {
281
+ const created = createdKinds(tools);
282
+ const required = new Set(tool.inputSchema?.required ?? []);
283
+ const handles = [...created].flatMap((kind) => handleParams(tool, kind).filter((p) => !required.has(p) && !(p in args)).map((param) => ({ param, kind })));
284
+ if (handles.length !== 1)
285
+ return undefined;
286
+ const [{ param, kind }] = handles;
287
+ const value = madeUpHandle(tool.inputSchema?.properties?.[param], kind);
288
+ return value === undefined ? undefined : { args: { ...args, [param]: value }, probe: { param, kind } };
289
+ }
252
290
  function handleProbe(tool, tools, missing, given) {
253
291
  const created = createdKinds(tools);
254
292
  const handles = missing.flatMap((param) => {
@@ -258,10 +296,9 @@ function handleProbe(tool, tools, missing, given) {
258
296
  if (handles.length !== 1 || missing.length !== 1)
259
297
  return undefined;
260
298
  const [{ param, kind }] = handles;
261
- const schema = tool.inputSchema?.properties?.[param];
262
- if (!schema || (schema.type !== undefined && schema.type !== 'string') || typeof schema.pattern === 'string' || schema.enum)
299
+ const value = madeUpHandle(tool.inputSchema?.properties?.[param], kind);
300
+ if (value === undefined)
263
301
  return undefined;
264
- const value = schema.format === 'uuid' ? '00000000-0000-4000-8000-000000000000' : `toolmenu-unknown-${kind}`;
265
302
  const rest = synthesizeArgs(tool.inputSchema, { ...given, [param]: { value, raw: value } });
266
303
  return rest.ok ? { args: rest.args, probe: { param, kind } } : undefined;
267
304
  }
@@ -353,6 +390,10 @@ export function scenarioYaml(plan, serverName) {
353
390
  for (const step of plan.scenario.steps) {
354
391
  if (step.kind === 'list')
355
392
  lines.push(' - list');
393
+ else if (step.kind === 'call' && step.probe) {
394
+ // A made-up handle is --auto's check, not a step to replay: as written it would fail as a step.
395
+ lines.push(` # --auto called ${step.tool} with a made-up ${step.probe.kind} (session/handle-error); to replay it, put a real one in:`, ` # - call: ${step.tool}`, ` # args: ${JSON.stringify(step.args)}`);
396
+ }
356
397
  else if (step.kind === 'call') {
357
398
  lines.push(` - call: ${step.tool}`);
358
399
  if (Object.keys(step.args).length)
package/dist/cli.js CHANGED
@@ -385,6 +385,11 @@ function parseIdentities(items, kind) {
385
385
  function configIdentities(ids, kind) {
386
386
  if (!ids)
387
387
  return undefined;
388
+ // Credentials for the other kind of server only (env for an HTTP server): that identity would list as nobody in particular.
389
+ const wrong = Object.entries(ids).filter(([, id]) => (kind === 'http' ? !id.headers && id.env : !id.env && id.headers)).map(([name]) => name);
390
+ if (wrong.length) {
391
+ throw new UsageError(`identities ${wrong.join(', ')} in the config give ${kind === 'http' ? 'env vars' : 'headers'} only, and this is ${kind === 'http' ? 'an HTTP' : 'a stdio'} server: give each ${kind === 'http' ? '"headers"' : '"env"'}.`);
392
+ }
388
393
  const list = Object.entries(ids).map(([name, id]) => ({ name, ...(kind === 'http' ? (id.headers ? { headers: id.headers } : {}) : id.env ? { env: id.env } : {}) }));
389
394
  return list.length >= 2 ? list : undefined;
390
395
  }
package/dist/config.d.ts CHANGED
@@ -11,7 +11,8 @@ export interface Config {
11
11
  serverVersionIsRelease?: boolean;
12
12
  /**
13
13
  * Where your client cuts tool descriptions: a number of characters, or a
14
- * known client ("claude-code", "amazon-q"). Default "claude-code" (2,048).
14
+ * known client ("claude-code", "claude-code-upfront", "amazon-q"). Default "claude-code"
15
+ * (16,384 through tool search, 4,096 for a tool that loads up front).
15
16
  */
16
17
  descriptionLimit?: number | string;
17
18
  /** Tools (names or globs) your client sends with the full description. */
package/dist/failures.js CHANGED
@@ -22,7 +22,7 @@ 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
- const AUTH = /\b(?:auth|authentication|credentials?|api[ _-]?key|access token)\b (?:is |are )?missing\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;
25
+ 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
26
  const NETWORK = /\b(ECONNREFUSED|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|ECONNRESET|EHOSTUNREACH)\b|socket hang up|getaddrinfo|network error/i;
27
27
  // "Either 'page_id' OR both 'title' and 'space_key' must be provided" (Atlassian),
28
28
  // "**Input Error**" (Sentry), JSON-RPC's invalid params.
package/dist/probe.js CHANGED
@@ -24,8 +24,12 @@ export function seeded(target, seed) {
24
24
  export function asIdentity(target, identity) {
25
25
  if (!identity)
26
26
  return target;
27
- if (target.kind === 'http')
28
- return { ...target, headers: { ...target.headers, ...identity.headers } };
27
+ if (target.kind === 'http') {
28
+ // Header names match whatever their case: the identity's authorization replaces --header's Authorization.
29
+ const mine = new Set(Object.keys(identity.headers ?? {}).map((h) => h.toLowerCase()));
30
+ const kept = Object.fromEntries(Object.entries(target.headers ?? {}).filter(([h]) => !mine.has(h.toLowerCase())));
31
+ return { ...target, headers: { ...kept, ...identity.headers } };
32
+ }
29
33
  return { ...target, env: { ...target.env, ...identity.env } };
30
34
  }
31
35
  /** A command that starts the server in a container: the seed (and --env) don't reach it unless passed through. */
@@ -5,11 +5,14 @@ export declare const DEFAULT_CLIENT = "claude-code";
5
5
  /**
6
6
  * The cut in characters, the client to name in a message ("Claude Code", "your
7
7
  * client"), and whether it's toolmenu's assumption rather than the user's setting.
8
+ * `perTool`: the cut for one tool, which differs under Claude Code's default for a
9
+ * tool marked to load up front.
8
10
  */
9
11
  export declare function resolveLimit(setting: number | string | undefined): {
10
12
  limit: number;
11
13
  who: string;
12
14
  assumed: boolean;
15
+ perTool: (tool: MenuTool) => number;
13
16
  };
14
17
  interface Instruction {
15
18
  at: number;
@@ -1,24 +1,39 @@
1
1
  import { clip, kept, num } from './rule.js';
2
2
  /*
3
3
  * Clients that cut tool descriptions, and where. Only reported cuts, with sources:
4
- * - claude-code: 2,048 characters, "… [truncated]" appended, silently (anthropics/claude-code#87650);
5
- * the Claude Code changelog lists CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH to change it from 2.1.280.
4
+ * - claude-code: Claude Code's default, where MCP tools are deferred behind tool
5
+ * search: 16,384 characters for a tool loaded through tool search, 4,096 for one
6
+ * that loads up front (marked `_meta["anthropic/alwaysLoad"]: true`). Read
7
+ * 2026-11-02 from https://code.claude.com/docs/en/mcp ("Tool search for MCP server
8
+ * authors"). Before v2.1.296 the cut was 2,048 for every tool.
9
+ * - claude-code-upfront: Claude Code with tool search off (ENABLE_TOOL_SEARCH=false,
10
+ * or a server set to alwaysLoad): 4,096 for every tool, same source.
6
11
  * - amazon-q: 10,024 characters, with a warning (Amazon Q CLI 1.19; makenotion/notion-mcp-server#145).
7
12
  * Other clients send the description in full or don't document a cut. Your own
8
13
  * client may cut elsewhere: set descriptionLimit to its number.
9
14
  */
10
- export const CLIENT_LIMITS = { 'claude-code': 2048, 'amazon-q': 10024 };
15
+ export const CLIENT_LIMITS = { 'claude-code': 16384, 'claude-code-upfront': 4096, 'amazon-q': 10024 };
11
16
  export const DEFAULT_CLIENT = 'claude-code';
17
+ /** Claude Code's cut for a tool that loads up front, not through tool search. */
18
+ const CLAUDE_CODE_UPFRONT = 4096;
12
19
  /**
13
20
  * The cut in characters, the client to name in a message ("Claude Code", "your
14
21
  * client"), and whether it's toolmenu's assumption rather than the user's setting.
22
+ * `perTool`: the cut for one tool, which differs under Claude Code's default for a
23
+ * tool marked to load up front.
15
24
  */
16
25
  export function resolveLimit(setting) {
17
26
  if (typeof setting === 'number')
18
- return { limit: setting, who: 'your client', assumed: false };
19
- const client = setting ?? DEFAULT_CLIENT;
20
- const limit = CLIENT_LIMITS[client] ?? CLIENT_LIMITS[DEFAULT_CLIENT];
21
- return { limit, who: client === 'amazon-q' ? 'Amazon Q CLI' : 'Claude Code', assumed: setting === undefined };
27
+ return { limit: setting, who: 'your client', assumed: false, perTool: () => setting };
28
+ const client = setting !== undefined && setting in CLIENT_LIMITS ? setting : DEFAULT_CLIENT;
29
+ const limit = CLIENT_LIMITS[client];
30
+ const upfront = (tool) => tool._meta?.['anthropic/alwaysLoad'] === true;
31
+ return {
32
+ limit,
33
+ who: client === 'amazon-q' ? 'Amazon Q CLI' : 'Claude Code',
34
+ assumed: setting === undefined,
35
+ perTool: client === 'claude-code' ? (tool) => (upfront(tool) ? CLAUDE_CODE_UPFRONT : limit) : () => limit,
36
+ };
22
37
  }
23
38
  /** The fix's last words when the cut is assumed, not set. */
24
39
  function unlessOtherClient(assumed) {
@@ -100,10 +115,11 @@ export const buried = {
100
115
  lesson: 'truncated description',
101
116
  summary: 'Instructions to the agent sit past the point where your client cuts descriptions',
102
117
  run(ctx) {
103
- const { limit, who, assumed } = resolveLimit(ctx.descriptionLimit);
118
+ const { perTool, who, assumed } = resolveLimit(ctx.descriptionLimit);
104
119
  const all = ctx.menu.tools.map((t) => t.name);
105
120
  const findings = [];
106
121
  for (const tool of ctx.menu.tools) {
122
+ const limit = perTool(tool);
107
123
  const text = tool.description ?? '';
108
124
  if (text.length <= limit || sentInFull(tool, ctx.fullDescriptions))
109
125
  continue;
@@ -141,12 +157,16 @@ export const cut = {
141
157
  lesson: 'truncated description',
142
158
  summary: 'Descriptions longer than your client sends',
143
159
  run(ctx) {
144
- const { limit, who, assumed } = resolveLimit(ctx.descriptionLimit);
160
+ const { perTool, who, assumed } = resolveLimit(ctx.descriptionLimit);
145
161
  const all = ctx.menu.tools.map((t) => t.name);
146
162
  const long = kept(ctx.menu.tools, ctx).filter((tool) => {
147
163
  const text = tool.description ?? '';
164
+ const limit = perTool(tool);
148
165
  return !sentInFull(tool, ctx.fullDescriptions) && text.length > limit && pastTheCut(text, all.filter((n) => n !== tool.name), limit).length === 0;
149
166
  });
167
+ // One number when every cut tool has the same cut (Claude Code cuts up-front tools shorter).
168
+ const limits = [...new Set(long.map(perTool))];
169
+ const limit = limits.length === 1 ? limits[0] : Math.min(...limits);
150
170
  if (long.length === 0)
151
171
  return [];
152
172
  const one = long.length === 1;
@@ -154,10 +174,11 @@ export const cut = {
154
174
  return [
155
175
  {
156
176
  ...(one ? { tool: long[0].name } : {}),
157
- message: `${one ? `The ${long[0].name} description is` : `${long.length} descriptions are`} longer than the ${num(limit)} characters ${who} sends. The model gets the start, with no sign that anything is missing, so a cut list or example can read as complete. Nothing past the cut reads as an instruction to the agent, so this is a check, not a bug.`,
177
+ message: `${one ? `The ${long[0].name} description is` : `${long.length} descriptions are`} longer than ${limits.length === 1 ? `the ${num(limit)} characters ${who} sends` : `${who} sends (${limits.map(num).join(' or ')} characters)`}. The model gets the start, with no sign that anything is missing, so a cut list or example can read as complete. Nothing past the cut reads as an instruction to the agent, so this is a check, not a bug.`,
158
178
  detail: long.map((t) => {
159
179
  const text = t.description ?? '';
160
- return `${t.name}: ${num(text.length)} characters, ${num(text.length - limit)} past the cut, which falls at ${aroundTheCut(text, limit)}`;
180
+ const at = perTool(t);
181
+ return `${t.name}: ${num(text.length)} characters, ${num(text.length - at)} past the cut, which falls at ${aroundTheCut(text, at)}`;
161
182
  }),
162
183
  fix: `Check that what's past the cut ${one ? 'in' : 'in each of'} ${one ? long[0].name : 'these'} can be lost, and move anything the agent needs into the first ${num(limit)} characters.${unlessOtherClient(assumed)}`,
163
184
  },
package/dist/session.js CHANGED
@@ -309,7 +309,14 @@ export async function session(target, scenario, options = {}) {
309
309
  record.outcome = result.isError ? 'tool-error' : 'answered';
310
310
  if (call.input.rounds && !result.isError)
311
311
  record.note = inputNote(call.input, answer);
312
- if (step.probe) {
312
+ const setup = step.probe && result.isError ? classifyFailure(errorText(result), { hadArguments: true }) : undefined;
313
+ if (step.probe && setup && SETUP_FAILURES.has(setup)) {
314
+ // Missing credentials, this machine: the call never got as far as the
315
+ // handle, so it says nothing about it. Counted with the other setup failures.
316
+ record.failure = setup;
317
+ record.note = `called with a made-up ${step.probe.kind}, but it failed before the ${step.probe.kind} mattered: ${clip(errorText(result), 100)}`;
318
+ }
319
+ else if (step.probe) {
313
320
  // A handle that can't exist: a tool error is the answer the spec asks for.
314
321
  const text = result.isError ? errorText(result) : '';
315
322
  record.note = result.isError
@@ -368,7 +375,9 @@ export async function session(target, scenario, options = {}) {
368
375
  if (needed.length)
369
376
  record.note = `${record.note} (needs the client to support ${needed.join(', ')})`;
370
377
  }
371
- if (step.probe && typeof code === 'number' && code !== -32021) {
378
+ const probeFailure = step.probe ? classifyFailure(record.note, { code: typeof code === 'number' ? code : undefined, hadArguments: true }) : undefined;
379
+ // Not a setup failure (credentials, this machine, -32021): those never got as far as the handle.
380
+ if (step.probe && typeof code === 'number' && probeFailure && !SETUP_FAILURES.has(probeFailure)) {
372
381
  // The server's protocol error to a handle that can't exist: the model gets no reason it can act on.
373
382
  if (!handleErrors.some((e) => e.tool === step.tool))
374
383
  handleErrors.push({ step: index, tool: step.tool, probe: step.probe, value: step.args[step.probe.param], message: record.note, code });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "toolmenu",
3
- "version": "0.17.0",
3
+ "version": "0.17.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",