@fitchmultz/pi-mcp-adapter 5.0.0 → 6.0.0

package/proxy-modes.ts

@@ -3,16 +3,15 @@ import type { Client } from "@modelcontextprotocol/client";
 import { DEFAULT_REQUEST_TIMEOUT_MSEC, UrlElicitationRequiredError } from "@modelcontextprotocol/client";
 import type { McpExtensionState } from "./state.ts";
 import type { ServerConnection } from "./server-manager.ts";
-import type { ToolMetadata, McpContent, McpOperationContext, McpToolCallEvent, McpToolCallIdentity } from "./types.ts";
+import type { ToolMetadata, McpOperationContext, McpToolCallEvent, McpToolCallIdentity } from "./types.ts";
 import { getServerPrefix, isServerDisabled, isNonInteractiveOAuth, parseUiPromptHandoff, resolveToolPrefix } from "./types.ts";
 import { lazyConnect, markKeepAliveAfterConnect, notifyToolMetadataUpdated, updateServerMetadata, updateMetadataCache, getFailureAgeSeconds, updateStatusBar, clearFailure, recordFailure } from "./init.ts";
 import { abortable, throwIfAborted } from "./abort.ts";
 import { combineAbortSignals, isAbortError } from "./runtime-owner.ts";
-import { buildToolMetadata, findToolByName, formatSchema } from "./tool-metadata.ts";
-import { renderTsShape } from "./ts-shape.ts";
+import { buildToolMetadata, catalogCoverage, findToolByName, formatSchema, toToolDescriptor } from "./tool-metadata.ts";
 import { reconstructPromptMetadata } from "./metadata-cache.ts";
-import { resolveMcpResultContent, transformMcpContent } from "./tool-registrar.ts";
-import { guardMcpOutput, guardedMcpDetails, resolveMcpOutputGuardOptions } from "./mcp-output-guard.ts";
+import { renderMcpResultContent } from "./tool-registrar.ts";
+import { guardMcpOutput, guardedMcpDetails, retainMcpResult, resolveMcpOutputGuardOptions, formatMcpResultReference } from "./mcp-output-guard.ts";
 import { maybeStartUiSession, summarizeUiSessionResult, type UiSessionRuntime } from "./ui-session.ts";
 import { formatAuthRequiredMessage, formatMcpStatus, resolveServerUrl, truncateAtWord } from "./utils.ts";
 import { authenticate, completeAuthFromInput, startAuth, supportsOAuth } from "./mcp-auth-flow.ts";
@@ -87,7 +86,7 @@ function formatManualAuthInstructions(serverName: string, authorizationUrl: stri
     "If the browser cannot reach the callback, copy the full redirected localhost URL from your address bar and send it back with:",
     `mcp({ action: "auth-complete", server: "${serverName}", args: { redirectUrl: "PASTE_REDIRECT_URL_HERE" } })`,
     "",
-    'You can also pass just the `code` query parameter as `args: { code: "PASTE_CODE_HERE" }`. JSON-string args remain supported.',
+    'You can also pass just the `code` query parameter as `args: { code: "PASTE_CODE_HERE" }`.',
     portNote.trimEnd(),
   ].filter(Boolean).join("\n");
 }
@@ -252,7 +251,7 @@ export function executeStatus(state: McpExtensionState): ProxyToolResult {
     const disabled = isServerDisabled(definition);
     const connection = disabled ? undefined : state.manager.getConnection(name);
     const metadata = disabled ? undefined : state.toolMetadata.get(name);
-    const toolCount = metadata?.length ?? 0;
+    const toolCount = metadata?.filter(tool => !tool.resourceUri).length ?? 0;
     const failedAgo = disabled ? null : getFailureAgeSeconds(state, name);
     let status = disabled ? "disabled" : "not connected";
     if (!disabled && connection?.status === "connected") {
@@ -272,6 +271,7 @@ export function executeStatus(state: McpExtensionState): ProxyToolResult {
   const enabledServers = servers.filter(s => !s.disabled);
   const totalTools = enabledServers.reduce((sum, s) => sum + s.toolCount, 0);
   const connectedCount = enabledServers.filter(s => s.status === "connected").length;
+  const coverage = catalogCoverage(state);
 
   let text = `MCP: ${connectedCount}/${enabledServers.length} connected, ${totalTools} tools available (calls connect lazily)`;
   if (disabledCount > 0) text += ` (${disabledCount} disabled)`;
@@ -297,16 +297,17 @@ export function executeStatus(state: McpExtensionState): ProxyToolResult {
       text += `✗ ${server.name} (failed ${server.failedAgo ?? 0}s ago)\n`;
       continue;
     }
-    text += `○ ${server.name} (not connected)\n`;
+    text += `○ ${server.name} (not discovered)\n`;
   }
 
   if (servers.length > 0) {
-    text += `\nmcp({ server: "name" }) to browse tools, mcp({ search: "..." }) to search`;
+    text += `\nmcp_search({ query: "...", server: "name" }) to discover tools; mcp({ action: "resources", server: "name" }) for resources.`;
+    if (!coverage.complete) text += `\nPartial catalog: ${coverage.unknownServers.length} undiscovered server(s).`;
   }
 
   return {
     content: [{ type: "text" as const, text: text.trim() }],
-    details: { mode: "status", servers, totalTools, connectedCount, disabledCount },
+    details: { mode: "status", servers, totalTools, connectedCount, disabledCount, coverage },
   };
 }
 
@@ -316,7 +317,7 @@ export async function executeAuthStart(state: McpExtensionState, serverName: str
   const definition = state.config.mcpServers[serverName];
   if (!definition) {
     return {
-      content: [{ type: "text" as const, text: `Server "${serverName}" not found. Use mcp({}) to see available servers.` }],
+      content: [{ type: "text" as const, text: `Server "${serverName}" not found. Use mcp({ action: "status" }) to see available servers.` }],
       details: { mode: "auth-start", error: "not_found", server: serverName },
     };
   }
@@ -364,7 +365,7 @@ export async function executeAuthComplete(state: McpExtensionState, serverName:
   const definition = state.config.mcpServers[serverName];
   if (!definition) {
     return {
-      content: [{ type: "text" as const, text: `Server "${serverName}" not found. Use mcp({}) to see available servers.` }],
+      content: [{ type: "text" as const, text: `Server "${serverName}" not found. Use mcp({ action: "status" }) to see available servers.` }],
       details: { mode: "auth-complete", error: "not_found", server: serverName },
     };
   }
@@ -390,7 +391,7 @@ export async function executeAuthComplete(state: McpExtensionState, serverName:
     clearFailure(state, serverName);
     updateStatusBar(state);
     return {
-      content: [{ type: "text" as const, text: `OAuth authentication successful for "${serverName}". Run mcp({ connect: "${serverName}" }) to connect with the new token.` }],
+      content: [{ type: "text" as const, text: `OAuth authentication successful for "${serverName}". Run mcp({ action: "connect", server: "${serverName}" }) to connect with the new token.` }],
       details: { mode: "auth-complete", server: serverName, authenticated: true },
     };
   } catch (error) {
@@ -402,57 +403,36 @@ export async function executeAuthComplete(state: McpExtensionState, serverName:
   }
 }
 
-export function executeDescribe(state: McpExtensionState, toolName: string): ProxyToolResult {
-  let serverName: string | undefined;
-  let toolMeta: ToolMetadata | undefined;
-  let disabledMatch: string | undefined;
-
-  for (const [server, metadata] of state.toolMetadata.entries()) {
-    const found = findToolByName(metadata, toolName);
-    if (!found) continue;
-    if (isServerDisabled(state.config.mcpServers[server])) {
-      disabledMatch ??= server;
-      continue;
-    }
-    serverName = server;
-    toolMeta = found;
-    break;
-  }
-
-  if (!serverName || !toolMeta) {
-    if (disabledMatch) return disabledResult("describe", disabledMatch);
-    const suggestions = rankSuggestions(state, toolName, 5);
+export function executeDescribe(state: McpExtensionState, toolName: string, serverFilter?: string): ProxyToolResult {
+  if (serverFilter && isServerDisabled(state.config.mcpServers[serverFilter])) return disabledResult("describe", serverFilter);
+  const catalog = [...state.toolMetadata].flatMap(([server, tools]) =>
+    (!serverFilter || serverFilter === server) && state.config.mcpServers[server] && !isServerDisabled(state.config.mcpServers[server])
+      ? tools.map(tool => ({ server, tool })) : []);
+  const originals = serverFilter ? catalog.filter(({ tool }) => tool.originalName === toolName) : [];
+  const exact = originals.length ? originals : catalog.filter(({ tool }) => tool.name === toolName);
+  const matches = exact.length ? exact : catalog.filter(({ tool }) => tool.name.replace(/-/g, "_") === toolName.replace(/-/g, "_"));
+  if (matches.length > 1) return {
+    content: [{ type: "text", text: `Tool ${JSON.stringify(toolName)} is ambiguous. Specify server and original tool name: ${JSON.stringify(matches.map(({ server, tool }) => ({ server, tool: tool.originalName })))}` }],
+    details: { mode: "describe", error: "ambiguous_tool", requestedTool: toolName },
+  };
+  const match = matches[0];
+  if (!match) {
+    const disabled = [...state.toolMetadata].find(([server, tools]) => isServerDisabled(state.config.mcpServers[server]) && findToolByName(tools, toolName));
+    if (disabled) return disabledResult("describe", disabled[0]);
+    const suggestions = rankSuggestions(state, toolName, 5, serverFilter);
     const hint = suggestions.length > 0
-      ? `Did you mean: ${suggestions.join(", ")}. Inspect with mcp({ describe: "${suggestions[0]}" }).`
-      : `Use mcp({ search: "..." }) to search.`;
+      ? `Did you mean: ${suggestions.join(", ")}. Inspect with mcp({ action: "describe", tool: "${suggestions[0]}" }).`
+      : `Use mcp_search({ query: "..." }) to search.`;
     return {
-      content: [{ type: "text" as const, text: `Tool "${toolName}" not found. ${hint}` }],
+      content: [{ type: "text", text: `Tool "${toolName}" not found. ${hint}` }],
       details: { mode: "describe", error: "tool_not_found", requestedTool: toolName, suggestions },
     };
   }
-
-  const approvalMarker = isToolCallApprovalRequired(state.config, serverName, toolMeta)
-    ? " (requires approval)"
-    : "";
-  let text = `${toolMeta.name}${approvalMarker}\n`;
-  text += `Server: ${serverName}\n`;
-  if (toolMeta.resourceUri) {
-    text += `Type: Resource (reads from ${toolMeta.resourceUri})\n`;
-  }
-  text += `\n${toolMeta.description || "(no description)"}\n`;
-  if (toolMeta.annotations) text += `\nAnnotations: ${JSON.stringify(toolMeta.annotations)}\n`;
-
-  if (toolMeta.inputSchema && !toolMeta.resourceUri) {
-    const shape = renderTsShape(toolMeta.inputSchema);
-    text += shape === null ? `\nParameters:\n${formatSchema(toolMeta.inputSchema)}` : `\nShape:\n${shape}`;
-  } else if (toolMeta.resourceUri) {
-    text += `\nNo parameters required (resource tool).`;
-  } else {
-    text += `\nNo parameters defined.`;
-  }
-
+  const { server: serverName, tool: toolMeta } = match;
+  const descriptor = toToolDescriptor(serverName, toolMeta);
+  const approvalRequired = isToolCallApprovalRequired(state.config, serverName, toolMeta);
   return {
-    content: [{ type: "text" as const, text: text.trim() }],
+    content: [{ type: "text", text: JSON.stringify({ ...descriptor, ...(toolMeta.resourceUri ? { resourceUri: toolMeta.resourceUri, readWith: { action: "read-resource", server: serverName, uri: toolMeta.resourceUri } } : {}), ...(approvalRequired ? { approvalRequired: true } : {}) }, null, 2) }],
     details: { mode: "describe", tool: toolMeta, server: serverName },
   };
 }
@@ -467,7 +447,7 @@ export function executeSearch(
 ): ProxyToolResult {
   const showSchemas = includeSchemas !== false;
   const searchCall = (nextOffset: number | null) =>
-    `mcp({ search: ${JSON.stringify(query)}${server ? `, server: ${JSON.stringify(server)}` : ""}${showSchemas ? "" : ", includeSchemas: false"}, limit: ${limit}, offset: ${nextOffset} })`;
+    `mcp({ action: "search", query: ${JSON.stringify(query)}${server ? `, server: ${JSON.stringify(server)}` : ""}${showSchemas ? "" : ", includeSchemas: false"}, limit: ${limit}, offset: ${nextOffset} })`;
   if (server && isServerDisabled(state.config.mcpServers[server])) return disabledResult("search", server);
 
   let matches: Array<{ server: string; tool: ToolMetadata; score: number }>;
@@ -478,7 +458,7 @@ export function executeSearch(
         details: { mode: "search", error: "empty_query" },
       };
     }
-    matches = (state.toolMetadata.get(server) ?? [])
+    matches = (state.toolMetadata.get(server) ?? []).filter(tool => !tool.resourceUri)
       .map(tool => ({ server, tool, score: 0 }))
       .sort((a, b) => a.tool.name.localeCompare(b.tool.name));
   } else {
@@ -486,11 +466,13 @@ export function executeSearch(
   }
 
   const page = paginate(matches, offset, limit);
+  const coverage = catalogCoverage(state, server);
+  const coverageNotice = coverage.complete ? "" : `\nCatalog is incomplete. Undiscovered servers: ${coverage.unknownServers.join(", ")}. Search with server to discover one.`;
   if (page.total === 0) {
     const msg = server ? `No tools matching "${query}" in "${server}"` : `No tools matching "${query}"`;
     return {
-      content: [{ type: "text" as const, text: msg }],
-      details: { mode: "search", matches: [], count: 0, hasMore: false, nextOffset: null, query },
+      content: [{ type: "text" as const, text: msg + coverageNotice }],
+      details: { mode: "search", matches: [], count: 0, hasMore: false, nextOffset: null, query, coverage },
     };
   }
   if (page.items.length === 0) {
@@ -507,17 +489,7 @@ export function executeSearch(
       ? " (requires approval)"
       : "";
     if (showSchemas) {
-      text += `${match.tool.name}${approvalMarker}\n`;
-      text += `  ${match.tool.description || "(no description)"}\n`;
-      if (match.tool.inputSchema && !match.tool.resourceUri) {
-        const shape = renderTsShape(match.tool.inputSchema);
-        text += shape === null
-          ? `\n  Parameters:\n${formatSchema(match.tool.inputSchema, "    ")}\n`
-          : `\n  Shape:\n${shape.split("\n").map(line => `    ${line}`).join("\n")}\n`;
-      } else if (match.tool.resourceUri) {
-        text += "  No parameters (resource tool).\n";
-      }
-      text += "\n";
+      text += `${JSON.stringify({ ...toToolDescriptor(match.server, match.tool), ...(approvalMarker ? { approvalRequired: true } : {}) }, null, 2)}\n\n`;
     } else {
       text += `- ${match.tool.name}${approvalMarker}`;
       if (match.tool.description) text += ` - ${truncateAtWord(match.tool.description, 50)}`;
@@ -531,9 +503,10 @@ export function executeSearch(
     : `\n${first}-${first + page.items.length - 1} of ${page.total} — end\n`;
 
   return {
-    content: [{ type: "text" as const, text: text.trim() }],
+    content: [{ type: "text" as const, text: text.trim() + coverageNotice }],
     details: {
       mode: "search",
+      coverage,
       matches: page.items.map(match => ({ server: match.server, tool: match.tool.name, score: match.score })),
       count: page.total,
       hasMore: page.hasMore,
@@ -547,13 +520,13 @@ export function executeList(state: McpExtensionState, server: string, limit = 12
   const definition = state.config.mcpServers[server];
   if (!definition) {
     return {
-      content: [{ type: "text" as const, text: `Server "${server}" not found. Use mcp({}) to see available servers.` }],
+      content: [{ type: "text" as const, text: `Server "${server}" not found. Use mcp({ action: "status" }) to see available servers.` }],
       details: { mode: "list", server, tools: [], count: 0, error: "not_found" },
     };
   }
   if (isServerDisabled(definition)) return disabledResult("list", server);
 
-  const metadata = state.toolMetadata.get(server);
+  const metadata = state.toolMetadata.get(server)?.filter(tool => !tool.resourceUri);
   const connection = state.manager.getConnection(server);
   const instructions = state.serverInstructions.get(server);
   let instructionsText = "";
@@ -561,7 +534,7 @@ export function executeList(state: McpExtensionState, server: string, limit = 12
     const preview = truncateAtWord(instructions, INSTRUCTIONS_PREVIEW_LENGTH);
     instructionsText = `\n\nServer instructions:\n${preview}`;
     if (preview !== instructions) {
-      instructionsText += `\nUse mcp({ instructions: "${server}" }) for the full text.`;
+      instructionsText += `\nUse mcp({ action: "instructions", server: "${server}" }) for the full text.`;
     }
   }
 
@@ -579,7 +552,7 @@ export function executeList(state: McpExtensionState, server: string, limit = 12
       };
     }
     return {
-      content: [{ type: "text" as const, text: `Server "${server}" is configured but not connected. Use mcp({ connect: "${server}" }) or /mcp reconnect ${server} to retry.${instructionsText}` }],
+      content: [{ type: "text" as const, text: `Server "${server}" is configured but not connected. Use mcp({ action: "connect", server: "${server}" }) or /mcp reconnect ${server} to retry.${instructionsText}` }],
       details: { mode: "list", server, tools: [], count: 0, error: "not_connected", hasInstructions: Boolean(instructions) },
     };
   }
@@ -587,7 +560,7 @@ export function executeList(state: McpExtensionState, server: string, limit = 12
   const page = paginate(metadata, offset, limit);
   if (page.items.length === 0) {
     return {
-      content: [{ type: "text" as const, text: `No tools at offset ${offset}; "${server}" has ${page.total} tools. Retry with mcp({ server: ${JSON.stringify(server)}, limit: ${limit}, offset: 0 }).` }],
+      content: [{ type: "text" as const, text: `No tools at offset ${offset}; "${server}" has ${page.total} tools. Retry with mcp({ action: "list", server: ${JSON.stringify(server)}, limit: ${limit}, offset: 0 }).` }],
       details: { mode: "list", error: "offset_out_of_range", server, tools: [], count: page.total, hasMore: false, nextOffset: null, hasInstructions: Boolean(instructions) },
     };
   }
@@ -603,7 +576,7 @@ export function executeList(state: McpExtensionState, server: string, limit = 12
   }
   const first = (Number.isFinite(offset) ? Math.max(0, Math.trunc(offset)) : 0) + 1;
   text += page.hasMore
-    ? `\n${first}-${first + page.items.length - 1} of ${page.total} — mcp({ server: ${JSON.stringify(server)}, limit: ${limit}, offset: ${page.nextOffset} }) for more`
+    ? `\n${first}-${first + page.items.length - 1} of ${page.total} — mcp({ action: "list", server: ${JSON.stringify(server)}, limit: ${limit}, offset: ${page.nextOffset} }) for more`
     : `\n${first}-${first + page.items.length - 1} of ${page.total} — end`;
   text += instructionsText;
 
@@ -625,7 +598,7 @@ export function executeInstructions(state: McpExtensionState, server: string): P
   const definition = state.config.mcpServers[server];
   if (!definition) {
     return {
-      content: [{ type: "text" as const, text: `Server "${server}" not found. Use mcp({}) to see available servers.` }],
+      content: [{ type: "text" as const, text: `Server "${server}" not found. Use mcp({ action: "status" }) to see available servers.` }],
       details: { mode: "instructions", server, error: "not_found" },
     };
   }
@@ -648,7 +621,7 @@ export function executeInstructions(state: McpExtensionState, server: string): P
   }
 
   return {
-    content: [{ type: "text" as const, text: `No instructions cached for "${server}". Use mcp({ connect: "${server}" }) to connect and refresh.` }],
+    content: [{ type: "text" as const, text: `No instructions cached for "${server}". Use mcp({ action: "connect", server: "${server}" }) to connect and refresh.` }],
     details: { mode: "instructions", server, error: "not_connected" },
   };
 }
@@ -665,7 +638,7 @@ export async function executeConnect(
   const definition = state.config.mcpServers[serverName];
   if (!definition) {
     return {
-      content: [{ type: "text" as const, text: `Server "${serverName}" not found. Use mcp({}) to see available servers.` }],
+      content: [{ type: "text" as const, text: `Server "${serverName}" not found. Use mcp({ action: "status" }) to see available servers.` }],
       details: { mode: "connect", error: "not_found", server: serverName },
     };
   }
@@ -702,6 +675,7 @@ export async function executeConnect(
     const prefix = state.config.settings?.toolPrefix ?? "server";
     const { metadata } = buildToolMetadata(connection.tools, connection.resources, definition, serverName, prefix);
     state.toolMetadata.set(serverName, metadata);
+    state.resourceCounts?.set(serverName, connection.resources.length);
     if (!connection.promptDiscoveryFailed) {
       state.promptMetadata?.set(serverName, reconstructPromptMetadata(serverName, connection.prompts ?? [], prefix, definition));
       state.promptMetadataLive?.add(serverName);
@@ -741,15 +715,14 @@ interface ToolCallOptions extends McpToolCallIdentity {
   recoverAuthConnection: NonNullable<SessionRecoveryDeps["onNeedsAuth"]>;
   authRequiredMessage: () => string;
   autoAuthAttempted: () => boolean;
-  onRawResult?: (result: unknown) => void;
+  raw?: boolean;
 }
 
 /**
  * Executes an already-approved tool call against a connected server.
  *
- * Both the `mcp` proxy and direct tools reach this with a resolved target and a
- * live connection; everything before this point (name resolution, connect and
- * auth strategy, approval) differs between them and stays with the caller.
+ * Direct, gateway, resource and script calls share executeCall preparation.
+ * Raw scripts skip content rendering but retain protocol results and artifacts.
  */
 export async function runToolCall(
   state: McpExtensionState,
@@ -758,7 +731,7 @@ export async function runToolCall(
   args: Record<string, unknown> | undefined,
   options: ToolCallOptions,
 ): Promise<ProxyToolResult> {
-  const { detailsBase, signal, recoverAuthConnection, authRequiredMessage, autoAuthAttempted, onRawResult } = options;
+  const { detailsBase, signal, recoverAuthConnection, authRequiredMessage, autoAuthAttempted } = options;
   const configuredOptions = state.manager.getRequestOptions?.(serverName, options.ownedSignal);
   const callerSignal = combineAbortSignals(configuredOptions?.signal, options.ownedSignal);
   const outputGuardOptions = resolveMcpOutputGuardOptions(state.config.settings, state.outputDirectory);
@@ -801,8 +774,7 @@ export async function runToolCall(
         })
       : null;
 
-    // Frozen direct-tool schemas may be older than the live catalog. Never use
-    // stale cached hints in preference to the connected server's annotations.
+    // UI preparation can replace the connection; use its current annotations.
     const liveTools = state.manager.getConnection(serverName)?.tools;
     const annotations = liveTools
       ? liveTools.find(tool => tool.name === target.originalName)?.annotations
@@ -841,62 +813,38 @@ export async function runToolCall(
       return result;
     };
 
-    if (target.resourceUri) {
-      const result = await dispatch(() => withSessionRecovery(
-        recovery,
-        serverName,
-        (conn) => conn.client.readResource({ uri: target.resourceUri! }, requestOptions),
-      ));
-      onRawResult?.(result);
-      const contents = (result.contents ?? []).map(c => ({
-        type: "text" as const,
-        text: "text" in c ? c.text : ("blob" in c ? `[Binary data: ${(c as { mimeType?: string }).mimeType ?? "unknown"}]` : JSON.stringify(c)),
-      }));
-      const guarded = await guardMcpOutput(contents.length > 0 ? contents : [{ type: "text" as const, text: "(empty resource)" }], outputGuardOptions);
-      return { content: guarded.content, details: { ...detailsBase, ...guardedMcpDetails(guarded) } };
-    }
-
-    const result = await dispatch(() => withSessionRecovery<ClientCallToolResult>(
-      { ...recovery, retryOnTransportFailure: annotations?.readOnlyHint === true || annotations?.idempotentHint === true },
-      serverName,
-      (conn) => abortable(conn.client.callTool({
-        name: target.originalName,
-        arguments: args ?? {},
-        _meta: uiSession?.requestMeta,
-      }, requestOptions), ownedSignal),
-    ));
-    uiSession?.sendToolResult(result);
-
-    if (result.isError) {
-      const content = transformMcpContent((result.content ?? []) as McpContent[]);
-      const guarded = await guardMcpOutput(
-        content.length > 0 ? content : [{ type: "text" as const, text: "(empty result)" }],
-        { ...outputGuardOptions, prefix: "Error: ", suffix: schemaSuffix(), emptyTextFallback: "Tool execution failed", rawMcpResult: result },
-      );
-      return { content: guarded.content, details: { ...detailsBase, error: "tool_error", ...guardedMcpDetails(guarded) } };
-    }
-
-    onRawResult?.(result);
-    const content = resolveMcpResultContent(result as Record<string, unknown>);
-    const outputContent = content.length > 0 ? content : [{ type: "text" as const, text: "(empty result)" }];
-
-    if (target.uiResourceUri) {
-      const uiSummary = summarizeUiSessionResult(uiSession);
-      const guarded = await guardMcpOutput(outputContent, { ...outputGuardOptions, suffix: `\n\n${uiSummary.message}`, rawMcpResult: result });
-      return {
-        content: guarded.content,
-        details: {
-          ...detailsBase,
-          ...guardedMcpDetails(guarded),
-          uiOpen: uiSummary.uiOpen,
-          uiViewer: uiSummary.uiViewer,
-          uiUrl: uiSummary.uiUrl,
-        },
-      };
+    const result = target.resourceUri
+      ? await dispatch(() => withSessionRecovery(
+          recovery, serverName,
+          conn => abortable(conn.client.readResource({ uri: target.resourceUri! }, requestOptions), ownedSignal),
+        ))
+      : await dispatch(() => withSessionRecovery<ClientCallToolResult>(
+          { ...recovery, retryOnTransportFailure: annotations?.readOnlyHint === true || annotations?.idempotentHint === true },
+          serverName,
+          conn => abortable(conn.client.callTool({ name: target.originalName, arguments: args ?? {}, _meta: uiSession?.requestMeta }, requestOptions), ownedSignal),
+        ));
+    if (!target.resourceUri) uiSession?.sendToolResult(result as ClientCallToolResult);
+    const record = result as Record<string, unknown>;
+    const isError = record.isError === true;
+    const uiSummary = target.uiResourceUri ? summarizeUiSessionResult(uiSession) : undefined;
+    const details = {
+      ...detailsBase,
+      ...(isError ? { error: "tool_error" } : {}),
+      ...(uiSummary ? { uiOpen: uiSummary.uiOpen, uiViewer: uiSummary.uiViewer, uiUrl: uiSummary.uiUrl } : {}),
+    };
+    const retained = await retainMcpResult(result, outputGuardOptions, options.raw);
+    if (options.raw) {
+      const message = isError
+        ? (Array.isArray(record.content) ? record.content.filter(block => block.type === "text").map(block => block.text).join("\n") : "") || "Tool execution failed" : undefined;
+      return { content: [], details: { ...details, ...retained, ...(message ? { message } : {}) } };
     }
-
-    const guarded = await guardMcpOutput(outputContent, { ...outputGuardOptions, rawMcpResult: result });
-    return { content: guarded.content, details: { ...detailsBase, ...guardedMcpDetails(guarded) } };
+    const content = renderMcpResultContent(record, retained.payloadFiles);
+    const guarded = await guardMcpOutput(content.length ? content : [{ type: "text", text: target.resourceUri ? "(empty resource)" : "(empty result)" }], {
+      ...outputGuardOptions, retainedMcpResult: retained,
+      ...(isError ? { prefix: "Error: ", suffix: schemaSuffix(), emptyTextFallback: "Tool execution failed" }
+        : uiSummary ? { suffix: `\n\n${uiSummary.message}` } : {}),
+    });
+    return { content: guarded.content, details: { ...details, ...guardedMcpDetails(guarded) } };
   } catch (error) {
     // Direct/proxy host errors throw; scripts retain their failed-call envelope.
     if (beforeDispatchPending && options.innerCallId === undefined) throw error;
@@ -906,9 +854,11 @@ export async function runToolCall(
         ? "MCP call capture failed before dispatch; the tool did not run. Restore capture before continuing."
         : "MCP outcome capture failed. Use the retained outcome to continue the original work; do not repeat a completed call or rerun the script.";
       uiSession?.sendToolCancelled(message);
+      const retained = "result" in captureFailure && captureFailure.result !== undefined
+        ? await retainMcpResult(captureFailure.result, { ...outputGuardOptions, enabled: true, detailsMaxBytes: 1 }) : {};
       return {
-        content: [{ type: "text", text: message }],
-        details: { ...detailsBase, error: isAbortError(error, callerSignal) ? "aborted" : "call_capture_failed", message, recovery: context },
+        content: [{ type: "text", text: message }, ...(retained.resultRef ? [{ type: "text" as const, text: formatMcpResultReference(retained.resultRef) }] : [])],
+        details: { ...detailsBase, ...retained, error: isAbortError(error, callerSignal) ? "aborted" : "call_capture_failed", message, recovery: context },
       };
     }
     if (isToolTransportFailure(error)) {
@@ -959,6 +909,82 @@ export async function runToolCall(
   }
 }
 
+export interface ExecuteCallOptions {
+  exactOriginalName?: boolean;
+  resourceUri?: string;
+  /** Scripts receive the raw protocol result without model-facing content transformation. */
+  raw?: boolean;
+}
+
+/** Connect/auth once for calls and resource discovery. Recovery stays bounded by withSessionRecovery. */
+export async function prepareMcpConnection(state: McpExtensionState, serverName: string, signal?: AbortSignal) {
+  const ownedSignal = combineAbortSignals(state.owner?.signal, signal);
+  throwIfAborted(ownedSignal);
+  let autoAuthAttempted = false;
+  const recoverAuthConnection: NonNullable<SessionRecoveryDeps["onNeedsAuth"]> = async (_name, recoverySignal = ownedSignal, challenge) => {
+    throwIfAborted(recoverySignal);
+    const current = state.manager.getConnection(serverName);
+    if (current?.status === "connected" && current !== challenge?.connection) return current;
+    if (!autoAuthAttempted) {
+      autoAuthAttempted = true;
+      const auth = await attemptAutoAuth(state, serverName, recoverySignal);
+      throwIfAborted(recoverySignal);
+      if (auth.status === "failed") throw new SessionRecoveryAuthRequiredError(serverName, auth.message);
+      if (auth.status === "success" && current) {
+        clearFailure(state, serverName);
+        const definition = state.config.mcpServers[serverName];
+        if (!definition) return undefined;
+        state.ui?.setStatus("mcp", formatMcpStatus(state.config, `connecting to ${serverName}...`));
+        await state.manager.reconnect(serverName, definition, current, recoverySignal);
+        if (await lazyConnect(state, serverName, recoverySignal)) {
+          updateStatusBar(state);
+          return state.manager.getConnection(serverName);
+        }
+      }
+    }
+    return challenge ? undefined : state.manager.getConnection(serverName);
+  };
+  const failure = (error: string, message: string) => ({
+    content: [{ type: "text" as const, text: message }],
+    details: { mode: "call", error, server: serverName, message },
+  });
+  const definition = state.config.mcpServers[serverName];
+  if (!definition) return { error: failure("server_not_found", `Server "${serverName}" not found.`) };
+  if (isServerDisabled(definition)) return { error: disabledResult("call", serverName) };
+  try {
+    // Connected metadata is read below, so it does not require another connection attempt.
+    let connection = state.manager.getConnection(serverName);
+    if (connection?.status !== "connected") {
+      await lazyConnect(state, serverName, ownedSignal);
+      connection = state.manager.getConnection(serverName);
+    } else {
+      markKeepAliveAfterConnect(state, serverName);
+    }
+    if (connection?.status === "needs-auth") connection = await recoverAuthConnection(serverName, ownedSignal);
+    if (connection?.status === "needs-auth") throw new SessionRecoveryAuthRequiredError(serverName);
+    if (connection?.status !== "connected") {
+      const failedAgo = getFailureAgeSeconds(state, serverName);
+      return { error: failure(failedAgo === null ? "server_unavailable" : "server_backoff", `Server "${serverName}" not available${failedAgo === null ? "" : ` (last failed ${failedAgo}s ago)`}`) };
+    }
+    // Use the live descriptor for visibility, filtering, approval, schema and UI hints.
+    if (connection.tools) {
+      const { metadata } = buildToolMetadata(connection.tools, connection.resources ?? [], definition, serverName, state.config.settings?.toolPrefix ?? "server");
+      state.toolMetadata.set(serverName, metadata);
+    }
+    return { connection, recoverAuthConnection, autoAuthAttempted: () => autoAuthAttempted };
+  } catch (error) {
+    if (isAbortError(error, ownedSignal)) throw error;
+    const message = error instanceof SessionRecoveryAuthRequiredError
+      ? error.authMessage ?? getAuthRequiredMessage(state, serverName)
+      : error instanceof Error ? error.message : String(error);
+    if (!(error instanceof SessionRecoveryAuthRequiredError)) {
+      recordFailure(state, serverName, message);
+      updateStatusBar(state);
+    }
+    return { error: failure(error instanceof SessionRecoveryAuthRequiredError ? "auth_required" : "connect_failed", message) };
+  }
+}
+
 export async function executeCall(
   state: McpExtensionState,
   toolName: string,
@@ -966,396 +992,118 @@ export async function executeCall(
   serverOverride?: string,
   getPiTools?: () => ToolInfo[],
   signal?: AbortSignal,
-  onRawResult?: (result: unknown) => void,
   identity: McpToolCallIdentity = {},
   beforeDispatch?: (signal: AbortSignal | undefined, operation: McpOperationContext) => Promise<void>,
+  options: ExecuteCallOptions = {},
 ): Promise<ProxyToolResult> {
   const ownedSignal = combineAbortSignals(state.owner?.signal, signal);
   throwIfAborted(ownedSignal);
-  let serverName: string | undefined = serverOverride;
-  let toolMeta: ToolMetadata | undefined;
-  let autoAuthAttempted = false;
-  const prefixMode = state.config.settings?.toolPrefix ?? "server";
-  const disabledCallResult = (disabledServer: string, metadata?: ToolMetadata): ProxyToolResult => {
-    if (!metadata) {
-      const message = `Server "${disabledServer}" is disabled. Run /mcp enable ${disabledServer} and /reload to enable it.`;
-      return {
-        content: [{ type: "text" as const, text: message }],
-        details: { mode: "call", error: "server_disabled", server: disabledServer, requestedTool: toolName, message },
-      };
-    }
-    const message = `Server "${disabledServer}" is disabled. Run /mcp enable ${disabledServer} and /reload to enable it.`;
-    const identity = metadata.resourceUri
-      ? { server: disabledServer, resourceUri: metadata.resourceUri }
-      : { server: disabledServer, tool: metadata.originalName };
-    return {
-      content: [{ type: "text" as const, text: message }],
-      details: { mode: "call", error: "server_disabled", ...identity, message },
-    };
+  if (typeof toolName !== "string" || !toolName.trim() || (serverOverride !== undefined && (typeof serverOverride !== "string" || !serverOverride))) return {
+    content: [{ type: "text", text: "Specify a non-empty tool name and, when supplied, server." }],
+    details: { mode: "call", error: "invalid_arguments" },
   };
-
-  if (serverName && !state.config.mcpServers[serverName]) {
-    return {
-      content: [{ type: "text" as const, text: `Server "${serverName}" not found. Use mcp({}) to see available servers.` }],
-      details: { mode: "call", error: "server_not_found", server: serverName, requestedTool: toolName },
-    };
-  }
-  if (serverName) {
-    toolMeta = findToolByName(state.toolMetadata.get(serverName), toolName);
-    if (isServerDisabled(state.config.mcpServers[serverName])) {
-      return disabledCallResult(serverName, toolMeta);
-    }
-  } else {
-    let disabledMatch: { serverName: string; toolMeta: ToolMetadata } | undefined;
-    for (const [server, metadata] of state.toolMetadata.entries()) {
-      const found = findToolByName(metadata, toolName);
-      if (!found) continue;
-      if (isServerDisabled(state.config.mcpServers[server])) {
-        disabledMatch ??= { serverName: server, toolMeta: found };
-        continue;
-      }
-      serverName = server;
-      toolMeta = found;
-      break;
-    }
-    if (!toolMeta && disabledMatch) return disabledCallResult(disabledMatch.serverName, disabledMatch.toolMeta);
-  }
-
-  if (serverName && !toolMeta && !state.toolMetadata.has(serverName)) {
-    const connected = await lazyConnect(state, serverName, ownedSignal);
-    if (connected) {
-      toolMeta = findToolByName(state.toolMetadata.get(serverName), toolName);
-    } else {
-      const needsAuthConnection = state.manager.getConnection(serverName);
-      if (needsAuthConnection?.status === "needs-auth") {
-        if (!autoAuthAttempted) {
-          autoAuthAttempted = true;
-          const autoAuth = await attemptAutoAuth(state, serverName, ownedSignal);
-          if (autoAuth.status === "failed") {
-            return {
-              content: [{ type: "text" as const, text: autoAuth.message }],
-              details: { mode: "call", error: "auth_required", server: serverName, requestedTool: toolName, message: autoAuth.message },
-            };
-          }
-          if (autoAuth.status === "success") {
-            clearFailure(state, serverName);
-            let connectedAfterAuth = false;
-            try {
-              const definition = state.config.mcpServers[serverName];
-              if (definition) {
-                await state.manager.reconnect(serverName, definition, needsAuthConnection, ownedSignal);
-                connectedAfterAuth = true;
-              }
-            } catch (error) {
-              if (isAbortError(error, ownedSignal)) throwIfAborted(ownedSignal);
-              recordFailure(state, serverName, error instanceof Error ? error.message : String(error));
-              updateStatusBar(state);
-            }
-            if (connectedAfterAuth) connectedAfterAuth = await lazyConnect(state, serverName, ownedSignal);
-            if (connectedAfterAuth) {
-              toolMeta = findToolByName(state.toolMetadata.get(serverName), toolName);
-              if (!toolMeta) {
-                const suggestions = rankSuggestions(state, toolName, 5, serverName);
-                const suggestionText = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}` : "";
-                return {
-                  content: [{ type: "text" as const, text: `Tool "${toolName}" not found on "${serverName}" after reconnect.${suggestionText}` }],
-                  details: { mode: "call", error: "tool_not_found_after_reconnect", server: serverName, requestedTool: toolName, suggestions },
-                };
-              }
-            }
-          }
-        }
-
-        if (!toolMeta && state.manager.getConnection(serverName)?.status === "needs-auth") {
-          const message = getAuthRequiredMessage(state, serverName);
-          return {
-            content: [{ type: "text" as const, text: message }],
-            details: { mode: "call", error: "auth_required", server: serverName, requestedTool: toolName, message },
-          };
-        }
-      }
-
-      if (!toolMeta) {
-        const failedAgo = getFailureAgeSeconds(state, serverName);
-        if (failedAgo !== null) {
-          return {
-            content: [{ type: "text" as const, text: `Server "${serverName}" not available (last failed ${failedAgo}s ago)` }],
-            details: { mode: "call", error: "server_backoff", server: serverName, requestedTool: toolName },
-          };
-        }
-      }
+  if (args !== undefined && (args === null || typeof args !== "object" || Array.isArray(args))) return {
+    content: [{ type: "text", text: "Tool arguments must be an object." }],
+    details: { mode: "call", error: "invalid_arguments", requestedTool: toolName },
+  };
+  let serverName = serverOverride;
+  const matches = (metadata: ToolMetadata[] = []) => {
+    if (options.resourceUri !== undefined) return metadata.filter(tool => tool.resourceUri === options.resourceUri);
+    if (options.exactOriginalName) return metadata.filter(tool => tool.originalName === toolName && !tool.resourceUri);
+    if (serverOverride) {
+      const originals = metadata.filter(tool => tool.originalName === toolName);
+      if (originals.length) return originals;
     }
-  }
-
-  let prefixMatchedServer: string | undefined;
-
-  if (!serverName && !toolMeta) {
-    const candidates = Object.keys(state.config.mcpServers)
-      .filter(name => !isServerDisabled(state.config.mcpServers[name]))
-      .map(name => ({
-        name,
-        prefix: getServerPrefix(name, resolveToolPrefix(state.config.mcpServers[name], prefixMode)),
-      }))
-      .filter(c => c.prefix && toolName.startsWith(c.prefix + "_"))
-      .sort((a, b) => b.prefix.length - a.prefix.length)
-      .slice(0, 1);
-
-    for (const { name: configuredServer } of candidates) {
-      const existingConnection = state.manager.getConnection(configuredServer);
-      const failedAgo = getFailureAgeSeconds(state, configuredServer);
-      if (failedAgo !== null && existingConnection?.status !== "needs-auth") continue;
-      if (state.toolMetadata.has(configuredServer)) {
-        prefixMatchedServer ??= configuredServer;
-        continue;
-      }
-
-      let connected = await lazyConnect(state, configuredServer, ownedSignal);
-      const needsAuthConnection = state.manager.getConnection(configuredServer);
-      if (!connected && needsAuthConnection?.status === "needs-auth" && !autoAuthAttempted) {
-        autoAuthAttempted = true;
-        const autoAuth = await attemptAutoAuth(state, configuredServer, ownedSignal);
-        if (autoAuth.status === "failed") {
-          return {
-            content: [{ type: "text" as const, text: autoAuth.message }],
-            details: { mode: "call", error: "auth_required", server: configuredServer, requestedTool: toolName, message: autoAuth.message },
-          };
-        }
-        if (autoAuth.status === "success") {
-          clearFailure(state, configuredServer);
-          try {
-            const definition = state.config.mcpServers[configuredServer];
-            if (definition) {
-              await state.manager.reconnect(configuredServer, definition, needsAuthConnection, ownedSignal);
-              connected = true;
-            }
-          } catch (error) {
-            if (isAbortError(error, ownedSignal)) throwIfAborted(ownedSignal);
-            recordFailure(state, configuredServer, error instanceof Error ? error.message : String(error));
-            updateStatusBar(state);
-          }
-          if (connected) connected = await lazyConnect(state, configuredServer, ownedSignal);
-        }
-      }
-
-      if (!connected) continue;
-      if (!prefixMatchedServer) prefixMatchedServer = configuredServer;
-      toolMeta = findToolByName(state.toolMetadata.get(configuredServer), toolName);
-      if (toolMeta) {
-        serverName = configuredServer;
-        break;
-      }
+    const exact = metadata.filter(tool => tool.name === toolName);
+    if (exact.length) return exact;
+    return metadata.filter(tool => tool.name.replace(/-/g, "_") === toolName.replace(/-/g, "_"));
+  };
+  const ambiguous = (): ProxyToolResult => ({
+    content: [{ type: "text", text: `Tool "${toolName}" is ambiguous. Specify its exact server and tool name; no call was dispatched.` }],
+    details: { mode: "call", error: "ambiguous_tool", requestedTool: toolName, ...(serverName ? { server: serverName } : {}) },
+  });
+  if (!serverName) {
+    const candidates = [...state.toolMetadata].flatMap(([server, metadata]) =>
+      isServerDisabled(state.config.mcpServers[server]) ? [] : matches(metadata).map(tool => ({ server, tool })));
+    if (candidates.length > 1) return ambiguous();
+    serverName = candidates[0]?.server;
+    if (!serverName) {
+      const disabled = [...state.toolMetadata].find(([server, metadata]) => isServerDisabled(state.config.mcpServers[server]) && matches(metadata).length > 0);
+      if (disabled) return disabledResult("call", disabled[0]);
+      const prefixes = Object.entries(state.config.mcpServers)
+        .filter(([, definition]) => !isServerDisabled(definition))
+        .map(([server, definition]) => ({ server, prefix: getServerPrefix(server, resolveToolPrefix(definition, state.config.settings?.toolPrefix ?? "server")) }))
+        .filter(({ prefix }) => prefix && toolName.startsWith(`${prefix}_`))
+        .sort((a, b) => b.prefix.length - a.prefix.length);
+      if (prefixes.length > 1 && prefixes[0]?.prefix === prefixes[1]?.prefix) return ambiguous();
+      serverName = prefixes[0]?.server;
     }
   }
-
-  if (!serverName || !toolMeta) {
-    const nativeTool = !serverOverride
-      ? getPiTools?.().find((tool) => tool.name === toolName && tool.name !== "mcp")
-      : undefined;
-    if (nativeTool) {
-      return {
-        content: [{ type: "text" as const, text: `"${toolName}" is a native Pi tool. Call ${toolName} directly instead of using mcp({ tool: "${toolName}" }).` }],
-        details: { mode: "call", error: "native_tool", requestedTool: toolName },
-      };
-    }
-
-    const hintServer = serverName ?? prefixMatchedServer;
-    const normalizedToolName = toolName.replace(/-/g, "_");
-    const localOriginalName = serverOverride && state.toolMetadata.get(serverOverride)
-      ?.some(tool => tool.originalName.replace(/-/g, "_") === normalizedToolName);
-    const suggestedOwner = serverOverride && !localOriginalName
-      ? [...state.toolMetadata].find(([candidateServer, metadata]) =>
-        candidateServer !== serverOverride
-        && !isServerDisabled(state.config.mcpServers[candidateServer])
-        && findToolByName(metadata, toolName))
-      : undefined;
-    const suggestedTool = suggestedOwner ? findToolByName(suggestedOwner[1], toolName) : undefined;
-    if (suggestedOwner && suggestedTool) {
-      const suggestedServer = suggestedOwner[0];
-      return {
-        content: [{ type: "text" as const, text: `Tool ${JSON.stringify(toolName)} is on server ${JSON.stringify(suggestedServer)}, not ${JSON.stringify(serverOverride)}. Retry the same call with server: ${JSON.stringify(suggestedServer)} or omit server.` }],
-        details: { mode: "call", error: "tool_not_found", requestedTool: toolName, hintServer, suggestedServer, suggestions: [suggestedTool.name] },
-      };
-    }
-
-    const suggestions = rankSuggestions(state, toolName, 5, hintServer);
-    let hint: string;
-    if (suggestions.length > 0) {
-      hint = ` Did you mean: ${suggestions.join(", ")}. Inspect with mcp({ describe: "${suggestions[0]}" }).`;
-    } else if (hintServer) {
-      hint = ` Search with mcp({ search: ${JSON.stringify(toolName)}, server: ${JSON.stringify(hintServer)} }).`;
-    } else {
-      hint = ` Use mcp({ search: "..." }) to search.`;
-    }
-    const suggestionOnHintServer = hintServer && suggestions.some(suggestion =>
-      state.toolMetadata.get(hintServer)?.some(tool => tool.name === suggestion));
-    if (hintServer && (suggestions.length === 0 || suggestionOnHintServer) && state.toolMetadata.has(hintServer) && state.manager.getConnection(hintServer)?.status !== "connected") {
-      hint += ` Refresh a stale catalog with mcp({ connect: ${JSON.stringify(hintServer)} }).`;
-    }
+  const missing = (): ProxyToolResult => {
+    const nativeTool = !serverOverride && getPiTools?.().find(tool => tool.name === toolName && tool.name !== "mcp");
+    if (nativeTool) return {
+      content: [{ type: "text", text: `"${toolName}" is a native Pi tool. Call ${toolName} directly instead of using mcp({ action: "call", tool: "${toolName}" }).` }],
+      details: { mode: "call", error: "native_tool", requestedTool: toolName },
+    };
+    const normalizedName = toolName.replace(/-/g, "_");
+    const localOriginal = serverOverride && state.toolMetadata.get(serverOverride)?.some(tool => tool.originalName.replace(/-/g, "_") === normalizedName);
+    const owners = serverOverride && !localOriginal
+      ? [...state.toolMetadata].filter(([server, metadata]) => server !== serverOverride && !isServerDisabled(state.config.mcpServers[server]) && matches(metadata).length === 1)
+      : [];
+    const suggestedOwner = owners.length === 1 ? owners[0] : undefined;
+    if (suggestedOwner) return {
+      content: [{ type: "text", text: `Tool ${JSON.stringify(toolName)} is on server ${JSON.stringify(suggestedOwner[0])}, not ${JSON.stringify(serverOverride)}. Retry the same call with server: ${JSON.stringify(suggestedOwner[0])} or omit server.` }],
+      details: { mode: "call", error: "tool_not_found", requestedTool: toolName, hintServer: serverName, suggestedServer: suggestedOwner[0], suggestions: matches(suggestedOwner[1]).map(tool => tool.name) },
+    };
+    const suggestions = rankSuggestions(state, toolName, 5, serverName);
+    let hint = suggestions.length
+      ? ` Did you mean: ${suggestions.join(", ")}. Inspect with mcp({ action: "describe", tool: ${JSON.stringify(suggestions[0])} }).`
+      : serverName ? ` Search with mcp({ action: "search", query: ${JSON.stringify(toolName)}, server: ${JSON.stringify(serverName)} }).` : ' Use mcp({ action: "search", query: "..." }) to search.';
+    if (serverName && state.toolMetadata.has(serverName) && state.manager.getConnection(serverName)?.status !== "connected") hint += ` Refresh a stale catalog with mcp({ action: "connect", server: ${JSON.stringify(serverName)} }).`;
     return {
-      content: [{ type: "text" as const, text: `Tool "${toolName}" not found.${hint}` }],
-      details: { mode: "call", error: "tool_not_found", requestedTool: toolName, hintServer, suggestions },
+      content: [{ type: "text", text: `Tool "${toolName}" not found.${hint}` }],
+      details: { mode: "call", error: "tool_not_found", requestedTool: toolName, hintServer: serverName, suggestions },
     };
+  };
+  if (!serverName) return missing();
+  const definition = state.config.mcpServers[serverName];
+  if (!definition) return { content: [{ type: "text", text: `Server "${serverName}" not found. Use mcp({ action: "status" }) to see available servers.` }], details: { mode: "call", error: "server_not_found", server: serverName, requestedTool: toolName } };
+  if (isServerDisabled(definition)) return disabledResult("call", serverName);
+  const cached = state.toolMetadata.get(serverName);
+  if (matches(cached).length > 1) return ambiguous();
+  // Misspellings in a known catalog do not cause connection churn or guessed execution.
+  if (cached && !matches(cached).length && !options.exactOriginalName && options.resourceUri === undefined) return missing();
+
+  const prepared = await prepareMcpConnection(state, serverName, ownedSignal);
+  if (prepared.error) {
+    const cachedTarget = matches(cached)[0];
+    return { ...prepared.error, details: { ...prepared.error.details, ...(cachedTarget
+      ? cachedTarget.resourceUri ? { resourceUri: cachedTarget.resourceUri } : { tool: cachedTarget.originalName }
+      : { requestedTool: toolName }) } };
   }
-
-  const callIdentity = toolMeta.resourceUri
-    ? { server: serverName, resourceUri: toolMeta.resourceUri }
-    : { server: serverName, tool: toolMeta.originalName };
-
-  let connection = state.manager.getConnection(serverName);
-  let refreshAfterAuth = false;
-  if (connection?.status === "needs-auth") {
-    if (!autoAuthAttempted) {
-      autoAuthAttempted = true;
-      const autoAuth = await attemptAutoAuth(state, serverName, ownedSignal);
-      if (autoAuth.status === "failed") {
-        return {
-          content: [{ type: "text" as const, text: autoAuth.message }],
-          details: { mode: "call", error: "auth_required", ...callIdentity, message: autoAuth.message },
-        };
-      }
-      if (autoAuth.status === "success") {
-        clearFailure(state, serverName);
-        refreshAfterAuth = true;
-      }
-    }
-
-    if (connection?.status === "needs-auth" && !refreshAfterAuth) {
-      const message = getAuthRequiredMessage(state, serverName);
-      return {
-        content: [{ type: "text" as const, text: message }],
-        details: { mode: "call", error: "auth_required", ...callIdentity, message },
-      };
-    }
-  }
-  if (!connection || connection.status !== "connected") {
-    const failedAgo = getFailureAgeSeconds(state, serverName);
-    if (failedAgo !== null) {
-      return {
-        content: [{ type: "text" as const, text: `Server "${serverName}" not available (last failed ${failedAgo}s ago)` }],
-        details: { mode: "call", error: "server_backoff", ...callIdentity },
-      };
-    }
-
-    const definition = state.config.mcpServers[serverName];
-    if (!definition) {
-      return {
-        content: [{ type: "text" as const, text: `Server "${serverName}" not connected` }],
-        details: { mode: "call", error: "server_not_connected", ...callIdentity },
-      };
-    }
-
-    try {
-      if (state.ui) {
-        state.ui.setStatus("mcp", formatMcpStatus(state.config, `connecting to ${serverName}...`));
-      }
-      connection = refreshAfterAuth && connection
-        ? await state.manager.reconnect(serverName, definition, connection, ownedSignal)
-        : await state.manager.connect(serverName, definition, ownedSignal);
-      if (connection.status === "needs-auth") {
-        if (!autoAuthAttempted) {
-          autoAuthAttempted = true;
-          const autoAuth = await attemptAutoAuth(state, serverName, ownedSignal);
-          if (autoAuth.status === "failed") {
-            return {
-              content: [{ type: "text" as const, text: autoAuth.message }],
-              details: { mode: "call", error: "auth_required", ...callIdentity, message: autoAuth.message },
-            };
-          }
-          if (autoAuth.status === "success") {
-            connection = await state.manager.reconnect(serverName, definition, connection, ownedSignal);
-          }
-        }
-
-        if (connection.status === "needs-auth") {
-          const message = getAuthRequiredMessage(state, serverName);
-          return {
-            content: [{ type: "text" as const, text: message }],
-            details: { mode: "call", error: "auth_required", ...callIdentity, message },
-          };
-        }
-      }
-      clearFailure(state, serverName);
-      updateServerMetadata(state, serverName);
-      updateMetadataCache(state, serverName);
-      notifyToolMetadataUpdated(state, serverName, "proxy-call-reconnect");
-      markKeepAliveAfterConnect(state, serverName);
-      updateStatusBar(state);
-      toolMeta = findToolByName(state.toolMetadata.get(serverName), toolName);
-      if (!toolMeta) {
-        const suggestions = rankSuggestions(state, toolName, 5, serverName);
-        const hint = suggestions.length > 0
-          ? ` Did you mean: ${suggestions.join(", ")}. Inspect with mcp({ describe: "${suggestions[0]}" }).`
-          : ` Search with mcp({ search: ${JSON.stringify(toolName)}, server: ${JSON.stringify(serverName)} }).`;
-        return {
-          content: [{ type: "text" as const, text: `Tool "${toolName}" not found on "${serverName}" after reconnect.${hint}` }],
-          details: { mode: "call", error: "tool_not_found_after_reconnect", server: serverName, requestedTool: toolName, suggestions },
-        };
-      }
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      if (!isAbortError(error, ownedSignal)) recordFailure(state, serverName, message);
-      updateStatusBar(state);
-      return {
-        content: [{ type: "text" as const, text: `Failed to connect to "${serverName}": ${message}` }],
-        details: { mode: "call", error: isAbortError(error, ownedSignal) ? "aborted" : "connect_failed", ...callIdentity, message },
-      };
-    }
-  }
-
-  if (isServerDisabled(state.config.mcpServers[serverName])) {
-    return disabledCallResult(serverName, toolMeta);
-  }
-
+  const targets = matches(state.toolMetadata.get(serverName));
+  if (targets.length > 1) return ambiguous();
+  const toolMeta = targets[0];
+  if (!toolMeta) return missing();
+  if (isServerDisabled(state.config.mcpServers[serverName])) return disabledResult("call", serverName);
   const approval = await ensureToolCallApproved(state, serverName, toolMeta, args, ownedSignal);
-  if (approval.ok === false) {
+  if (!approval.ok) {
     const denied = approval.reason === "denied";
-    const message = denied
-      ? `The user declined approval to run MCP tool "${toolMeta.originalName}" on server "${serverName}".`
-      : `MCP tool "${toolMeta.originalName}" on server "${serverName}" is approval-gated and requires an interactive session.`;
     return {
-      content: [{ type: "text" as const, text: message }],
-      details: {
-        mode: "call",
-        error: denied ? "approval_denied" : "approval_required",
-        server: serverName,
-        tool: toolMeta.originalName,
-      },
+      content: [{ type: "text", text: denied
+        ? `The user declined approval to run MCP tool "${toolMeta.originalName}" on server "${serverName}".`
+        : `MCP tool "${toolMeta.originalName}" on server "${serverName}" is approval-gated and requires an interactive session.` }],
+      details: { mode: "call", error: denied ? "approval_denied" : "approval_required", server: serverName, tool: toolMeta.originalName },
     };
   }
-
-  const recoverAuthConnection: NonNullable<SessionRecoveryDeps["onNeedsAuth"]> = async (_serverName, recoverySignal = ownedSignal, challenge) => {
-    throwIfAborted(recoverySignal);
-    const current = state.manager.getConnection(serverName);
-    if (current?.status === "connected" && current !== challenge?.connection) return current;
-
-    if (!autoAuthAttempted) {
-      autoAuthAttempted = true;
-      const autoAuth = await attemptAutoAuth(state, serverName, recoverySignal);
-      throwIfAborted(recoverySignal);
-      if (autoAuth.status === "failed") {
-        throw new SessionRecoveryAuthRequiredError(serverName, autoAuth.message);
-      }
-      if (autoAuth.status === "success") {
-        const definition = state.config.mcpServers[serverName];
-        if (!definition) return undefined;
-        if (!current) return undefined;
-        clearFailure(state, serverName);
-        connection = await state.manager.reconnect(serverName, definition, current, recoverySignal);
-        return connection;
-      }
-    }
-    return challenge ? undefined : state.manager.getConnection(serverName);
-  };
-
   return runToolCall(state, serverName, toolMeta, args, {
     ...identity,
     ...(beforeDispatch ? { beforeDispatch } : {}),
-    detailsBase: { mode: "call", ...callIdentity },
-    ownedSignal,
-    signal,
-    recoverAuthConnection,
+    ...(options.raw !== undefined ? { raw: options.raw } : {}),
+    detailsBase: { mode: "call", server: serverName, ...(toolMeta.resourceUri ? { resourceUri: toolMeta.resourceUri } : { tool: toolMeta.originalName }) },
+    ownedSignal, signal,
+    recoverAuthConnection: prepared.recoverAuthConnection!,
     authRequiredMessage: () => getAuthRequiredMessage(state, serverName),
-    autoAuthAttempted: () => autoAuthAttempted,
-    ...(onRawResult ? { onRawResult } : {}),
+    autoAuthAttempted: prepared.autoAuthAttempted!,
   });
 }