@withpica/mcp-server 2.95.3 → 2.96.0

package/dist/tools/discovery.js

@@ -1,4 +1,11 @@
 // Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
+// `deriveAnnotations` is a value import back into ./index.js, which imports
+// this module — an ESM cycle. Safe because it is a hoisted function
+// declaration: it is initialised before either module body runs, and it is
+// only ever CALLED from inside a method here. Do not convert it to a const
+// arrow function on the other side.
+import { deriveAnnotations } from "./index.js";
+import { getAliasFor } from "./deprecations.js";
 import { getToolMetadata } from "./metadata.js";
 import { RECOVERY_HINTS } from "./recovery-hints.js";
 const SCHEMA_VERSION = "2026.1";
@@ -25,6 +32,133 @@ const SCOPES_NOT_GRANTABLE_TO_STANDARD_AGENT = new Set([
 ]);
 /** Max matched tools returned by a `pica_discover({ query })` call. */
 const DISCOVER_MATCH_LIMIT = 25;
+/**
+ * The fresh-org on-ramp, carried by BOTH pica_discover modes (ADR-294 L3).
+ * Static and org-blind by design so the response stays cacheable: the
+ * instruction is universal, not org data. One constant, because the ChatGPT
+ * app moved to query mode on 2026-08-10 and for sixteen days this line lived
+ * only on the full map — the client carrying 92% of tool calls never saw it
+ * (FIX_LOG 2026-08-26). Pinned in discovery.test.ts for a hit, a miss and
+ * the full map.
+ */
+export const FRESH_ORG_HINT = "on a fresh or empty org, run pica_dashboard_briefing first (through pica_execute where this surface routes calls that way). if the catalog is empty it names the fastest import: paste a spotify album or playlist link.";
+/**
+ * Words that describe the asker, not the entity. `pica_my_*` tools carry
+ * "my" as their DOMAIN segment, so before this filter "start my music
+ * catalogue and import my songs" led with pica_my_recent_questions,
+ * pica_my_reported_issues and pica_export_my_data — three tools about the
+ * caller, for a user who asked to import (prod agent_events, 2026-08-11).
+ * Determiners, pronouns, prepositions, conjunctions, auxiliaries and the
+ * LIGHT verbs (get / list / find / show / check / run / set …) that name no
+ * entity — "get the isrc" is about the ISRC. Eight tools carry a light verb
+ * as their first segment (pica_get_agent_activity, pica_find_duplicates,
+ * pica_run_work_cascade …); for them the entity is the next segment, and
+ * the verb still reaches them through the name text (+1). Domain verbs that
+ * discriminate inside a domain (delete, create, update, query, import …)
+ * stay. Before the light verbs were listed, "get the isrc from this
+ * spotify link" led with pica_get_agent_activity once the noise words that
+ * had been propping the import tool up were removed.
+ */
+export const STOP_WORDS = new Set([
+    "a",
+    "an",
+    "the",
+    "my",
+    "me",
+    "mine",
+    "our",
+    "ours",
+    "your",
+    "yours",
+    "his",
+    "her",
+    "hers",
+    "their",
+    "theirs",
+    "its",
+    "it",
+    "i",
+    "we",
+    "you",
+    "they",
+    "them",
+    "us",
+    "this",
+    "that",
+    "these",
+    "those",
+    "and",
+    "or",
+    "of",
+    "to",
+    "for",
+    "in",
+    "on",
+    "at",
+    "by",
+    "with",
+    "from",
+    "into",
+    "across",
+    "about",
+    "as",
+    "per",
+    "is",
+    "are",
+    "am",
+    "be",
+    "was",
+    "were",
+    "do",
+    "does",
+    "did",
+    "can",
+    "could",
+    "would",
+    "should",
+    "will",
+    "shall",
+    "please",
+    "want",
+    "need",
+    "just",
+    "also",
+    "some",
+    "any",
+    "all",
+    "get",
+    "list",
+    "find",
+    "show",
+    "see",
+    "view",
+    "check",
+    "run",
+    "make",
+    "use",
+    "look",
+    "set",
+]);
+/**
+ * Rows reserved at the tail of a capped shortlist for tools the caller
+ * cannot run here — a floor, not a ceiling: flagged rows also fill whatever
+ * the visible rows leave free, so a narrowly-scoped connection sees as many
+ * rows as an open one. Visible-first sorting alone let them fall off the
+ * end of a 25-row list, so an agent could conclude a capability was missing
+ * rather than gated (the Ridwayne session: five finance tools, zero
+ * callable). Pinned by discovery-ranking.test.ts.
+ */
+const FLAGGED_MATCH_ROWS = 5;
+/**
+ * Flag text for a tool the caller cannot run on this connection — surfaced
+ * as `surface_note` beside `callable_on_this_surface: false` in the
+ * shortlist row and in tool_details, so an agent learns the wall at
+ * discovery time. Its own key: a scope or destructive-tier `callable_note`
+ * carries the specific remediation (admin elevation, confirmation token)
+ * and must survive alongside it. Factual; names the two causes the
+ * predicate folds together (ADR-248: audiences ∋ surface AND scope held).
+ */
+const NOT_CALLABLE_ON_SURFACE_NOTE = "not callable on this connection — it is listed on a different surface (stdio / lobby / web) or needs a scope this connection does not hold. prefer a tool without this note; the user can reach it from withpica.com.";
 /**
  * Hand-maintained category taxonomy for the catalog server.
  * Grouped by natural entity/capability prefix.
@@ -507,8 +641,17 @@ export const CATEGORIES = {
         depends_on: [],
     },
     subscription: {
-        description: "view your billing state, manage your subscription, and pick a tier",
-        tools: ["pica_subscription_status", "pica_subscription_manage"],
+        // Reworded 2026-08-26 (WS-B). "pick a tier" described a capacity ladder
+        // ADR-276 superseded, and neither "what does pica cost" nor "how do I pay"
+        // appeared anywhere in this bucket — so the two questions a paying user
+        // actually asks routed to no category at all.
+        description: "what does pica cost, how do I pay, and what is pica holding — read " +
+            "your billing state and get a pay link",
+        tools: [
+            "pica_subscription_status",
+            "pica_billing_pay",
+            "pica_subscription_manage",
+        ],
         depends_on: [],
     },
     profile: {
@@ -811,6 +954,11 @@ export const CATEGORIES = {
         ],
         depends_on: [],
     },
+    shows: {
+        description: "log live shows and tour credits, and confirm setlist matches against your catalogue",
+        tools: ["pica_log_show", "pica_shows_query", "pica_setlist_match"],
+        depends_on: [],
+    },
 };
 /**
  * Operational metadata defaults for pica_tool_details responses.
@@ -827,49 +975,167 @@ function getOperationalMeta(toolName) {
     }
     return {};
 }
+/**
+ * Naive English singular of a search token.
+ *
+ * A wrong stem is NOT free. An `-es` strip turns `notes` into `not` — and
+ * `pica_notes_*` are in CATEGORIES with `notes` as their domain segment, so
+ * every query containing the ordinary English word "not" ("works not
+ * registered") scored a +6 domain hit on the notes family. The same rule
+ * stems `releases`→`releas`, which the query word `release` can never match,
+ * defeating the feature in the other direction. Both shipped on 2026-08-24
+ * and are pinned by the singularise unit tests.
+ *
+ * The rules, in order:
+ *   - `ies` → `y`   (categories → category)
+ *   - `s`   → ""    unless the token ends `ss`/`us`/`is`, none of which is an
+ *                   English plural (address, status, analysis stay put)
+ *
+ * There is deliberately NO `-es` rule. Every domain segment in CATEGORIES is a
+ * plain `-s` plural (works, notes, releases, documents, statements, credits,
+ * shows…), so `-es` would only ever misfire: it cannot tell `releas+es` from
+ * `release+s`, and the wrong branch (`releas`) is one a query word can never
+ * reach. `boxes` therefore stems to `boxe` rather than `box` — harmless,
+ * because both sides of every comparison run through this same function.
+ *
+ * Exported for direct unit assertion in
+ * `src/__tests__/tools/discovery-ranking.test.ts` — the stem is load-bearing
+ * enough that it needs testing without a whole registry behind it.
+ */
+export function singularise(token) {
+    if (token.length > 3 && token.endsWith("ies"))
+        return `${token.slice(0, -3)}y`;
+    if (token.length > 2 && token.endsWith("s") && !/(?:ss|us|is)$/.test(token))
+        return token.slice(0, -1);
+    return token;
+}
+/** The token plus its stem, deduped — matching on either is a hit. */
+function tokenVariants(token) {
+    const stem = singularise(token);
+    return stem === token ? [token] : [token, stem];
+}
+/**
+ * Levenshtein distance, two rolling rows. Tool names are short (< 60 chars)
+ * and the registry is a few hundred entries, so the O(n·m) form is well
+ * inside budget for a once-per-failed-dispatch call.
+ */
+function editDistance(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    let curr = new Array(b.length + 1);
+    for (let i = 1; i <= a.length; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const substitution = prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1);
+            curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, substitution);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[b.length];
+}
+/** Length of the common leading substring — a typo late in a name keeps it. */
+function sharedPrefixLength(a, b) {
+    const max = Math.min(a.length, b.length);
+    let i = 0;
+    while (i < max && a[i] === b[i])
+        i++;
+    return i;
+}
 export class DiscoveryTools {
     executeToolFn;
     getToolDef;
     listToolNames;
+    isToolVisible;
     constructor(executeToolFn, getToolDef, 
     /**
-     * Registered tool names, for UNKNOWN_TOOL near-match suggestions.
+     * Registered tool names, for TOOL_NOT_FOUND near-match suggestions.
      * Optional so existing constructions keep compiling; without it the
      * unknown-tool envelope simply carries no suggestions.
      */
-    listToolNames) {
+    listToolNames, 
+    /**
+     * Whether the CURRENT caller can run a tool on this connection. On HTTP
+     * the route installs its `allowedToolNames` judgement (ADR-248:
+     * audiences ∋ http AND scope held) via `ToolRegistry.setToolVisibility`;
+     * the registry's default is audience-only. Absent = every registered
+     * tool is treated as callable (legacy constructions, unit harnesses).
+     * Consulted by the shortlist (rank visible first, flag the rest) and by
+     * tool_details (flag) — never by pica_execute, which the dispatcher
+     * already gates.
+     */
+    isToolVisible) {
         this.executeToolFn = executeToolFn;
         this.getToolDef = getToolDef;
         this.listToolNames = listToolNames;
+        this.isToolVisible = isToolVisible;
+    }
+    isVisible(toolName) {
+        return this.isToolVisible ? this.isToolVisible(toolName) : true;
+    }
+    /** Shortlist / detail keys added only when the tool is NOT callable here. */
+    surfaceFlags(toolName) {
+        return this.isVisible(toolName)
+            ? {}
+            : {
+                callable_on_this_surface: false,
+                surface_note: NOT_CALLABLE_ON_SURFACE_NOTE,
+            };
     }
     /**
-     * Rank registered tool names by shared `_`-token overlap with a
-     * hallucinated name. ChatGPT callers routinely invent tool names
+     * Rank registered tool names against a hallucinated or mistyped one.
+     *
+     * ChatGPT callers routinely invent tool names
      * (`pica_releases_attach_track_by_identifier`, `pica_credit_add`, …) and
      * retry variations instead of consulting pica_tool_details — 26 opaque
      * dispatcher errors in 14 days. Naming the closest real tools breaks that
      * guess-loop.
+     *
+     * Token overlap alone was not enough: `pica_works_inspekt` overlaps every
+     * `pica_works_*` tool on exactly one token, so the top-3 slice fell back to
+     * registration order and could drop the obvious answer. Edit distance
+     * breaks that tie — pinned by "ranks the nearest EDIT-distance name first"
+     * in `src/__tests__/tools/discovery.test.ts`.
+     *
+     * Deprecated aliases are excluded. The candidate pool is
+     * `[...this.tools.keys()]` (index.ts, where DiscoveryTools is constructed),
+     * which includes the hidden alias clones `expandAliases` registers — so a
+     * typo one letter off an alias (`pica_releases_lists`) was answered with the
+     * alias (`pica_releases_list`, removal_target 2.96.0) ranked above its own
+     * canonical. Steering a confused caller onto a name we are trying to retire
+     * is the opposite of what this envelope is for.
      */
     suggestToolNames(input) {
-        const candidates = this.listToolNames?.() ?? [];
+        const candidates = (this.listToolNames?.() ?? []).filter((name) => getAliasFor(name) === undefined);
         const tokens = new Set(input
             .replace(/^pica_/, "")
             .split("_")
             .filter(Boolean));
         if (tokens.size === 0 || candidates.length === 0)
             return [];
-        return candidates
+        return (candidates
             .map((name) => ({
             name,
             overlap: name
                 .replace(/^pica_/, "")
                 .split("_")
                 .filter((t) => tokens.has(t)).length,
+            distance: editDistance(name, input),
+            prefix: sharedPrefixLength(name, input),
         }))
-            .filter((c) => c.overlap > 0)
-            .sort((a, b) => b.overlap - a.overlap)
+            // A near-miss on spelling shares no whole token, so distance and prefix
+            // have to be able to admit a candidate on their own.
+            .filter((c) => c.overlap > 0 || c.distance <= 3 || c.prefix >= 8)
+            .sort((a, b) => b.overlap - a.overlap ||
+            a.distance - b.distance ||
+            b.prefix - a.prefix ||
+            a.name.localeCompare(b.name))
             .slice(0, 3)
-            .map((c) => c.name);
+            .map((c) => c.name));
     }
     getTools() {
         return [
@@ -911,6 +1177,10 @@ export class DiscoveryTools {
             },
             executor: async (args) => {
                 const cacheUntil = new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString();
+                // Query-mode rows carry per-connection flags since 2026-08-26 (an
+                // org's finance toggle changes them), so a shortlist is cacheable for
+                // an hour, not the day the org-blind full map gets.
+                const queryCacheUntil = new Date(Date.now() + 60 * 60 * 1000).toISOString();
                 const rawQuery = typeof args?.query === "string" ? args.query : "";
                 const query = rawQuery.trim();
                 // Filtered mode — a job-search shortlist. Additive: when no query is
@@ -923,18 +1193,20 @@ export class DiscoveryTools {
                     ];
                     const payload = {
                         schema_version: SCHEMA_VERSION,
-                        cache_until: cacheUntil,
+                        cache_until: queryCacheUntil,
                         query,
                         match_count: matches.length,
                         matches: matches.map(({ tool, category, description }) => ({
                             tool,
                             category,
                             description,
+                            ...this.surfaceFlags(tool),
                         })),
                         matched_categories: matchedCategories,
-                        hint: matches.length > 0
+                        hint: (matches.length > 0
                             ? `${matches.length} tool(s) match "${query}". Call pica_tool_details({ tool: "<name>" }) for a full schema. Call pica_discover with no query to browse all ${Object.keys(CATEGORIES).length} categories.`
-                            : `no tools matched "${query}". Try different words, or call pica_discover with no query to browse all ${Object.keys(CATEGORIES).length} categories before concluding a capability is missing.`,
+                            : `no tools matched "${query}". Try different words, or call pica_discover with no query to browse all ${Object.keys(CATEGORIES).length} categories before concluding a capability is missing.`) +
+                            ` ${FRESH_ORG_HINT}`,
                     };
                     return {
                         content: [
@@ -962,7 +1234,7 @@ export class DiscoveryTools {
                     cache_until: cacheUntil,
                     // Static, org-blind by design (the response is cacheable): the
                     // fresh-org on-ramp is a universal instruction, not org data.
-                    hint: "on a fresh or empty org, run pica_dashboard_briefing first (through pica_execute where this surface routes calls that way). if the catalog is empty it names the fastest import: paste a spotify album or playlist link.",
+                    hint: FRESH_ORG_HINT,
                     categories,
                 };
                 return {
@@ -979,18 +1251,32 @@ export class DiscoveryTools {
     }
     /**
      * Rank tools against a plain-language job description. Case-insensitive
-     * token scoring (no external deps): each query token scores +3 when it
-     * exactly matches an underscore-separated token of the tool name and +1
-     * when it appears anywhere in the tool's searchable text (name +
-     * description/triggers + its category name + category description). Tools
-     * are deduped across cross-listed categories (keeping the highest-scoring
-     * category), sorted by score then name, and capped.
+     * token scoring (no external deps):
+     *
+     *   +6  the token matches the tool's DOMAIN segment (the `_`-separated
+     *       segment after `pica_` — `recordings` in `pica_recordings_delete`)
+     *   +3  the token matches any other `_`-separated segment of the name
+     *   +1  the token appears anywhere in the searchable text (name +
+     *       description/triggers + category name + category description)
+     *
+     * Both sides are compared through {@link singularise}, so "recording" and
+     * "recordings" are one term. Tools are deduped across cross-listed
+     * categories (keeping the highest-scoring category), sorted by score then
+     * name, and capped.
+     *
+     * The domain weight exists because the VERB is shared by dozens of tools
+     * and the ENTITY is what the user actually named: before it, "delete a
+     * recording" led with `pica_agreement_types_delete` and "read a document"
+     * put `pica_notifications_mark_read` above every documents tool. Both are
+     * pinned in `src/__tests__/tools/discovery-ranking.test.ts`, alongside the
+     * flagship isrc-from-spotify pin the weighting must not disturb.
      */
     matchDiscovery(query) {
         const tokens = query
             .toLowerCase()
             .split(/[^a-z0-9]+/)
-            .filter((t) => t.length >= 2);
+            .filter((t) => t.length >= 2 && !STOP_WORDS.has(t))
+            .map((t) => ({ raw: t, variants: tokenVariants(t) }));
         if (tokens.length === 0)
             return [];
         // Best score per tool, plus the category that produced it.
@@ -1001,16 +1287,22 @@ export class DiscoveryTools {
                 const def = this.getToolDef(toolName)?.definition;
                 const metadata = getToolMetadata(toolName);
                 const toolDesc = def?.description ?? metadata?.display_name ?? "";
-                const nameTokens = new Set(toolName
+                const segments = toolName
                     .replace(/^pica_/, "")
                     .split("_")
-                    .filter(Boolean));
+                    .filter(Boolean);
+                // The entity the tool acts on. `pica_upload` has no verb segment, so
+                // its only segment is both domain and verb — that is correct here.
+                const domainVariants = new Set(segments.length > 0 ? tokenVariants(segments[0]) : []);
+                const nameVariants = new Set(segments.flatMap(tokenVariants));
                 const haystack = `${toolName.replace(/_/g, " ")} ${toolDesc} ${catText}`.toLowerCase();
                 let score = 0;
-                for (const token of tokens) {
-                    if (nameTokens.has(token))
+                for (const { variants } of tokens) {
+                    if (variants.some((v) => domainVariants.has(v)))
+                        score += 6;
+                    else if (variants.some((v) => nameVariants.has(v)))
                         score += 3;
-                    if (haystack.includes(token))
+                    if (variants.some((v) => haystack.includes(v)))
                         score += 1;
                 }
                 if (score === 0)
@@ -1022,13 +1314,24 @@ export class DiscoveryTools {
                         category: key,
                         description: this.oneLineDescription(toolName),
                         score,
+                        visible: this.isVisible(toolName),
                     });
                 }
             }
         }
-        return [...best.values()]
-            .sort((a, b) => b.score - a.score || a.tool.localeCompare(b.tool))
-            .slice(0, DISCOVER_MATCH_LIMIT);
+        // Callable-here first, then score, then name. A tool the caller cannot
+        // run keeps a row (it exists — the agent should not conclude the
+        // capability is missing) but never leads. The cap holds at least
+        // FLAGGED_MATCH_ROWS tail rows for those, and lets them fill any room
+        // the visible rows leave, so the total never shrinks because of a scope.
+        const ranked = [...best.values()].sort((a, b) => b.score - a.score || a.tool.localeCompare(b.tool));
+        const visible = ranked.filter((m) => m.visible);
+        const flagged = ranked.filter((m) => !m.visible);
+        const flaggedShown = Math.min(flagged.length, Math.max(FLAGGED_MATCH_ROWS, DISCOVER_MATCH_LIMIT - visible.length));
+        return [
+            ...visible.slice(0, DISCOVER_MATCH_LIMIT - flaggedShown),
+            ...flagged.slice(0, flaggedShown),
+        ];
     }
     /**
      * A single-line description for a match row: the first sentence of the
@@ -1161,6 +1464,10 @@ export class DiscoveryTools {
         // Collect all recovery hints for this tool (all error codes)
         const hints = RECOVERY_HINTS[toolName] ?? [];
         const definition = registered?.definition ?? null;
+        // A deprecated alias is registered as a clone of its canonical, so the
+        // schema/description below ARE the canonical's — the agent gets a working
+        // tool plus the name it should migrate to, not a bare refusal.
+        const deprecation = getAliasFor(toolName);
         // Gate visibility (audit P1 #6): surface the authority tier + required
         // scope so an agent knows BEFORE calling whether it holds the grant, and
         // an explicit note when the scope is unreachable for a standard agent
@@ -1188,14 +1495,48 @@ export class DiscoveryTools {
             // concluded "I can see the tool but can't execute it" and given up
             // (observed on ChatGPT, 2026-07-08). Spell out the execution path so
             // the next step is unavoidable.
-            invoke: `if ${toolName} is not in your callable function list, run it via the pica_execute tool: ` +
-                `{"tool": "${toolName}", "args": { ...arguments per the schema below }}. ` +
-                "Never tell the user the tool is unavailable — pica_execute executes every tool returned here.",
+            // When the caller cannot run the tool here, the line above would be
+            // false in the worst direction — pica_execute refuses it (the route's
+            // allowedToolNames gate) — so the invoke text says so instead.
+            invoke: this.isVisible(toolName)
+                ? `if ${toolName} is not in your callable function list, run it via the pica_execute tool: ` +
+                    `{"tool": "${toolName}", "args": { ...arguments per the schema below }}. ` +
+                    "Never tell the user the tool is unavailable — pica_execute executes every tool returned here."
+                : `pica_execute will refuse ${toolName} on this connection (see surface_note). ` +
+                    "Do not call it here; tell the user plainly what it needs and offer a tool without this flag.",
             schema: definition?.inputSchema ?? null,
-            annotations: definition?.annotations ?? null,
+            ...(definition?.outputSchema
+                ? { outputSchema: definition.outputSchema }
+                : {}),
+            // Derived, never the raw declaration: most tools declare no
+            // `annotations` at all, so reading the declaration answered `null` for
+            // the large majority of registered tools while listTools() answered real
+            // hints for the same tool (measured 2026-08-24). deriveAnnotations() is
+            // the one derivation both surfaces read — see index.ts and
+            // src/__tests__/tools/tool-details-contract.test.ts.
+            annotations: definition ? deriveAnnotations(definition) : null,
+            // Every category key this tool is listed under. Cross-listed tools
+            // (ADR-226 Decision 12) appear in more than one, and an agent that
+            // arrived via one category otherwise cannot see the others.
+            discovery_categories: Object.entries(CATEGORIES)
+                .filter(([, cat]) => cat.tools.includes(toolName))
+                .map(([key]) => key),
+            ...(deprecation
+                ? {
+                    deprecated: {
+                        use: deprecation.canonical,
+                        removal_target: deprecation.removal_target,
+                    },
+                }
+                : {}),
             tier,
             required_scope: requiredScope,
+            // A scope / destructive-tier note stays whatever the surface says:
+            // its remediation (admin elevation, confirmation token) is the part an
+            // agent can act on. The surface flag rides beside it under its own
+            // key (`surface_note`), never in its place.
             ...(callableNote ? { callable_note: callableNote } : {}),
+            ...this.surfaceFlags(toolName),
             metadata: metadata
                 ? {
                     category: metadata.category,
@@ -1264,7 +1605,13 @@ export class DiscoveryTools {
                     readOnlyHint: false,
                     destructiveHint: false,
                     idempotentHint: false,
-                    openWorldHint: false,
+                    // TRUE, matching the `annotationOverrides.openWorldHint` above.
+                    // This read `false` until 2026-08-24 while the override next to it
+                    // said `true` — the override wins, so the declaration was never
+                    // published and only misled the next reader of this file. The
+                    // dispatcher wraps every tool, including the ones that email an
+                    // external recipient, so `true` is the honest value.
+                    openWorldHint: true,
                 },
             },
             executor: async (args, ctx) => {
@@ -1337,17 +1684,41 @@ export class DiscoveryTools {
                 // hallucinated variations instead of consulting the catalog.
                 // structuredContent mirrors the envelope so telemetry and
                 // structured-content-aware clients get the code without parsing text.
+                //
+                // The code is TOOL_NOT_FOUND, matching pica_tool_details' answer for
+                // the same question and the ADR-149 Phase 5bcd design. It read
+                // UNKNOWN_TOOL from 2026-07-03 until 2026-08-24; `suggestions` is kept
+                // beside the new `did_you_mean` for callers written against that
+                // shape. Both are asserted in
+                // `src/__tests__/tools/discovery.test.ts`.
+                //
+                // `did_you_mean` is ALWAYS present, empty array included: a key that
+                // only sometimes exists forces every caller to branch on `undefined`
+                // before it can branch on "no suggestions".
+                //
+                // `retry_safe` and `retry_eligible` carry the same fact under two
+                // names, deliberately. `retry_eligible` is the ADR-180 envelope field
+                // that the five sibling envelopes in this file all emit, so dropping
+                // it here alone would make one dispatcher error shaped unlike the
+                // rest; `retry_safe` is the name the same fact wears in
+                // `pica_tool_details.metadata.retry_safe`, which is where an agent
+                // reads it everywhere else. Unifying the file on one key is a
+                // separate change — do it for all six envelopes or none.
                 if (!this.getToolDef(toolName)) {
                     const suggestions = this.suggestToolNames(toolName);
                     const envelope = {
-                        error_code: "UNKNOWN_TOOL",
+                        error: "TOOL_NOT_FOUND",
+                        error_code: "TOOL_NOT_FOUND",
                         tool: toolName,
                         message: `${toolName} is not a registered tool.` +
                             (suggestions.length > 0
                                 ? ` Closest real tools: ${suggestions.join(", ")}.`
                                 : "") +
                             " Call pica_tool_details on the intended tool for its exact name and schema, or pica_discover to browse categories — do not guess tool names or argument shapes.",
-                        ...(suggestions.length > 0 ? { suggestions } : {}),
+                        did_you_mean: suggestions,
+                        suggestions,
+                        next_tool: "pica_discover",
+                        retry_safe: false,
                         retry_eligible: false,
                     };
                     return {
@@ -1355,9 +1726,14 @@ export class DiscoveryTools {
                             { type: "text", text: JSON.stringify(envelope, null, 2) },
                         ],
                         structuredContent: {
+                            error: envelope.error,
                             error_code: envelope.error_code,
                             error_message: envelope.message,
-                            ...(suggestions.length > 0 ? { suggestions } : {}),
+                            tool: toolName,
+                            did_you_mean: suggestions,
+                            suggestions,
+                            next_tool: "pica_discover",
+                            retry_safe: false,
                         },
                         isError: true,
                     };