@withpica/mcp-server 2.98.0 → 2.99.0

package/dist/tools/deprecations.js

@@ -1,6 +1,18 @@
 // Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 /**
- * The one alias registry. Populated per-consolidation in later phases.
+ * The one alias registry. Populated per-consolidation; EMPTY as of
+ * mcp-server 2.99.0.
+ *
+ * REMOVAL (mcp-server 2.99.0, founder decision 2026-09-29): the last eleven
+ * aliases were removed — their entries here, their TOOL_METADATA mirrors,
+ * and any standalone ToolDefinitions that still sat beside the canonical
+ * tools. Prod `agent_events` over the 60 days to 2026-09-29: 4 calls in all
+ * (pica_recording_credits_bulk_update 2, last 08-17; pica_releases_get 1,
+ * 08-01; pica_royalties_summary 1, 09-14; the other eight zero). Calling any
+ * of them now gets TOOL_NOT_FOUND whose message names its replacement; the
+ * replacement also leads `did_you_mean` when the caller can call it. The
+ * name → replacement mapping is RETIRED_TOOLS below — the one copy.
+ * The dated notes below are the history of how that deadline moved.
  *
  * REMOVAL SWEEP (mcp-server 2.93.0, 2026-07-12): the first batch of WS5
  * deprecated names were traffic-gated against prod `agent_events` (30-day
@@ -9,10 +21,11 @@
  * ToolDefinition, TOOL_METADATA, cost-model, and required-schemas companion
  * rows all went with them: `pica_projects_get`, `pica_notes_get`,
  * `pica_sessions_list`, `pica_sessions_get`, `pica_statements_get`,
- * `pica_share_links_list`. The ten aliases below still carry real live
- * traffic, so they STAY callable — their `removal_target` is consciously
- * extended (the "expire loudly" lint would otherwise block this publish at
- * 2.93.0). Re-run the traffic gate before that release.
+ * `pica_share_links_list`. The ten aliases that then remained still carried
+ * real live traffic, so they STAYED callable — their `removal_target` was
+ * consciously extended (the "expire loudly" lint would otherwise have blocked
+ * the 2.93.0 publish), with the traffic check to be re-run before the new
+ * target. They were finally removed in 2.99.0 (above).
  *
  * ⚠️ `removal_target` HERE IS DOCUMENTATION, NOT THE GATE (noted 2026-08-13).
  * `checkDeprecationExpiry` in `scripts/lint-mcp-tools.ts` reads the value from
@@ -40,107 +53,94 @@
  * 2.98.0 shipped the ADR-321 Phase 2 release without removals).
  */
 export const TOOL_ALIASES = [
-    // Retired 2026-09-25 (ADR-321 Phase 0, founder decision): the old gap list
-    // ran its own judgement — PRS/PPL/MCPS hard-coded, a missing row read as
-    // "not registered with PRS", first 1,000 works only. Its society-income
-    // questions now go to pica_royalties_blockers, the one judgement the song
-    // page and /inspect/money use. Unmatched payments stay with
-    // pica_royalties_unmatched. Dropped with it: "released but no Spotify link"
-    // and "no tunecode" (not society-income blockers). Traffic: 2 calls from 2
-    // orgs in the 90 days to 2026-09-25 (agent_events). gap_type/priority have
-    // no equivalent and are dropped; work_id and limit carry over.
-    {
-        deprecated: "pica_royalties_summary",
-        canonical: "pica_royalties_blockers",
-        removal_target: "2.99.0",
-        adaptArgs: (a) => ({ work_id: a.work_id, limit: a.limit }),
-    },
-    // Tier 1 (MCP tool-surface consolidation): pica_releases_attach_track is
-    // now a superset (identifier_type+value / items[] / single-track) — see
-    // ReleasesTools.attachTrack. Both siblings below are strict subsets of it.
-    // FLAGGED (kept): 160 (_by_identifier) + 6 (_bulk) calls/30d in prod.
-    {
-        deprecated: "pica_releases_attach_track_by_identifier",
-        canonical: "pica_releases_attach_track",
-        removal_target: "2.99.0",
+// Empty since mcp-server 2.99.0 — every alias has been removed (history in
+// the comment above). Add a new entry here, with its TOOL_METADATA mirror,
+// for the next deprecation.
+];
+export const RETIRED_TOOLS = {
+    // mcp-server 2.99.0 (founder, 2026-09-29) — the last eleven aliases.
+    pica_releases_list: {
+        replacement: "pica_releases_query",
+        removed_in: "2.99.0",
     },
-    {
-        deprecated: "pica_releases_bulk_attach_tracks",
-        canonical: "pica_releases_attach_track",
-        removal_target: "2.99.0",
-        adaptArgs: (a) => ({
-            release_id: a.release_id,
-            items: a.tracks,
-            dry_run: a.dry_run,
-        }),
+    pica_releases_get: {
+        replacement: "pica_releases_inspect",
+        removed_in: "2.99.0",
     },
-    // Tier 1 (MCP tool-surface consolidation): releases aligned to the
-    // ADR-149 query/inspect pattern. Both identity — args map 1:1.
-    // FLAGGED (kept): _list 63 + _get 17 calls/30d in prod.
-    {
-        deprecated: "pica_releases_list",
-        canonical: "pica_releases_query",
-        removal_target: "2.99.0",
+    pica_releases_bulk_attach_tracks: {
+        replacement: "pica_releases_attach_track",
+        removed_in: "2.99.0",
+        argument_change: "pass the tracks as items[] (the old tracks field)",
     },
-    {
-        deprecated: "pica_releases_get",
-        canonical: "pica_releases_inspect",
-        removal_target: "2.99.0",
+    pica_releases_attach_track_by_identifier: {
+        replacement: "pica_releases_attach_track",
+        removed_in: "2.99.0",
+        argument_change: "pass identifier_type + value (with track_number) on pica_releases_attach_track",
     },
-    // Tier 2 (MCP tool-surface consolidation): projects aligned to the
-    // ADR-149 query/inspect pattern. Identity — args map 1:1. pica_projects_get
-    // was REMOVED in the 2.93.0 sweep (0 calls/30d); _list stays (3 calls/30d).
-    {
-        deprecated: "pica_projects_list",
-        canonical: "pica_projects_query",
-        removal_target: "2.99.0",
+    pica_projects_list: {
+        replacement: "pica_projects_query",
+        removed_in: "2.99.0",
     },
-    // Tier 2 (MCP tool-surface consolidation): notes aligned to the
-    // ADR-149 query/inspect pattern. Identity — args map 1:1. pica_notes_get
-    // was REMOVED in the 2.93.0 sweep (0 calls/30d); _list stays (4 calls/30d).
-    {
-        deprecated: "pica_notes_list",
-        canonical: "pica_notes_query",
-        removal_target: "2.99.0",
+    pica_notes_list: { replacement: "pica_notes_query", removed_in: "2.99.0" },
+    pica_documents_list: {
+        replacement: "pica_documents_query",
+        removed_in: "2.99.0",
     },
-    // Tier 2 (MCP tool-surface consolidation): documents aligned to the
-    // ADR-149 query/inspect pattern. Both identity — args map 1:1.
-    // FLAGGED (kept): _list 5 + _read 10 calls/30d in prod.
-    {
-        deprecated: "pica_documents_list",
-        canonical: "pica_documents_query",
-        removal_target: "2.99.0",
+    pica_documents_read: {
+        replacement: "pica_documents_inspect",
+        removed_in: "2.99.0",
     },
-    {
-        deprecated: "pica_documents_read",
-        canonical: "pica_documents_inspect",
-        removal_target: "2.99.0",
+    pica_statements_list: {
+        replacement: "pica_statements_query",
+        removed_in: "2.99.0",
     },
-    // Tier 2 (MCP tool-surface consolidation): statements aligned to the
-    // ADR-149 query/inspect pattern. Identity — args map 1:1 (the canonical
-    // inspect tool accepts the legacy batch_id field too). pica_statements_get
-    // was REMOVED in the 2.93.0 sweep (0 calls/30d); _list stays (2 calls/30d).
-    {
-        deprecated: "pica_statements_list",
-        canonical: "pica_statements_query",
-        removal_target: "2.99.0",
+    pica_royalties_summary: {
+        replacement: "pica_royalties_blockers",
+        removed_in: "2.99.0",
+        argument_change: "work_id and limit carry over; gap_type and priority have no equivalent",
     },
-    // Task A1 (MCP tool-surface consolidation): pica_recording_credits_update
-    // is now a superset — dispatches to the bulk path when args.credits is an
-    // array (see CreditsTools.updateRecordingCredits). Identity — the bulk arg
-    // shape {release_id, recording_ids, credits, dry_run} is already accepted
-    // by the superset's inputSchema, so no adaptArgs. FLAGGED (kept): 22
-    // calls/30d in prod. VARIANT-MERGE ALIAS: when finally removed the
-    // standalone pica_recording_credits_bulk_update ToolDefinition +
-    // bulkUpdateRecordingCredits executor in credits.ts must ALSO be deleted,
-    // or the tool resurrects (same trap as the attach bulk/by_identifier
-    // aliases above).
-    {
-        deprecated: "pica_recording_credits_bulk_update",
-        canonical: "pica_recording_credits_update",
-        removal_target: "2.99.0",
+    pica_recording_credits_bulk_update: {
+        replacement: "pica_recording_credits_update",
+        removed_in: "2.99.0",
+        argument_change: "pass the credit set as a credits[] array (with release_id or recording_ids)",
     },
-];
+};
+/** The retired-tool record for a name, if it is one. */
+export function getRetiredTool(name) {
+    return Object.prototype.hasOwnProperty.call(RETIRED_TOOLS, name)
+        ? RETIRED_TOOLS[name]
+        : undefined;
+}
+/**
+ * Adjust a not-found answer for a retired name. Pure.
+ *
+ * `similar` is the similarity-ranked suggestion list the caller already built
+ * (at most three names). For a retired name whose replacement `canCall`
+ * accepts, the replacement goes FIRST and the list stays at most three long;
+ * `note` is the sentence to lead the message with. A replacement the caller
+ * cannot call is named in `note` (the mapping is published in the package
+ * CHANGELOG) but never added to the suggestions. This function does not
+ * filter `similar` itself: each caller builds it from names the caller can
+ * call (`canSuggest` in discovery.ts; the `allowedToolNames` pool in
+ * app/api/mcp/tool-not-found.ts). For any other name the list comes back
+ * unchanged and `note` is null.
+ */
+export function retiredToolAnswer(name, similar, canCall) {
+    const retired = getRetiredTool(name);
+    if (!retired)
+        return { suggestions: [...similar], note: null };
+    const suggestions = canCall(retired.replacement)
+        ? [
+            retired.replacement,
+            ...similar.filter((n) => n !== retired.replacement),
+        ].slice(0, 3)
+        : [...similar];
+    const note = `${name} was retired in mcp-server ${retired.removed_in}; use ` +
+        `${retired.replacement} instead` +
+        (retired.argument_change ? ` — ${retired.argument_change}` : "") +
+        ".";
+    return { suggestions, note };
+}
 /** True when a tool's metadata marks it deprecated (aliased). Pure. */
 export function isDeprecatedMeta(meta) {
     return meta?.deprecated === true;

package/dist/tools/deprecations.js.map

@@ -1 +1 @@
-{"version":3,"file":"deprecations.js","sourceRoot":"","sources":["../../src/tools/deprecations.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"deprecations.js","sourceRoot":"","sources":["../../src/tools/deprecations.ts"],"names":[],"mappings":"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"}

package/dist/tools/discovery.d.ts

@@ -148,11 +148,37 @@ export declare class DiscoveryTools {
      * `[...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
+     * alias (`pica_releases_list`, since removed in 2.99.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.
+     * is the opposite of what this envelope is for. TOOL_ALIASES is empty as of
+     * 2.99.0, so the filter currently removes nothing; it stays for the next
+     * deprecation.
+     *
+     * Tools the caller cannot run here are excluded too ({@link canSuggest}).
+     * The pool is every REGISTERED name, and on HTTP the route narrows what a
+     * caller may run through `setToolVisibility` (audience + scope). Without
+     * this filter a caller lacking finance scope was offered hidden
+     * statements/royalties tools for a statements typo — the same names the
+     * hosted route's suggester (`app/api/mcp/tool-not-found.ts`) never offers,
+     * because its pool is the caller's callable set.
      */
     private suggestToolNames;
+    /** Registered AND callable by this caller on this surface. */
+    private canSuggest;
+    /**
+     * The suggestions and leading note for a name that is not registered. A
+     * retired name (RETIRED_TOOLS in deprecations.ts) gets its replacement
+     * first (when callable) and a sentence saying what replaced it; any other
+     * name gets the similarity ranking unchanged.
+     *
+     * What is shared with the hosted route (`app/api/mcp/tool-not-found.ts`)
+     * is `retiredToolAnswer`, so both name the same replacement — pinned on
+     * this side by `src/__tests__/tools/tool-details-contract.test.ts` and on
+     * that side by `app/api/mcp/__tests__/tool-not-found.test.ts`. The
+     * similarity lists are NOT shared: each side ranks with its own suggester
+     * over its own pool, so for non-retired names the two may differ.
+     */
+    private notFoundAnswer;
     getTools(): Array<{
         definition: ToolDefinition;
         executor: ToolExecutor;

package/dist/tools/discovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/tools/discovery.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACZ,UAAU,EACX,MAAM,YAAY,CAAC;AAwCpB;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,6NACiM,CAAC;AAE7N;;;;;;;;;;;;;;;;GAgBG;AAGH,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,MAAM,CA+EzC,CAAC;AAyBH,UAAU,kBAAkB;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAWD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAk0BzD,CAAC;AAoBF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMjD;AAsCD,qBAAa,cAAc;IAEvB,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,UAAU;IAOlB;;;;OAIG;IACH,OAAO,CAAC,aAAa,CAAC;IACtB;;;;;;;;;OASG;IACH,OAAO,CAAC,aAAa,CAAC;gBA5Bd,aAAa,EAAE,CACrB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,CAAC,EAAE,mBAAmB,KACtB,OAAO,CAAC,UAAU,CAAC,EAChB,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAC7B;QACE,UAAU,EAAE,cAAc,CAAC;QAC3B,QAAQ,EAAE,YAAY,CAAC;QACvB,QAAQ,CAAC,EAAE,YAAY,CAAC;KACzB,GACD,SAAS;IACb;;;;OAIG;IACK,aAAa,CAAC,GAAE,MAAM,MAAM,EAAE,aAAA;IACtC;;;;;;;;;OASG;IACK,aAAa,CAAC,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,aAAA;IAGnD,OAAO,CAAC,SAAS;IAIjB,6EAA6E;IAC7E,OAAO,CAAC,YAAY;IASpB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,gBAAgB;IAqCxB,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;IAQzE,OAAO,CAAC,iBAAiB;IAiIzB;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,OAAO,CAAC,cAAc;IAiGtB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAc1B,OAAO,CAAC,oBAAoB;IAiJ5B,OAAO,CAAC,eAAe;IAwGvB,OAAO,CAAC,gBAAgB;CA+YzB"}
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/tools/discovery.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACZ,UAAU,EACX,MAAM,YAAY,CAAC;AAwCpB;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,6NACiM,CAAC;AAE7N;;;;;;;;;;;;;;;;GAgBG;AAGH,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,MAAM,CA+EzC,CAAC;AAyBH,UAAU,kBAAkB;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAWD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAo0BzD,CAAC;AAoBF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMjD;AAsCD,qBAAa,cAAc;IAEvB,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,UAAU;IAOlB;;;;OAIG;IACH,OAAO,CAAC,aAAa,CAAC;IACtB;;;;;;;;;OASG;IACH,OAAO,CAAC,aAAa,CAAC;gBA5Bd,aAAa,EAAE,CACrB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,CAAC,EAAE,mBAAmB,KACtB,OAAO,CAAC,UAAU,CAAC,EAChB,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAC7B;QACE,UAAU,EAAE,cAAc,CAAC;QAC3B,QAAQ,EAAE,YAAY,CAAC;QACvB,QAAQ,CAAC,EAAE,YAAY,CAAC;KACzB,GACD,SAAS;IACb;;;;OAIG;IACK,aAAa,CAAC,GAAE,MAAM,MAAM,EAAE,aAAA;IACtC;;;;;;;;;OASG;IACK,aAAa,CAAC,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,aAAA;IAGnD,OAAO,CAAC,SAAS;IAIjB,6EAA6E;IAC7E,OAAO,CAAC,YAAY;IASpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,OAAO,CAAC,gBAAgB;IAqCxB,8DAA8D;IAC9D,OAAO,CAAC,UAAU;IAIlB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,cAAc;IAStB,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;IAQzE,OAAO,CAAC,iBAAiB;IAiIzB;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,OAAO,CAAC,cAAc;IAiGtB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAc1B,OAAO,CAAC,oBAAoB;IAoJ5B,OAAO,CAAC,eAAe;IAwGvB,OAAO,CAAC,gBAAgB;CAgZzB"}

package/dist/tools/discovery.js

@@ -5,7 +5,7 @@
 // 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 { getAliasFor, retiredToolAnswer } from "./deprecations.js";
 import { getToolMetadata } from "./metadata.js";
 import { RECOVERY_HINTS } from "./recovery-hints.js";
 import { applyArgAliases } from "./arg-aliases.js";
@@ -253,8 +253,8 @@ export const CATEGORIES = {
             "pica_credits_update",
             // pica_recording_credits_update is a superset (batch dispatch on
             // credits[] across a release's tracklist or an explicit recording
-            // list, single call) — pica_recording_credits_bulk_update is now a
-            // hidden alias (deprecations.ts), not listed here.
+            // list, single call) — pica_recording_credits_bulk_update, once a
+            // hidden alias of it, was removed in mcp-server 2.99.0.
             "pica_recording_credits_update",
             // ADR-226 Decision 12 cross-listing — Atlas routes "I want to claim my
             // credit on X" to natural_domain="credits".
@@ -331,9 +331,8 @@ export const CATEGORIES = {
     projects: {
         description: "manage albums, EPs, and work groupings",
         tools: [
-            // pica_projects_list/_get are Tier 2 consolidation aliases now —
-            // subsumed by pica_projects_query/_inspect (see TOOL_ALIASES in
-            // deprecations.ts); hidden from discovery, still callable.
+            // pica_projects_list/_get were Tier 2 consolidation aliases of
+            // pica_projects_query/_inspect — _get removed in 2.93.0, _list in 2.99.0.
             "pica_projects_query",
             "pica_projects_inspect",
             "pica_projects_create",
@@ -348,9 +347,8 @@ export const CATEGORIES = {
     releases: {
         description: "manage releases with dates, labels, and UPCs",
         tools: [
-            // pica_releases_list/_get are Tier 1 consolidation aliases now —
-            // subsumed by pica_releases_query/_inspect (see TOOL_ALIASES in
-            // deprecations.ts); hidden from discovery, still callable.
+            // pica_releases_list/_get were Tier 1 consolidation aliases of
+            // pica_releases_query/_inspect, removed in mcp-server 2.99.0.
             "pica_releases_query",
             "pica_releases_inspect",
             "pica_releases_create",
@@ -358,8 +356,8 @@ export const CATEGORIES = {
             "pica_releases_delete",
             // ADR-175 workflow tools
             // pica_releases_bulk_attach_tracks and pica_releases_attach_track_by_identifier
-            // are Tier 1 consolidation aliases now — subsumed by pica_releases_attach_track
-            // (see TOOL_ALIASES in deprecations.ts); hidden from discovery, still callable.
+            // were Tier 1 consolidation aliases of pica_releases_attach_track, removed
+            // in mcp-server 2.99.0.
             "pica_releases_move_track",
             "pica_releases_create_with_tracks",
             "pica_releases_completeness_check",
@@ -390,9 +388,8 @@ export const CATEGORIES = {
     notes: {
         description: "create and manage catalog notes",
         tools: [
-            // pica_notes_list/_get are Tier 2 consolidation aliases now —
-            // subsumed by pica_notes_query/_inspect (see TOOL_ALIASES in
-            // deprecations.ts); hidden from discovery, still callable.
+            // pica_notes_list/_get were Tier 2 consolidation aliases of
+            // pica_notes_query/_inspect — _get removed in 2.93.0, _list in 2.99.0.
             "pica_notes_query",
             "pica_notes_inspect",
             "pica_notes_create",
@@ -488,9 +485,8 @@ export const CATEGORIES = {
         description: "analyse documents with ai",
         tools: [
             "pica_documents_analyse",
-            // pica_documents_list/_read are Tier 2 consolidation aliases now —
-            // subsumed by pica_documents_query/_inspect (see TOOL_ALIASES in
-            // deprecations.ts); hidden from discovery, still callable.
+            // pica_documents_list/_read were Tier 2 consolidation aliases of
+            // pica_documents_query/_inspect, removed in mcp-server 2.99.0.
             "pica_documents_query",
             "pica_documents_inspect",
             "pica_documents_link",
@@ -829,9 +825,9 @@ export const CATEGORIES = {
         tools: [
             "pica_royalties_list",
             "pica_royalties_get",
-            // pica_statements_list/_get are Tier 2 consolidation aliases now —
-            // subsumed by pica_statements_query/_inspect (see TOOL_ALIASES in
-            // deprecations.ts); hidden from discovery, still callable.
+            // pica_statements_list/_get were Tier 2 consolidation aliases of
+            // pica_statements_query/_inspect — _get removed in 2.93.0, _list in
+            // 2.99.0.
             "pica_statements_query",
             "pica_statements_inspect",
             // ADR-226 Decision 12 cross-listing — Atlas routes "import a royalty
@@ -850,8 +846,14 @@ export const CATEGORIES = {
     },
     // ADR-321 §9 — programmable rights: agents propose, humans confirm by email.
     rights: {
-        description: "programmable rights — propose a song, master or share rule for the parties to confirm, check who has confirmed, and see what money would be held and why",
-        tools: ["pica_rights_inspect", "pica_rights_status", "pica_rights_propose"],
+        description: "programmable rights — propose a song, master or share rule for the parties to confirm, check who has confirmed, see what money would be held and why, and what income would pay each party (computed, never paid)",
+        tools: [
+            "pica_rights_inspect",
+            "pica_rights_status",
+            "pica_rights_propose",
+            "pica_rights_statements",
+            "pica_rights_record_income",
+        ],
         depends_on: [],
     },
     selections: {
@@ -1131,12 +1133,22 @@ export class DiscoveryTools {
      * `[...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
+     * alias (`pica_releases_list`, since removed in 2.99.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.
+     * is the opposite of what this envelope is for. TOOL_ALIASES is empty as of
+     * 2.99.0, so the filter currently removes nothing; it stays for the next
+     * deprecation.
+     *
+     * Tools the caller cannot run here are excluded too ({@link canSuggest}).
+     * The pool is every REGISTERED name, and on HTTP the route narrows what a
+     * caller may run through `setToolVisibility` (audience + scope). Without
+     * this filter a caller lacking finance scope was offered hidden
+     * statements/royalties tools for a statements typo — the same names the
+     * hosted route's suggester (`app/api/mcp/tool-not-found.ts`) never offers,
+     * because its pool is the caller's callable set.
      */
     suggestToolNames(input) {
-        const candidates = (this.listToolNames?.() ?? []).filter((name) => getAliasFor(name) === undefined);
+        const candidates = (this.listToolNames?.() ?? []).filter((name) => getAliasFor(name) === undefined && this.canSuggest(name));
         const tokens = new Set(input
             .replace(/^pica_/, "")
             .split("_")
@@ -1163,6 +1175,26 @@ export class DiscoveryTools {
             .slice(0, 3)
             .map((c) => c.name));
     }
+    /** Registered AND callable by this caller on this surface. */
+    canSuggest(name) {
+        return this.getToolDef(name) !== undefined && this.isVisible(name);
+    }
+    /**
+     * The suggestions and leading note for a name that is not registered. A
+     * retired name (RETIRED_TOOLS in deprecations.ts) gets its replacement
+     * first (when callable) and a sentence saying what replaced it; any other
+     * name gets the similarity ranking unchanged.
+     *
+     * What is shared with the hosted route (`app/api/mcp/tool-not-found.ts`)
+     * is `retiredToolAnswer`, so both name the same replacement — pinned on
+     * this side by `src/__tests__/tools/tool-details-contract.test.ts` and on
+     * that side by `app/api/mcp/__tests__/tool-not-found.test.ts`. The
+     * similarity lists are NOT shared: each side ranks with its own suggester
+     * over its own pool, so for non-retired names the two may differ.
+     */
+    notFoundAnswer(input) {
+        return retiredToolAnswer(input, this.suggestToolNames(input), (name) => this.canSuggest(name));
+    }
     getTools() {
         return [
             this.buildDiscoverTool(),
@@ -1457,12 +1489,13 @@ export class DiscoveryTools {
                         //
                         // Same helper, same envelope keys as the execute branch, so an
                         // agent reads one shape wherever the question is asked.
-                        const suggestions = this.suggestToolNames(args.tool);
+                        const { suggestions, note } = this.notFoundAnswer(args.tool);
                         const envelope = {
                             error: "TOOL_NOT_FOUND",
                             error_code: "TOOL_NOT_FOUND",
                             tool: args.tool,
                             message: `no tool named '${args.tool}'.` +
+                                (note ? ` ${note}` : "") +
                                 (suggestions.length > 0
                                     ? ` Closest real tools: ${suggestions.join(", ")}.`
                                     : "") +
@@ -1813,12 +1846,13 @@ export class DiscoveryTools {
                 // reads it everywhere else. Unifying the file on one key is a
                 // separate change — do it for all six envelopes or none.
                 if (!registered) {
-                    const suggestions = this.suggestToolNames(toolName);
+                    const { suggestions, note } = this.notFoundAnswer(toolName);
                     const envelope = {
                         error: "TOOL_NOT_FOUND",
                         error_code: "TOOL_NOT_FOUND",
                         tool: toolName,
                         message: `${toolName} is not a registered tool.` +
+                            (note ? ` ${note}` : "") +
                             (suggestions.length > 0
                                 ? ` Closest real tools: ${suggestions.join(", ")}.`
                                 : "") +