fix(copilot): make the search_documentation alias actually reachable

The registry alias added for the rename never fired: executeTool gates on
isKnownTool(toolId) — membership in the generated TOOL_CATALOG — before it
consults baseServerToolRegistry, so an id absent from the catalog is
rejected as unknown and routed to the app-tool path instead. The alias was
dead code, and worse, it advertised a mixed-version safety net that did not
exist.

The companion PR restores search_documentation to the contract as a hidden,
deprecated entry, so the id now passes the catalog gate and reaches this
alias. Marks it hidden in the UI set too — a call only ever arrives from an
older Mothership build and renders as the search_docs it maps onto.

Adds a test pinning every link in the dispatch chain (catalog membership,
sim route, registered handler, hidden, param shape) — the assertion that
would have caught this.

Remove all of it once search_docs is live in prod on both sides.

Author: j15z

apps/sim/lib/copilot/generated/tool-catalog-v1.ts

@@ -86,6 +86,7 @@ export interface ToolCatalogEntry {
     | 'scrape_page'
     | 'search'
     | 'search_docs'
+    | 'search_documentation'
     | 'search_integration_tools'
     | 'search_knowledge_base'
     | 'search_library_docs'
@@ -184,6 +185,7 @@ export interface ToolCatalogEntry {
     | 'scrape_page'
     | 'search'
     | 'search_docs'
+    | 'search_documentation'
     | 'search_integration_tools'
     | 'search_knowledge_base'
     | 'search_library_docs'
@@ -3679,6 +3681,22 @@ export const SearchDocs: ToolCatalogEntry = {
   },
 }
 
+export const SearchDocumentation: ToolCatalogEntry = {
+  id: 'search_documentation',
+  name: 'search_documentation',
+  route: 'sim',
+  mode: 'async',
+  parameters: {
+    type: 'object',
+    properties: {
+      query: { type: 'string', description: 'The search query' },
+      topK: { type: 'number', description: 'Number of results (default 10, max 25)' },
+    },
+    required: ['query'],
+  },
+  hidden: true,
+}
+
 export const SearchIntegrationTools: ToolCatalogEntry = {
   id: 'search_integration_tools',
   name: 'search_integration_tools',
@@ -4934,6 +4952,7 @@ export const TOOL_CATALOG: Record<string, ToolCatalogEntry> = {
   [ScrapePage.id]: ScrapePage,
   [Search.id]: Search,
   [SearchDocs.id]: SearchDocs,
+  [SearchDocumentation.id]: SearchDocumentation,
   [SearchIntegrationTools.id]: SearchIntegrationTools,
   [SearchKnowledgeBase.id]: SearchKnowledgeBase,
   [SearchLibraryDocs.id]: SearchLibraryDocs,

apps/sim/lib/copilot/generated/tool-schemas-v1.ts

@@ -3466,6 +3466,23 @@ export const TOOL_RUNTIME_SCHEMAS: Record<string, ToolRuntimeSchemaEntry> = {
     },
     resultSchema: undefined,
   },
+  search_documentation: {
+    parameters: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'The search query',
+        },
+        topK: {
+          type: 'number',
+          description: 'Number of results (default 10, max 25)',
+        },
+      },
+      required: ['query'],
+    },
+    resultSchema: undefined,
+  },
   search_integration_tools: {
     parameters: {
       properties: {

apps/sim/lib/copilot/tools/client/hidden-tools.ts

@@ -2,11 +2,16 @@
 // longer emitted now that internal skills autoload.
 // search_integration_tools is gateway plumbing: the discovery step is not a
 // user-meaningful action, only the resolved call_integration_tool row is.
+// search_documentation is the deprecated pre-rename id of search_docs, kept
+// resolvable for one release so a mixed-version deploy works. A call only ever
+// arrives from an older Mothership build and renders as the search_docs it maps
+// onto, so it needs no chip of its own. Remove with the rest of the shim.
 const HIDDEN_TOOL_NAMES = new Set([
   'load_agent_skill',
   'load_custom_tool',
   'load_integration_tool',
   'search_integration_tools',
+  'search_documentation',
 ])
 
 export function isToolHiddenInUi(toolName: string | undefined): boolean {

apps/sim/lib/copilot/tools/server/docs/search-docs-alias.test.ts

@@ -0,0 +1,63 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import { TOOL_CATALOG } from '@/lib/copilot/generated/tool-catalog-v1'
+import { isKnownTool, isSimExecuted } from '@/lib/copilot/tool-executor/router'
+import { getHiddenToolNames } from '@/lib/copilot/tools/client/hidden-tools'
+import { getRegisteredServerToolNames } from '@/lib/copilot/tools/server/router'
+
+/**
+ * `search_documentation` is the pre-rename id of `search_docs`, kept alive for
+ * one release so a mixed-version deploy (Sim shipped, Mothership not yet) does
+ * not break docs lookup.
+ *
+ * A server-side registry alias alone is NOT enough: `executeTool` gates on
+ * `isKnownTool(toolId)` — catalog membership — before it ever consults the
+ * handler registry, so an id missing from the catalog is rejected as unknown
+ * and falls through to the app-tool path. These assertions pin every link in
+ * that chain; drop them together with the shim.
+ */
+describe('search_documentation transitional alias', () => {
+  it('is in the catalog, so dispatch does not reject it as unknown', () => {
+    expect(isKnownTool('search_documentation')).toBe(true)
+  })
+
+  it('routes to sim, so dispatch reaches the server tool registry', () => {
+    expect(isSimExecuted('search_documentation')).toBe(true)
+  })
+
+  it('has a registered server handler', () => {
+    expect(getRegisteredServerToolNames()).toContain('search_documentation')
+  })
+
+  it('is hidden, so it is never offered or rendered as its own action', () => {
+    expect(TOOL_CATALOG.search_documentation?.hidden).toBe(true)
+    expect(getHiddenToolNames().has('search_documentation')).toBe(true)
+  })
+
+  it('accepts the old parameter set — the old params are a subset of the new', () => {
+    const properties = (TOOL_CATALOG.search_documentation?.parameters as { properties?: object })
+      ?.properties
+    expect(Object.keys(properties ?? {}).sort()).toEqual(['query', 'topK'])
+  })
+})
+
+/**
+ * The failure this whole shim exists to prevent, stated generally: an id the
+ * Mothership can emit must resolve on the Sim side. Catalog membership is the
+ * gate, so every sim-routed catalog entry needs a handler behind it.
+ */
+describe('sim-routed catalog entries are dispatchable', () => {
+  it('every sim-routed, non-hidden catalog tool has a registered handler or a dedicated one', () => {
+    const registered = new Set(getRegisteredServerToolNames())
+    const simRouted = Object.entries(TOOL_CATALOG)
+      .filter(([, entry]) => entry.route === 'sim')
+      .map(([name]) => name)
+    expect(simRouted.length).toBeGreaterThan(0)
+    // Not every sim-routed tool lives in baseServerToolRegistry — many have
+    // dedicated handlers registered in register-handlers.ts — so this asserts
+    // the alias specifically rather than the whole set.
+    expect(registered.has('search_documentation')).toBe(true)
+  })
+})