@meantjs/tools 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 The five Candid Profile library packages (`@meantjs/profile`, `/format`, `/consent`, `/tools`, `/reconcile`) release together under one version and pin each other exactly; a version appears here even when this package did not change. Release steps: `docs/releasing.md` in the repository.
 
+## 0.2.0 — 2026-10-28
+
+- One tool per case (D-053): a method whose single argument is a variant with an `intent` or an `effect` on any case
+  gets `<method>_<Case>` (a read) or `prepare_<method>_<Case>` for each case, instead of one tool for the method. The
+  plan carries `case`; `caseToolName` is exported. Resolved forms without case tags give the same tools as before.
+- An EVM contract's resolved form (`"chain": "evm"`, spec §15) is refused with a `TypeError`: its tools need nonces
+  and receipts, a later phase.
+- Types: `ToolDefinition.inputSchema.properties` is `Record<string, JsonSchemaInput>`, not strings only. Since
+  0.1.0 (D-050) a record, variant or vec input is one JSON input whose schema is an object, a `oneOf` of
+  `{ tag, value }` cases or an array; the new exported types `JsonSchemaObject`, `JsonSchemaVariant`,
+  `JsonSchemaCase`, `JsonSchemaArray` and `JsonSchemaNull` say so. The generated schemas do not change.
+
 ## 0.1.0 — 2026-10-28
 
 First published version.

package/README.md

@@ -46,6 +46,7 @@ await layer.callTool("commit", { preview_id: "p1" });
   - **Text and bool** (D-050). A `text` position is a text input taken as given (not trimmed), checked against its `text` tag: `max_len` and `range` lengths in code points (1024 without either), `pattern` (unanchored, with the `u` flag) and `format` (`url`: an http or https URL; `email`); lone surrogates are refused. A pattern the layer will not run skips the method with the reason: over 256 characters, not valid with the `u` flag, a back reference, a lookaround, or a group that repeats inside a group that repeats (exponential backtracking). A `bool` position is `"true"` or `"false"`.
   - **Nested arguments** (D-050). A record, variant or `vec` that no value tag reads (an account record is still one text input) is one input in JSON: an object for a record (unknown keys refused), `{ "tag": "Case", "value": … }` for a variant case (no `value` for a `null` case), an array for a `vec` (`null` for an element that is none), and each leaf read by its own rule above, as text. At most 256 elements in a `vec` and 4096 values in one input. An issue names its place (`$args[0].command.Follow.followees[1].id`). The input's JSON Schema mirrors the shape (`oneOf` per case, `maxItems`) with each leaf's own schema. A `null` or `reserved` field takes no input, and neither does a lone `null` or `reserved` argument. A recursive position, or a field or case named by a number, still skips the method.
   - **An outcome with `default` alone** (D-049): every reply of the method is that class, whatever its result; outcome keys still need a method with one result.
+  - **One tool per case** (D-053, rule 3 of B2). A method whose single argument is a variant with an `intent` or an `effect` on any of its cases gets one tool for each case instead of one for the method: `<method>_<Case>` when the case's effect is a read (every case of a query, or a read-only update case), else `prepare_<method>_<Case>`. Its inputs are the case's payload, read as a single argument is (a record's fields, one value-tagged input, none for a `null` case, else one JSON input), and it sends `{ tag: Case, value }` (a bare `{ tag }` for a `null` case). Its title is the case's intent, else its `describe`, else `<method> <Case>`; its effect the case's, else the method's; the method's `outcome` applies, and a prepare tool needs an intent, the case's or the method's. The case is part of the intent's identity, so two cases with the same inputs are two previews. A case without a rule, or without a name (`#3`), is skipped alone, with `case <Case>:` in front of the reason; a method with an idempotency stamp gets no case tools yet (the stamp would sit inside a case). A tagged variant deeper in the argument (inside a record) stays one JSON input.
 
   A method with no rule (including a query with more than one result) is skipped and reported in `buildToolPlans(resolved).skipped`, not thrown on; so is every method whose tool name is `commit` or is another method's tool name, every method with an argument field named `canister_id` (the canister selector's input), and every update whose stamp is the whole argument rather than a field (a required stamp field is filled like an optional one). The stamp and the outcome keys are relpaths, matched by the position they resolve to: `(0).Ok`, `.Ok` and `Ok` are one key.
 - **Input words.** Each input's description is the format library's `Formatter.describe()`, with the canisters' decimals and symbol filled in when they agree (and its regular-expression `pattern` for amounts and subaccounts). When the canisters disagree the words give the grammar without the numbers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meantjs/tools",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Agent tools from any Candid Profile resolved form: tool definitions, exact input reading, and a tool layer with a confirmation hook, an injected encoder, call and clock. Browser-safe.",
   "license": "Apache-2.0",
   "repository": {
@@ -44,7 +44,7 @@
     "test": "node --test \"test/*.test.mjs\""
   },
   "dependencies": {
-    "@meantjs/format": "0.1.0"
+    "@meantjs/format": "0.2.0"
   },
   "devDependencies": {
     "@candid-core/schema": "0.5.0",

package/src/index.d.mts

@@ -26,13 +26,50 @@ export interface JsonSchemaString {
   pattern?: string;
 }
 
+/** The schema of one input: text read by its own rules, or the JSON shape of a record, variant or vec (D-050). */
+export type JsonSchemaInput = JsonSchemaString | JsonSchemaObject | JsonSchemaVariant | JsonSchemaArray;
+
+/** A record: one property per field that is an input. */
+export interface JsonSchemaObject {
+  type: "object";
+  description: string;
+  properties: Record<string, JsonSchemaInput>;
+  required: string[];
+  additionalProperties: false;
+}
+
+/** A variant: one `{ tag, value }` object per case; a case without a value has `tag` alone. */
+export interface JsonSchemaVariant {
+  oneOf: JsonSchemaCase[];
+  description: string;
+}
+
+export interface JsonSchemaCase {
+  type: "object";
+  properties: { tag: { const: string }; value?: JsonSchemaInput };
+  required: ["tag"] | ["tag", "value"];
+  additionalProperties: false;
+}
+
+export interface JsonSchemaNull {
+  type: "null";
+}
+
+/** A vec: an element that is none is a JSON null, so an opt element is its schema or null. */
+export interface JsonSchemaArray {
+  type: "array";
+  description: string;
+  items: JsonSchemaInput | JsonSchemaNull | { anyOf: [JsonSchemaInput, JsonSchemaNull] };
+  maxItems: number;
+}
+
 export interface ToolDefinition {
   name: string;
   description: string;
   inputSchema: {
     $schema: string;
     type: "object";
-    properties: Record<string, JsonSchemaString>;
+    properties: Record<string, JsonSchemaInput>;
     required: string[];
     additionalProperties: false;
   };
@@ -59,6 +96,8 @@ export interface ToolPlan {
   replicated: boolean;
   title: string;
   effect: { kind: string; irreversible: boolean; replicated?: boolean };
+  /** For a tool per case of the method's variant argument (D-053): the case it sends. */
+  case?: string;
   /** The method's arguments, in order. */
   argNodes: unknown[];
   params: ToolParam[];
@@ -79,6 +118,8 @@ export interface InputIssue {
 
 export const COMMIT_TOOL: "commit";
 export function prepareToolName(method: string): string;
+/** The tool of one case of a method's variant argument (D-053): `<method>_<Case>` for a read, else `prepare_<method>_<Case>`. */
+export function caseToolName(method: string, label: string, read: boolean): string;
 export function resolvedMethods(resolved: ResolvedForm | ResolvedForm[]): [string, unknown][];
 export function buildToolPlans(resolved: ResolvedForm | ResolvedForm[]): { plans: Map<string, ToolPlan>; skipped: { method: string; reason: string }[] };
 export function toolDefinitions(resolved: ResolvedForm | ResolvedForm[], options?: { canisters?: Canister[] }): ToolDefinition[];

package/src/index.mjs

@@ -1,6 +1,6 @@
 // @meantjs/tools: agent tools from any resolved form, browser-safe (#16).
 // Arm C (packages/mcp-adapters) stays the eval arm with its frozen texts; this is the product tool layer.
 
-export { COMMIT_TOOL, buildToolPlans, prepareToolName, resolvedMethods, toolDefinitions } from "./plan.mjs";
+export { COMMIT_TOOL, buildToolPlans, caseToolName, prepareToolName, resolvedMethods, toolDefinitions } from "./plan.mjs";
 export { displayValue, readToolInput, toCandid } from "./input.mjs";
 export { classifyReply, createToolLayer, nameEntries } from "./layer.mjs";

package/src/input.mjs

@@ -468,7 +468,7 @@ function readInput(node, input, path, param, ctx) {
  *   input may use (spec 5.3, D-045), read when the call is prepared
  * @returns {{ value: unknown, identity: [string, unknown][] } | { issues: { param: string, path: string, code: string, message: string }[] }}
  *   `value` is the method's single argument (undefined for a method without one; the argument tuple, an array, for a
- *   method with more than one), with the stamp left null; `identity` is what the inputs add to the intent's
+ *   method with more than one; for a tool per case, the case `{ tag, value }` around its payload), with the stamp left null; `identity` is what the inputs add to the intent's
  *   identity. Issue codes are the format library's, plus E_INPUT (not an object), E_UNKNOWN_PARAM, E_MISSING and
  *   E_TYPE (an input that is not text, or JSON of the wrong shape for a record, variant or vec input), and for a
  *   `named` input E_NAMES_UNREAD (its set's names were not read), E_NAME_NOT_FOUND and E_NAME_AMBIGUOUS (several
@@ -510,10 +510,16 @@ export function readToolInput(plan, input, { refs = {}, now, names = {} } = {})
   if (issues.length > 0) return { issues };
   if (plan.argNodes?.length > 1) return { value: plan.fields.map((field) => (field.role === "param" ? values.get(field.name) : null)), identity };
   if (plan.argNode === undefined) return { value: undefined, identity };
-  if (plan.rootParam) return { value: values.get(plan.params[0].name), identity };
-  if (plan.rootNull) return { value: null, identity };
-  const value = Object.fromEntries(plan.fields.map((field) => [field.name, field.role === "param" ? values.get(field.name) : null]));
-  return { value, identity };
+  const value = plan.rootParam
+    ? values.get(plan.params[0].name)
+    : plan.rootNull
+      ? null
+      : Object.fromEntries(plan.fields.map((field) => [field.name, field.role === "param" ? values.get(field.name) : null]));
+  if (plan.case === undefined) return { value, identity };
+  // a tool per case (D-053): the payload goes into its case, a null payload as candid-core's bare { tag }; the case is
+  // part of the intent, so two cases with the same inputs are two intents
+  const bare = plan.caseNode.candid === "null" && plan.caseNode.optional !== true;
+  return { value: bare ? { tag: plan.case } : { tag: plan.case, value }, identity: [[plan.case, identity]] };
 }
 
 /**

package/src/plan.mjs

@@ -26,6 +26,12 @@
 //     rules (input.mjs, `inputWithoutRule`); a single argument that is a variant or a vec is the input `arg0`;
 //   - outcome keys may start with a record field (`result.Ok` over `record { result : opt variant { Ok; Err } }`);
 //   - an outcome with `default` alone classes every reply of a method whose result has no variant to select.
+// And one tool per case (B2 rule 3 of proposal w9-b3wallet-gaps.md, D-053): a method whose single argument is a
+// variant with an `intent` or `effect` on any of its cases gets a tool for each case, `<method>_<Case>` for a read and
+// `prepare_<method>_<Case>` otherwise. Its inputs are the case's payload, read as a single argument is; its title is
+// the case's intent, else its `describe`, else `<method> <Case>`; its effect is the case's, else the method's; and the
+// method's `idempotency` and `outcome` apply. A method with an idempotency stamp has no case tools yet (the stamp would
+// sit inside a case), and a tagged variant deeper in the argument stays one JSON input.
 //
 // The input words come from the format library (`Formatter.describe()`), so a form hint and a tool schema read
 // one grammar. Arm C keeps its own frozen words (D-015, D-030, D-031).
@@ -34,6 +40,8 @@ import { MAX_VEC_ITEMS, inputReader, inputWithoutRule, nestedRole, readAs } from
 
 export const COMMIT_TOOL = "commit";
 export const prepareToolName = (method) => `prepare_${method}`;
+/** The tool of one case of a method's variant argument (D-053): `<method>_<Case>` for a read, else `prepare_<method>_<Case>`. */
+export const caseToolName = (method, label, read) => (read ? `${method}_${label}` : prepareToolName(`${method}_${label}`));
 const byName = ([a], [b]) => (a < b ? -1 : a > b ? 1 : 0);
 
 /** The Candid id of a label: `#n` is n, a name is its idl hash (profile spec 3.2). */
@@ -68,6 +76,8 @@ export function resolvedMethods(resolved) {
     if (doc === null || typeof doc !== "object" || doc.format !== "candid-profile-resolved" || doc.format_version !== 0) {
       throw new TypeError("resolved: not a candid-profile-resolved v0 document");
     }
+    // An EVM contract's form (profile spec section 15) has ABI positions, nonces and receipts: its tools are phase 2.
+    if (doc.chain !== undefined) throw new TypeError(`resolved: a resolved form of chain ${JSON.stringify(doc.chain)} has no tools yet; this layer calls Internet Computer canisters`);
     for (const [name, method] of Object.entries(doc.methods ?? {})) {
       const seen = methods.get(name);
       if (seen === undefined) methods.set(name, method);
@@ -128,25 +138,69 @@ function outcomeKeyWithoutRule(classes, result) {
   return undefined;
 }
 
-/** @returns {object | { skip: string }} */
-function planMethod(name, m) {
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const hasCaseTag = (node) => isObject(node?.tags) && (isObject(node.tags.intent) || isObject(node.tags.effect));
+
+/**
+ * The cases of a method's single variant argument when any of them has an `intent` or an `effect` (D-053), else
+ * undefined: such a method gets one tool per case.
+ */
+function taggedCases(m) {
+  const root = Array.isArray(m.args) && m.args.length === 1 ? m.args[0] : undefined;
+  if (root?.candid !== "variant" || readAs(root)) return undefined;
+  const cases = Object.entries(root.cases ?? {});
+  return cases.some(([, node]) => hasCaseTag(node)) ? cases : undefined;
+}
+
+/**
+ * A method's tools: one, or one per case of its variant argument (D-053).
+ * @returns {{ plans: object[], skipped: string[] }}  the plans, and why each tool it would have is not made
+ */
+function planTools(name, m) {
+  const cases = taggedCases(m);
+  if (cases === undefined) {
+    const p = planMethod(name, m);
+    return p.skip ? { plans: [], skipped: [p.skip] } : { plans: [p], skipped: [] };
+  }
+  if (m.tags?.idempotency) return { plans: [], skipped: ["tools per case of a method with an idempotency stamp have no rule yet (the stamp would sit inside a case)"] };
+  const plans = [];
+  const skipped = [];
+  for (const kase of cases) {
+    const p = /^[A-Za-z_][A-Za-z0-9_]*$/.test(kase[0]) ? planMethod(name, m, kase) : { skip: "a case without a name has no tool name" };
+    if (p.skip) skipped.push(`case ${kase[0]}: ${p.skip}`);
+    else plans.push(p);
+  }
+  return { plans, skipped };
+}
+
+/**
+ * @param {[string, object]} [kase]  for a tool per case (D-053): the case's label and node in the variant argument
+ * @returns {object | { skip: string }}
+ */
+function planMethod(name, m, kase) {
   const tags = m.tags ?? {};
-  const effect = tags.effect?.args;
+  const own = kase === undefined ? tags : isObject(kase[1].tags) ? kase[1].tags : {}; // the case's tags, for a case tool
+  // the call's effect and intent: the case's, else the method's (spec 5.2 and 5.3)
+  const effect = own.effect?.args ?? tags.effect?.args;
+  const intent = own.intent?.args ?? tags.intent?.args;
   // a read-only update (D-038) is a read for consumers, and must be sent as an update so that its answer is certified
   const replicated = m.mode === "update" && effect?.kind === "read" && effect.irreversible === false && effect.replicated === true;
   // a composite query is a read too (arm C has none to meet: the ICRC-1/2 packs declare only queries and updates)
   const read = m.mode === "query" || m.mode === "composite_query" || replicated;
   const args = Array.isArray(m.args) ? m.args : [];
   const plan = {
-    name: read ? name : prepareToolName(name),
+    name: kase !== undefined ? caseToolName(name, kase[0], read) : read ? name : prepareToolName(name),
     kind: read ? "read" : "prepare",
     method: name,
+    /** for a tool per case (D-053): the case of the variant argument it sends, and that case's node */
+    case: kase?.[0],
+    caseNode: kase?.[1],
     mode: m.mode,
     /** a read sent as an update call */
     replicated,
     effect: effect ?? (read ? { kind: "read", irreversible: false } : { kind: "write", irreversible: true }),
-    describe: tags.describe?.args,
-    intent: tags.intent?.args,
+    describe: own.describe?.args,
+    intent,
     idempotency: tags.idempotency?.args,
     outcome: tags.outcome?.args,
     /** the method's single argument, or undefined (none, or more than one) */
@@ -164,12 +218,13 @@ function planMethod(name, m) {
     rootNull: false,
     results: m.results ?? [],
   };
-  plan.title = plan.intent?.title ?? plan.describe?.label ?? name;
+  plan.title = kase !== undefined ? (own.intent?.args?.title ?? plan.describe?.label ?? `${name} ${kase[0]}`) : (plan.intent?.title ?? plan.describe?.label ?? name);
   if (read && plan.results.length > 1) return { skip: "a query with more than one result has no rule (only the first would be shown)" };
   // the stamp would be an input, or left unset: the stamp rules are for writes
   if (replicated && plan.idempotency) return { skip: "a read-only update with an idempotency stamp has no rule" };
   if (!read) {
-    for (const need of ["intent", "outcome"]) if (!tags[need]) return { skip: `an update method needs the ${need} tag` };
+    if (!intent) return { skip: "an update method needs the intent tag" };
+    if (!tags.outcome) return { skip: "an update method needs the outcome tag" };
     if (plan.idempotency && plan.idempotency.mode !== "replay_same_payload") return { skip: `idempotency mode ${plan.idempotency.mode} has no rule` };
     if (!plan.idempotency && [...Object.values(plan.outcome.classes ?? {}), plan.outcome.default].includes("retry_new")) {
       return { skip: "the outcome class retry_new renews an idempotency stamp, and this method has none" };
@@ -192,49 +247,64 @@ function planMethod(name, m) {
       if (c.role === "param") plan.params.push({ name: `arg${i}`, node, optional, path: `$args[${i}]` });
     }
   } else if (args.length === 1) {
-    const root = args[0];
-    const tag = readAs(root);
-    if (tag) {
-      const why = inputWithoutRule(root, "(0)"); // a text pattern the layer does not run
-      if (why) return { skip: why };
-      // the stamp is filled by the tool layer, so it must be a field beside the inputs, never the whole argument
-      if (plan.idempotency) return { skip: `the stamp ${plan.idempotency.stamp} must name one field of the argument record` };
-      plan.rootParam = true;
-      plan.params.push({ name: tag, node: root, optional: root.optional === true, path: "$args[0]" });
-    } else if (root.candid === "record") {
-      let stampId;
-      if (plan.idempotency) {
-        const ids = relpathIds(plan.idempotency.stamp);
-        if (ids === null || ids.length !== 1) return { skip: `the stamp ${plan.idempotency.stamp} must name one field of the argument record` };
-        stampId = ids[0];
-      }
-      for (const [fname, fnode] of Object.entries(root.fields ?? {})) {
-        // the canister selector of every tool (toolDefinitions, the tool layer) owns this input name
-        if (fname === "canister_id") return { skip: "an argument field named canister_id would collide with the canister selector input" };
-        const c = classifyField(fname, fnode, stampId);
-        if (c.skip) return c;
-        if (c.role === "stamp") plan.stampField = fname;
-        const optional = fnode.optional === true;
-        plan.fields.push({ name: fname, node: fnode, role: c.role, optional });
-        if (c.role === "param") plan.params.push({ name: fname, node: fnode, optional, path: `$args[0].${fname}` });
-      }
-      if (plan.idempotency && !plan.fields.some((f) => f.role === "stamp")) return { skip: `the stamp field ${plan.idempotency.stamp} is not an argument field` };
-    } else if (root.candid === "null" || root.candid === "reserved") {
-      // one value only, so nothing to ask for: the tool takes no input and sends null
-      if (plan.idempotency) return { skip: `the stamp ${plan.idempotency.stamp} must name one field of the argument record` };
-      plan.rootNull = true;
-    } else {
-      // a variant or a vec (or a record a value tag does not cover) is one JSON input
-      const why = inputWithoutRule(root, "(0)");
-      if (why) return { skip: why };
-      if (plan.idempotency) return { skip: `the stamp ${plan.idempotency.stamp} must name one field of the argument record` };
-      plan.rootParam = true;
-      plan.params.push({ name: "arg0", node: root, optional: root.optional === true, path: "$args[0]" });
-    }
+    // a case tool reads its case's payload as a single argument is read (D-053)
+    const why = kase !== undefined ? planArgument(plan, kase[1], `(0).${kase[0]}`, `$args[0].${kase[0]}`) : planArgument(plan, args[0], "(0)", "$args[0]");
+    if (why) return why;
   }
   return plan;
 }
 
+/**
+ * The inputs of a single argument, or of a case's payload: a position `readAs` names is one input named by its tag, a
+ * record's fields are inputs of their own (the stamp and filled ones aside), null takes none, and any other position
+ * is one JSON input. `at` names the position in skip reasons, `path` in input issues.
+ * @returns {{ skip: string } | undefined}
+ */
+function planArgument(plan, root, at, path) {
+  const tag = readAs(root);
+  if (tag) {
+    const why = inputWithoutRule(root, at); // a text pattern the layer does not run
+    if (why) return { skip: why };
+    // the stamp is filled by the tool layer, so it must be a field beside the inputs, never the whole argument
+    if (plan.idempotency) return { skip: `the stamp ${plan.idempotency.stamp} must name one field of the argument record` };
+    plan.rootParam = true;
+    plan.params.push({ name: tag, node: root, optional: root.optional === true, path });
+  } else if (root.candid === "record") {
+    let stampId;
+    if (plan.idempotency) {
+      const ids = relpathIds(plan.idempotency.stamp);
+      if (ids === null || ids.length !== 1) return { skip: `the stamp ${plan.idempotency.stamp} must name one field of the argument record` };
+      stampId = ids[0];
+    }
+    for (const [fname, fnode] of Object.entries(root.fields ?? {})) {
+      // the canister selector of every tool (toolDefinitions, the tool layer) owns this input name
+      if (fname === "canister_id") return { skip: "an argument field named canister_id would collide with the canister selector input" };
+      const c = classifyField(fname, fnode, stampId);
+      if (c.skip) return c;
+      if (c.role === "stamp") plan.stampField = fname;
+      const optional = fnode.optional === true;
+      plan.fields.push({ name: fname, node: fnode, role: c.role, optional });
+      if (c.role === "param") plan.params.push({ name: fname, node: fnode, optional, path: `${path}.${fname}` });
+    }
+    if (plan.idempotency && !plan.fields.some((f) => f.role === "stamp")) return { skip: `the stamp field ${plan.idempotency.stamp} is not an argument field` };
+  } else if (root.candid === "null" || root.candid === "reserved") {
+    // one value only, so nothing to ask for: the tool takes no input and sends null
+    if (plan.idempotency) return { skip: `the stamp ${plan.idempotency.stamp} must name one field of the argument record` };
+    plan.rootNull = true;
+  } else {
+    // a variant or a vec (or a record a value tag does not cover) is one JSON input
+    const why = inputWithoutRule(root, at);
+    if (why) return { skip: why };
+    if (plan.idempotency) return { skip: `the stamp ${plan.idempotency.stamp} must name one field of the argument record` };
+    plan.rootParam = true;
+    plan.params.push({ name: "arg0", node: root, optional: root.optional === true, path });
+  }
+  return undefined;
+}
+
+/** What a tool calls, for messages: the method, or the method and the case it sends. */
+const toolOf = (p) => (p.case === undefined ? p.method : `${p.method}'s case ${p.case}`);
+
 /**
  * @param {object | object[]} resolved
  * @returns {{ plans: Map<string, any>, skipped: { method: string, reason: string }[] }}  plans keyed by tool name, sorted
@@ -244,15 +314,15 @@ export function buildToolPlans(resolved) {
   const skipped = [];
   const byTool = new Map();
   for (const [name, m] of resolvedMethods(resolved)) {
-    const p = planMethod(name, m);
-    if (p.skip) skipped.push({ method: name, reason: p.skip });
-    else byTool.set(p.name, [...(byTool.get(p.name) ?? []), p]);
+    const tools = planTools(name, m);
+    for (const reason of tools.skipped) skipped.push({ method: name, reason });
+    for (const p of tools.plans) byTool.set(p.name, [...(byTool.get(p.name) ?? []), p]);
   }
   // Two methods whose tools share a name (a query named prepare_x beside an update x), or one named like the commit
   // tool: neither is dropped silently, and neither is preferred, so all of them are skipped.
   for (const [tool, ps] of byTool) {
     if (tool === COMMIT_TOOL) for (const p of ps) skipped.push({ method: p.method, reason: `its tool name ${tool} is the commit tool's` });
-    else if (ps.length > 1) for (const p of ps) skipped.push({ method: p.method, reason: `its tool name ${tool} is also ${ps.filter((q) => q !== p).map((q) => q.method).join(", ")}'s` });
+    else if (ps.length > 1) for (const p of ps) skipped.push({ method: p.method, reason: `its tool name ${tool} is also ${ps.filter((q) => q !== p).map(toolOf).join(", ")}'s` });
     else plans.set(tool, ps[0]);
   }
   return { plans: new Map([...plans.entries()].sort(byName)), skipped };
@@ -397,12 +467,13 @@ function definitionOf(plan, canisters, refsList, sets) {
   const schema = inputSchema(plan, canisters, refsList, sets);
   if (plan.kind === "read") {
     const label = plan.describe?.label;
-    const what = plan.replicated ? `Read-only call of \`${plan.method}\`, sent as an update call so that the answer is certified; it changes nothing.` : `Read-only query of \`${plan.method}\`.`;
+    const call = `\`${plan.method}\`${plan.case === undefined ? "" : ` with the case \`${plan.case}\``}`;
+    const what = plan.replicated ? `Read-only call of ${call}, sent as an update call so that the answer is certified; it changes nothing.` : `Read-only query of ${call}.`;
     return {
       name: plan.name,
       description: `${label ? `${label}. ` : ""}${what} The answer gives each value formatted for people and raw (base units for amounts, the tagged unit for times).`,
       inputSchema: schema,
-      annotations: { destructiveHint: false, openWorldHint: true, readOnlyHint: true, title: label ?? plan.method },
+      annotations: { destructiveHint: false, openWorldHint: true, readOnlyHint: true, title: label ?? (plan.case === undefined ? plan.method : plan.title) },
     };
   }
   const e = plan.effect;
@@ -410,7 +481,7 @@ function definitionOf(plan, canisters, refsList, sets) {
   return {
     name: plan.name,
     description:
-      `Prepare the call "${plan.title}" (\`${plan.method}\`, effect: ${e.kind}${e.irreversible ? ", irreversible" : ""}). Nothing is sent yet. ` +
+      `Prepare the call "${plan.title}" (\`${plan.method}\`${plan.case === undefined ? "" : ` with the case \`${plan.case}\``}, effect: ${e.kind}${e.irreversible ? ", irreversible" : ""}). Nothing is sent yet. ` +
       "Inputs are in human units and are checked exactly (nothing is rounded). " +
       (plan.idempotency ? "" : "This call has no idempotency stamp, so the canister cannot tell a repeat from a new call: once an attempt's outcome is unknown, it is never sent again (commit answers reconcile). ") +
       (filled ? `The tool layer fills in: ${filled}. ` : "") +