pi-mcp-adapter 3.2.0 → 4.0.0

package/init.ts

@@ -12,6 +12,7 @@ import {
   getMetadataCachePath,
   getMissingConfiguredDirectToolServers,
   isServerCacheValid,
+  keepOutputShapes,
   loadMetadataCache,
   reconstructPromptMetadata,
   reconstructToolMetadata,
@@ -43,6 +44,7 @@ import {
   createSessionApprovalWriter,
   restoreSessionApprovalState,
 } from "./session-approvals.ts";
+import { seedObservedOutputs } from "./output-shape.ts";
 export { getFailureAgeSeconds, getFailureMessage } from "./failure-backoff.ts";
 
 const MAX_FAILURE_MESSAGE_CHARS = 8 * 1024;
@@ -339,6 +341,7 @@ export async function initializeMcp(
       if (cachedEntry.instructions) {
         serverInstructions.set(name, cachedEntry.instructions);
       }
+      seedObservedOutputs(state, name, cachedEntry);
     }
   }
 
@@ -603,19 +606,29 @@ export function updateMetadataCache(
 
   const tools = serializeTools(connection.tools);
   let resources = definition.exposeResources === false ? [] : serializeResources(connection.resources);
+  const sessionEntry = state.sessionMetadata?.get(serverName);
+  const cacheScope = connection.toolListHints?.cacheScope;
+  // Metadata from a private listing is tied to that authorization context; it may only fill an entry that is private too.
+  const sessionFallback = sessionEntry?.configHash === configHash && (sessionEntry.cacheScope !== "private" || cacheScope === "private")
+    ? sessionEntry
+    : undefined;
   const prompts = connection.promptDiscoveryFailed
-    ? existingEntry?.configHash === configHash ? existingEntry.prompts : undefined
+    ? sessionFallback
+      ? sessionFallback.prompts
+      : existingEntry?.configHash === configHash && isServerCacheValid(existingEntry, definition)
+        ? existingEntry.prompts
+        : undefined
     : serializePrompts(connection.prompts ?? []);
 
   if (definition.exposeResources !== false && connection.resourceDiscoveryFailed === true) {
-    const sessionEntry = state.sessionMetadata?.get(serverName);
-    if (sessionEntry?.configHash === configHash) {
-      resources = sessionEntry.resources ?? [];
+    if (sessionFallback) {
+      resources = sessionFallback.resources ?? [];
     } else if (existingEntry?.resources?.length && isServerCacheValid(existingEntry, definition)) {
       resources = existingEntry.resources;
     }
   }
 
+  const outputShapes = keepOutputShapes(existingEntry, configHash, tools);
   const entry: ServerCacheEntry = {
     configHash,
     tools,
@@ -623,12 +636,14 @@ export function updateMetadataCache(
     ...(prompts !== undefined ? { prompts } : {}),
     ...(connection.instructions !== undefined ? { instructions: connection.instructions } : {}),
     ...(connection.toolListHints?.ttlMs !== undefined ? { ttlMs: connection.toolListHints.ttlMs } : {}),
-    ...(connection.toolListHints?.cacheScope !== undefined ? { cacheScope: connection.toolListHints.cacheScope } : {}),
+    ...(cacheScope !== undefined ? { cacheScope } : {}),
+    ...(outputShapes !== undefined ? { outputShapes } : {}),
     cachedAt: Date.now(),
   };
 
   (state.sessionMetadata ??= new Map()).set(serverName, entry);
   saveMetadataCache({ version: 1, servers: { [serverName]: entry } });
+  seedObservedOutputs(state, serverName, entry);
 }
 
 export function notifyToolMetadataUpdated(state: McpExtensionState, serverName: string, reason: string): void {

package/jev-client.ts

@@ -2,7 +2,7 @@ import { TypeSafeClient } from "@typesafe-ai/sdk";
 import type { McpExtensionState } from "./state.ts";
 import { isServerDisabled } from "./types.ts";
 import { combineAbortSignals } from "./runtime-owner.ts";
-import { JEV_SDK_PATH, resolveJevCredential, resolveJevEndpoint, type JevCredentialResolution, type ResolvedJevEndpoint } from "./jev-key-store.ts";
+import { JEV_SDK_PATH, OPENROUTER_ORIGIN, resolveJevCredential, resolveJevEndpoint, type JevCredentialResolution, type ResolvedJevEndpoint } from "./jev-key-store.ts";
 import type { JevAnswer, JevBudget, JevEvaluateInput, JevEvaluationData, JevEvaluationEnvelope, JevJson, JevQuestion, ResolvedJevSettings } from "./jev-contracts.ts";
 
 export type { ResolvedJevSettings } from "./jev-contracts.ts";
@@ -15,6 +15,8 @@ const DEFAULTS: ResolvedJevSettings = {
   semanticMinProbability: 0.2,
 };
 const DANGEROUS_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+/** OpenRouter's name for Jev, used there when `settings.jev.model` is not configured. */
+const OPENROUTER_DEFAULT_MODEL = "typesafe/jev-1.13";
 
 type JevSettingsInput = Partial<ResolvedJevSettings>;
 type Host = { endpoint: ResolvedJevEndpoint; client: TypeSafeClient };
@@ -192,8 +194,8 @@ function sameKeys(actual: Record<string, unknown>, expected: string[]): boolean
   return keys.length === expected.length && expected.every(key => Object.hasOwn(actual, key));
 }
 function validateResponse(value: unknown, input: JevEvaluateInput): JevEvaluationData {
+  // Providers may add metadata such as `id`, `provider`, or `usage.cost`; only the fields validated here are kept.
   const response = record(value, "response");
-  exactKeys(response, ["model", "answers", "usage"], "response");
   const answers = record(response.answers, "response answers");
   const questionNames = Object.keys(input.questions);
   if (!sameKeys(answers, questionNames)) throw new Error("Response answer keys do not match questions");
@@ -224,7 +226,6 @@ function validateResponse(value: unknown, input: JevEvaluateInput): JevEvaluatio
   }
   if (typeof response.model !== "string" || response.model.length === 0 || response.model.length > 128) throw new Error("Invalid response model");
   const usage = record(response.usage, "response usage");
-  if (!sameKeys(usage, ["input_tokens", "output_tokens"])) throw new Error("Invalid response usage");
   return { answers: validated, model: response.model, usage: { inputTokens: safeNumber(usage.input_tokens, "input tokens", true), outputTokens: safeNumber(usage.output_tokens, "output tokens", true) } };
 }
 
@@ -291,7 +292,9 @@ export async function evaluateJev(state: McpExtensionState, value: JevEvaluateIn
   const timer = setTimeout(() => { timedOut = true; deadline.abort(new Error("Jev evaluation deadline exceeded")); }, settings.requestTimeoutMs);
   const signal = combineAbortSignals(options.signal, state.owner.signal, deadline.signal);
   try {
-    const request = { state: input.state, questions: input.questions, model: settings.model };
+    const configured = state.config.settings?.jev;
+    const model = resolved.endpoint.origin === OPENROUTER_ORIGIN && (!configured || configured.model === undefined) ? OPENROUTER_DEFAULT_MODEL : settings.model;
+    const request = { state: input.state, questions: input.questions, model };
     const raw = await resolved.client.systemOne(request as Parameters<TypeSafeClient["systemOne"]>[0], { ...(signal ? { signal } : {}), timeout: settings.requestTimeoutMs, retry: { maxRetries: settings.maxRetries } });
     try { return { ok: true, data: validateResponse(raw, input) }; }
     catch { return { ok: false, error: { code: "invalid_response", message: "Jev returned an invalid response." } }; }

package/jev-key-store.ts

@@ -6,6 +6,9 @@ const SYSTEMONE_ENDPOINT_ENV = "SYSTEMONE_ENDPOINT";
 const SYSTEMONE_API_KEY_ENV = "SYSTEMONE_API_KEY";
 /** TypeSafe-issued key: honored only for the default endpoint and never sent anywhere else. */
 const LEGACY_TYPESAFE_API_KEY_ENV = "TYPESAFE_API_KEY";
+/** OpenRouter's general-purpose key: honored only for an OpenRouter endpoint and never sent anywhere else. */
+const OPENROUTER_API_KEY_ENV = "OPENROUTER_API_KEY";
+export const OPENROUTER_ORIGIN = "https://openrouter.ai";
 /** Origin recorded in version 1 credential records. */
 export const TYPESAFE_API_ORIGIN = "https://api.typesafe.ai";
 /** Version 1 credential account, still read for the default endpoint. */
@@ -158,6 +161,10 @@ export function resolveJevCredential(
     try { return { status: "present", source: "environment", apiKey: validateApiKey(env[LEGACY_TYPESAFE_API_KEY_ENV]) }; }
     catch { return { status: "unavailable", message: `${LEGACY_TYPESAFE_API_KEY_ENV} is present but invalid.` }; }
   }
+  if (target.origin === OPENROUTER_ORIGIN && Object.hasOwn(env, OPENROUTER_API_KEY_ENV)) {
+    try { return { status: "present", source: "environment", apiKey: validateApiKey(env[OPENROUTER_API_KEY_ENV]) }; }
+    catch { return { status: "unavailable", message: `${OPENROUTER_API_KEY_ENV} is present but invalid.` }; }
+  }
   let stored: string | undefined;
   try { stored = readStoredKey(secretStore, target); }
   catch (error) {

package/mcp-auth-flow.ts

@@ -8,6 +8,7 @@ import {
   auth as runSdkAuth,
   extractWWWAuthenticateParams,
   LATEST_PROTOCOL_VERSION,
+  RegistrationRejectedError,
   UnauthorizedError,
   validateClientMetadataUrl,
   type AuthOptions,
@@ -443,6 +444,13 @@ function parseOAuthRedirectUri(redirectUri: string): OAuthRedirectTarget {
   }
 }
 
+export function explainRegistrationRejection(error: RegistrationRejectedError, serverUrl: string): Error {
+  const hint = new URL(serverUrl).hostname === "mcp.figma.com"
+    ? "Figma's remote MCP server only accepts approved clients, and Pi isn't approved yet. Use the Figma desktop app's local server instead: run /mcp-adapter setup."
+    : "This server only accepts pre-registered OAuth clients. If the provider gave you a client ID, set oauth.clientId (and oauth.clientSecret if required) for this server."
+  return new Error(`${error.message}. ${hint}`, { cause: error })
+}
+
 /**
  * Start OAuth authentication flow for a server.
  * Returns the authorization URL when browser authorization is required.
@@ -464,6 +472,9 @@ export async function startAuth(
   const signal = combineAbortSignals(runtime.signal, options.signal)
   const generation = runtimeState.generation
   throwIfAborted(signal)
+  const explainRejection = (error: unknown): never => {
+    throw error instanceof RegistrationRejectedError ? explainRegistrationRejection(error, serverUrl) : error
+  }
 
   if (config.grantType === "client_credentials") {
     const storedAuth = await getAuthForUrl(serverName, serverUrl, authStorageOptions)
@@ -486,7 +497,7 @@ export async function startAuth(
       const discovery = applyOAuthConfig(await probeAuthDiscovery(serverUrl, definition, signal), config)
       authority()
       throwIfAborted(signal)
-      const result = await abortable(runSdkAuth(authProvider, { serverUrl, ...discovery, fetchFn }), signal)
+      const result = await abortable(runSdkAuth(authProvider, { serverUrl, ...discovery, fetchFn }).catch(explainRejection), signal)
       authority()
       throwIfAborted(signal)
       if (result !== "AUTHORIZED") {
@@ -580,7 +591,7 @@ export async function startAuth(
     const discovery = applyOAuthConfig(await probeAuthDiscovery(serverUrl, definition, signal), config)
     authority()
     throwIfAborted(signal)
-    const result = await abortable(runSdkAuth(authProvider, { serverUrl, ...discovery, fetchFn }), signal)
+    const result = await abortable(runSdkAuth(authProvider, { serverUrl, ...discovery, fetchFn }).catch(explainRejection), signal)
     authority()
     throwIfAborted(signal)
     if (result === "AUTHORIZED") {

package/mcp-code.ts

@@ -6,19 +6,30 @@ import { guardMcpOutput, guardedMcpDetails, resolveMcpOutputGuardOptions } from
 import { loadMcpScriptWasm, resolveMcpScriptQuickJsUrl } from "./mcp-script-wasm.ts";
 import { evaluateJev, validateJevSettings } from "./jev-client.ts";
 import type { JevErrorCode, JevEvaluateInput, JevEvaluationEnvelope } from "./jev-contracts.ts";
-import { executeCall } from "./proxy-modes.ts";
+import { executeCall, findTools, resolveDescribeTarget, unscopedCallReachesServer } from "./proxy-modes.ts";
 import { combineAbortSignals } from "./runtime-owner.ts";
-import { paginate, rankSuggestions, rankToolMatches } from "./search-ranking.ts";
-import { semanticSearch, type SemanticSearchEvaluator } from "./semantic-search.ts";
-import { isServerInActiveFailureBackoff } from "./failure-backoff.ts";
+import { paginate } from "./search-ranking.ts";
+import type { SemanticSearchEvaluator } from "./semantic-search.ts";
 import type { McpExtensionState } from "./state.ts";
-import { findToolByName, formatSchema, hasSchemaDescriptions } from "./tool-metadata.ts";
+import { formatSchema, hasSchemaDescriptions } from "./tool-metadata.ts";
 import { renderTsShape } from "./ts-shape.ts";
+import { getObservedOutput, renderOutputShape } from "./output-shape.ts";
+import type { ObservedOutput } from "./output-shape.ts";
 import type { ContentBlock } from "./types.ts";
 
 export const DEFAULT_MCP_SCRIPT_TIMEOUT_MS = 30_000;
 const MCP_SCRIPT_INTERMEDIATE_MAX_BYTES = 16 * 1024 * 1024;
 const MCP_SCRIPT_OUTPUT_MAX_BYTES = 16 * 1024 * 1024;
+const SEEN_FIELDS_MAX_CHARS = 8 * 1024;
+const EMPTY_RETURNS = new Set(["[]", "{}", "null", ""]);
+
+// Spelled out from the call because models otherwise read `content` off the { ok, data } envelope.
+// Names the server only when the path alone would not reach this server's tool, e.g. a name two servers share.
+const observedTarget = (state: McpExtensionState, observed: ObservedOutput, path: string, server: string) => {
+  const scope = unscopedCallReachesServer(state, path, server) ? "" : `, { server: ${JSON.stringify(server)} }`;
+  const call = `(await tools.call(${JSON.stringify(path)}, args${scope}))`;
+  return observed.source === "structuredContent" ? `${call}.data.structuredContent` : `JSON.parse(${call}.data.content[0].text)`;
+};
 
 class McpScriptTimeoutError extends Error {
   constructor(timeoutMs: number) {
@@ -28,10 +39,10 @@ class McpScriptTimeoutError extends Error {
 }
 
 type SearchInput = { query?: unknown; server?: unknown; limit?: unknown; offset?: unknown; searchMode?: unknown; regex?: unknown };
-type DescribeInput = { path?: unknown };
+type DescribeInput = { path?: unknown; server?: unknown };
 type WorkerMessage =
   | { type: "emit"; block: unknown }
-  | { type: "call"; id: number; path: string; args?: unknown }
+  | { type: "call"; id: number; path: string; args?: unknown; server?: string }
   | { type: "evaluate"; id: number; input: unknown }
   | { type: "search"; id: number; input?: unknown }
   | { type: "describe"; id: number; input?: unknown }
@@ -87,6 +98,19 @@ function textFromContent(content: ContentBlock[]): string {
     .join("\n");
 }
 
+function resultErrorMessage(result: { content: ContentBlock[]; details: Record<string, unknown> }): string {
+  return typeof result.details.message === "string" ? result.details.message : textFromContent(result.content);
+}
+
+/** Script-usable guidance for scoping errors whose shared text points at mcp(), which scripts cannot call. */
+function scriptScopeMessage(code: string, path: string, server: unknown, retry: string): string | undefined {
+  if (code === "server_not_found") return `Server "${String(server)}" not found. Use the server from a tools.search hit.`;
+  if (code !== "ambiguous_tool") return undefined;
+  return typeof server === "string"
+    ? `Tool "${path}" matches multiple tools on server "${server}". Use an exact path from tools.search({ query: "", server: ${JSON.stringify(server)} }).`
+    : `Tool "${path}" matches multiple servers. Pass the server from tools.search: ${retry}.`;
+}
+
 function abortReasonError(reason: unknown): Error {
   return reason instanceof Error ? reason : new Error(String(reason ?? "MCP request aborted"));
 }
@@ -96,9 +120,13 @@ function parseWorkerMessage(value: unknown): WorkerMessage | null {
   const message = value as Record<string, unknown>;
   if (message.type === "emit" && "block" in message) return { type: "emit", block: message.block };
   if (message.type === "call" && typeof message.id === "number" && typeof message.path === "string") {
-    return "args" in message
-      ? { type: "call", id: message.id, path: message.path, args: message.args }
-      : { type: "call", id: message.id, path: message.path };
+    return {
+      type: "call",
+      id: message.id,
+      path: message.path,
+      ...("args" in message ? { args: message.args } : {}),
+      ...(typeof message.server === "string" ? { server: message.server } : {}),
+    };
   }
   if (message.type === "evaluate" && typeof message.id === "number" && "input" in message) {
     return { type: "evaluate", id: message.id, input: message.input };
@@ -161,18 +189,21 @@ export async function runMcpScript(
   }));
   let callsSnapshot: ScriptOperation[] | undefined;
   let intermediateBytes = 0;
+  // Successful calls by server and path, for listing the result fields they returned when the script fails or finds nothing.
+  const calledTools = new Map<string, { path: string; server: string; tool: string }>();
+  let returnedEmpty = false;
   const reserveIntermediateBytes = (dataJson: string): boolean => {
     const bytes = Buffer.byteLength(dataJson, "utf8");
     if (bytes > MCP_SCRIPT_INTERMEDIATE_MAX_BYTES - intermediateBytes) return false;
     intermediateBytes += bytes;
     return true;
   };
-  const callTool = async (path: string, args?: Record<string, unknown>): Promise<WorkerResultPayload> => {
+  const callTool = async (path: string, args?: Record<string, unknown>, server?: string): Promise<WorkerResultPayload> => {
     // Record before dispatch so calls still in flight at timeout/abort appear in the trace.
     const startedAt = Date.now();
     const index = calls.push({ operation: "call", path, ok: false, error: "incomplete", durationMs: 0, startedAt }) - 1;
     let dataJson: string | undefined;
-    const result = await executeCall(state, path, args, undefined, getPiTools, callSignal, "script", {
+    const result = await executeCall(state, path, args, server, getPiTools, callSignal, "script", {
       onSuccess(data) {
         // Serialize once for both byte accounting and worker transfer, never for display.
         dataJson = JSON.stringify(data);
@@ -187,9 +218,7 @@ export async function runMcpScript(
         : [];
       const message = errorCode === "tool_not_found"
         ? `Tool "${path}" not found. Use await tools.search({ query: "..." }) inside mcpScript.${suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}` : ""}`
-        : typeof details.message === "string"
-          ? details.message
-          : textFromContent(result.content);
+        : scriptScopeMessage(errorCode, path, details.server, "tools.call(path, args, { server })") ?? resultErrorMessage(result);
       calls[index] = { operation: "call", path, ok: false, error: errorCode, durationMs: Date.now() - startedAt, startedAt };
       return {
         envelope: { ok: false, error: { code: errorCode, message } },
@@ -209,6 +238,10 @@ export async function runMcpScript(
     }
     // Rejected responses do not consume budget. This bounds transfer, not upstream allocation.
     calls[index] = { operation: "call", path, ok: true, durationMs: Date.now() - startedAt, startedAt };
+    if (typeof details.server === "string" && typeof details.tool === "string") {
+      const calledPath = typeof details.canonicalTool === "string" ? details.canonicalTool : path;
+      calledTools.set(JSON.stringify([details.server, calledPath]), { path: calledPath, server: details.server, tool: details.tool });
+    }
     return { dataJson };
   };
 
@@ -278,34 +311,27 @@ export async function runMcpScript(
     const index = calls.push({ operation: "search", query, ok: false, error: "incomplete", durationMs: 0, startedAt }) - 1;
     let error: unknown;
     try {
-      if (input?.searchMode !== undefined && input.searchMode !== "lexical" && input.searchMode !== "semantic") {
-        error = "invalid_search_mode";
-        return { items: [], total: 0, hasMore: false, nextOffset: null, error: { code: "invalid_search_mode", message: "Search mode must be lexical or semantic." } };
-      }
-      if (query.trim() === "" && input?.searchMode !== "semantic") {
-        return { items: [], total: 0, hasMore: false, nextOffset: null };
+      const outcome = await findTools(state, {
+        query,
+        regex: input?.regex === true,
+        server: typeof input?.server === "string" ? input.server : undefined,
+        searchMode: input?.searchMode,
+        signal: callSignal,
+        semanticEvaluator: async (semanticState, semanticInput, options) => {
+          const rejected = admitEvaluation(semanticInput);
+          if (rejected) return rejected;
+          const envelope = await (semanticEvaluator ?? evaluateJev)(semanticState, semanticInput, options);
+          return chargeEvaluationTokens(envelope);
+        },
+        observedSources: [...observedSources],
+      });
+      if ("error" in outcome) {
+        error = String(outcome.error.details.error);
+        return { items: [], total: 0, hasMore: false, nextOffset: null, error: { code: error, message: resultErrorMessage(outcome.error) } };
       }
-      const server = typeof input?.server === "string" ? input.server : undefined;
       const limit = typeof input?.limit === "number" ? input.limit : 12;
       const offset = typeof input?.offset === "number" ? input.offset : 0;
-      const searchMode = input?.searchMode === "semantic" ? "semantic" : "lexical";
-      if (searchMode === "semantic" && input?.regex === true) {
-        error = "invalid_search_mode";
-        return { items: [], total: 0, hasMore: false, nextOffset: null, error: { code: "invalid_search_mode", message: "Semantic search cannot be combined with regex search." } };
-      }
-      const semantic = searchMode === "semantic"
-        ? await semanticSearch(state, query, server, callSignal, async (semanticState, semanticInput, options) => {
-            const rejected = admitEvaluation(semanticInput);
-            if (rejected) return rejected;
-            const envelope = await (semanticEvaluator ?? evaluateJev)(semanticState, semanticInput, options);
-            return chargeEvaluationTokens(envelope);
-          }, [...observedSources])
-        : undefined;
-      if (semantic && !semantic.ok) {
-        error = semantic.error.code;
-        return { items: [], total: 0, hasMore: false, nextOffset: null, error: semantic.error };
-      }
-      const page = paginate(semantic?.matches ?? rankToolMatches(state, query, server), offset, limit);
+      const page = paginate(outcome.matches, offset, limit);
       return {
         ...page,
         items: page.items.map(({ server: matchServer, tool, score }) => ({
@@ -315,7 +341,7 @@ export async function runMcpScript(
           ...(tool.description ? { description: tool.description } : {}),
           score,
         })),
-        ...(semantic ? { backend: semantic.backend } : {}),
+        ...(outcome.backend ? { backend: outcome.backend } : {}),
       };
     } catch (caught) {
       error = caught;
@@ -332,35 +358,45 @@ export async function runMcpScript(
     const path = typeof input?.path === "string" ? input.path : "";
     let error: unknown;
     try {
-      for (const [server, metadata] of state.toolMetadata) {
-        if (isServerInActiveFailureBackoff(state, server)) continue;
-        const tool = findToolByName(metadata, path);
-        if (!tool) continue;
-        const inputShape = tool.inputSchema ? renderTsShape(tool.inputSchema) : null;
-        const inputTypeScript = inputShape ?? (tool.inputSchema ? formatSchema(tool.inputSchema) : null);
+      const target = resolveDescribeTarget(state, path, typeof input?.server === "string" ? input.server : undefined);
+      if ("error" in target) {
+        const details = target.error.details;
+        const code = String(details.error);
+        error = code;
         return {
-          path: tool.name,
-          name: tool.originalName,
-          server,
-          ...(tool.description ? { description: tool.description } : {}),
-          ...(inputTypeScript ? { inputTypeScript } : {}),
-          ...(inputShape && hasSchemaDescriptions(tool.inputSchema)
-            ? { inputGuidance: formatSchema(tool.inputSchema) } : {}),
-          ...(tool.outputSchema !== undefined ? {
-            outputSchemaTarget: "data.structuredContent",
-            outputSchema: tool.outputSchema,
-          } : {}),
+          path,
+          error: {
+            code,
+            message: code === "tool_not_found"
+              ? `Tool not found: ${path}`
+              : scriptScopeMessage(code, path, details.server, "tools.describe({ path, server })") ?? resultErrorMessage(target.error),
+            suggestions: Array.isArray(details.suggestions) ? details.suggestions : [],
+          },
         };
       }
-      const suggestions = path ? rankSuggestions(state, path, 5) : [];
-      error = "tool_not_found";
+      const { server, tool } = target;
+      const inputShape = tool.inputSchema ? renderTsShape(tool.inputSchema) : null;
+      const inputTypeScript = inputShape ?? (tool.inputSchema ? formatSchema(tool.inputSchema) : null);
+      const observed = tool.resourceUri ? undefined : getObservedOutput(state, server, tool);
       return {
-        path,
-        error: {
-          code: "tool_not_found",
-          message: `Tool not found: ${path}`,
-          suggestions,
-        },
+        path: tool.name,
+        name: tool.originalName,
+        server,
+        ...(tool.description ? { description: tool.description } : {}),
+        ...(inputTypeScript ? { inputTypeScript } : {}),
+        ...(inputShape && hasSchemaDescriptions(tool.inputSchema)
+          ? { inputGuidance: formatSchema(tool.inputSchema) } : {}),
+        ...(tool.outputSchema !== undefined ? {
+          outputSchemaTarget: "data.structuredContent",
+          outputSchema: tool.outputSchema,
+        } : {}),
+        ...(tool.annotations ? { annotations: tool.annotations } : {}),
+        ...(observed ? {
+          observedOutput: {
+            target: observedTarget(state, observed, tool.name, server),
+            typeScript: renderOutputShape(observed.shape),
+          },
+        } : {}),
       };
     } catch (caught) {
       error = caught;
@@ -447,6 +483,8 @@ export async function runMcpScript(
             rejectOutputBudget();
             return;
           }
+          const returned = message.returnBlock as { type?: unknown; text?: unknown } | undefined;
+          returnedEmpty = returned?.type === "text" && typeof returned.text === "string" && EMPTY_RETURNS.has(returned.text.trim());
           completed = true;
           resolve();
           return;
@@ -460,7 +498,7 @@ export async function runMcpScript(
         void (async () => {
           let payload: WorkerResultPayload;
           if (message.type === "call") {
-            payload = await callTool(message.path, message.args as Record<string, unknown> | undefined);
+            payload = await callTool(message.path, message.args as Record<string, unknown> | undefined, message.server);
           } else if (message.type === "evaluate") {
             payload = await evaluate(message.input);
           } else if (message.type === "search") {
@@ -504,10 +542,30 @@ export async function runMcpScript(
     await worker?.terminate();
   }
 
+  // A script that fails or finds nothing after calling a tool without an output schema usually guessed
+  // the result fields wrong. Listing the fields seen saves a separate turn spent looking at the data.
+  let seenFields: string | undefined;
+  if (errorCode === "timeout" || errorCode === "script_error" || returnedEmpty || output.length === 0) {
+    const sections: string[] = [];
+    let chars = 0;
+    for (const { path, server, tool } of calledTools.values()) {
+      const meta = state.toolMetadata.get(server)?.find(entry => entry.originalName === tool && !entry.resourceUri);
+      const observed = meta && getObservedOutput(state, server, meta);
+      if (!observed) continue;
+      const section = `${observedTarget(state, observed, path, server)} is:\n${renderOutputShape(observed.shape)}`;
+      if (chars + section.length > SEEN_FIELDS_MAX_CHARS) break;
+      chars += section.length;
+      sections.push(section);
+    }
+    if (sections.length > 0) {
+      seenFields = `\n\n[Result fields seen from the tools this script called (names and types only, not a contract):\n${sections.join("\n\n")}]`;
+    }
+  }
+
   // Snapshot before the asynchronous output guard; the terminated worker can no longer emit.
   const guarded = await guardMcpOutput(
     output.length > 0 ? [...output] : [{ type: "text", text: "(no output)" }],
-    resolveMcpOutputGuardOptions(state.config.settings),
+    { ...resolveMcpOutputGuardOptions(state.config.settings), ...(seenFields ? { footer: seenFields } : {}) },
   );
   return {
     content: guarded.content,

package/mcp-output-guard.ts

@@ -14,6 +14,7 @@ import type { ContentBlock, McpSettings } from "./types.ts";
 export const DEFAULT_MCP_OUTPUT_MAX_BYTES = DEFAULT_MAX_BYTES;
 export const DEFAULT_MCP_OUTPUT_MAX_LINES = DEFAULT_MAX_LINES;
 export const DEFAULT_MCP_DETAILS_MAX_BYTES = 16 * 1024;
+const SCRIPT_PIPE_HINT_MIN_BYTES = 8 * 1024;
 
 const CONTENT_SUMMARY_LIMIT = 20;
 const KEY_PREVIEW_LIMIT = 20;
@@ -63,6 +64,8 @@ export interface McpOutputGuardOptions {
   enabled?: boolean;
   prefix?: string;
   suffix?: string;
+  /** Optional guidance appended when it fits the output limits. */
+  footer?: string;
   emptyTextFallback?: string;
   maxBytes?: number;
   maxLines?: number;
@@ -93,6 +96,18 @@ export function resolveMcpOutputGuardOptions(settings?: McpSettings): Pick<McpOu
   };
 }
 
+/**
+ * Models retype large results into the next call's arguments unless told otherwise at the moment
+ * they see the result; the same wording in tool descriptions did not change that.
+ */
+export function scriptPipeHint(scriptTool: boolean | undefined, content: ContentBlock[]): { footer?: string } {
+  if (scriptTool !== true) return {};
+  const bytes = content.reduce((total, block) => total + (block.type === "text" ? byteLength(block.text) : 0), 0);
+  return bytes >= SCRIPT_PIPE_HINT_MIN_BYTES
+    ? { footer: "\n\n[Use mcpScript to pass this result to another MCP call without copying it through the conversation.]" }
+    : {};
+}
+
 /** Spread helper for tool-result details: includes mcpResult/outputGuard only when present. */
 export function guardedMcpDetails(guarded: GuardedMcpOutput): Record<string, unknown> {
   return {
@@ -115,6 +130,7 @@ export async function guardMcpOutput(
   const detailsMaxBytes = options.detailsMaxBytes ?? DEFAULT_MCP_DETAILS_MAX_BYTES;
   const prefix = options.prefix ?? "";
   const suffix = options.suffix ?? "";
+  const footer = options.footer ?? "";
 
   const normalizedContent = withEmptyTextFallback(
     content.length > 0
@@ -125,7 +141,7 @@ export async function guardMcpOutput(
 
   if (options.enabled === false) {
     return {
-      content: addAffixes(normalizedContent, prefix, suffix),
+      content: addAffixes(normalizedContent, prefix, `${suffix}${footer}`),
       ...(options.rawMcpResult !== undefined ? { mcpResult: options.rawMcpResult } : {}),
     };
   }
@@ -136,15 +152,18 @@ export async function guardMcpOutput(
     .map((block) => (block as { text: string }).text)
     .join("\n");
   const composedOutput = `${prefix}${textOutput}${suffix}`;
-  const truncation = truncateHead(composedOutput, { maxBytes, maxLines });
+  const truncation = truncateHead(`${composedOutput}${footer}`, { maxBytes, maxLines });
 
-  let guardedContent: ContentBlock[] = addAffixes(normalizedContent, prefix, suffix);
+  let guardedContent: ContentBlock[] = addAffixes(normalizedContent, prefix, `${suffix}${footer}`);
   let outputGuard: McpOutputGuardDetails | undefined;
 
   if (truncation.truncated) {
     const { path: fullOutputPath, error: writeError } = await saveArtifact("output", composedOutput);
     const initialNotice = formatTruncationNotice(truncation, fullOutputPath, writeError);
-    const previewBudget = reserveBudget(maxBytes, maxLines, initialNotice);
+    // Footers are optional guidance: drop one that would not fit beside the notice rather than exceed the limits.
+    const noticeWithFooter = textStats(`\n\n${initialNotice}${footer}`);
+    const keptFooter = noticeWithFooter.bytes < maxBytes && noticeWithFooter.lines < maxLines ? footer : "";
+    const previewBudget = reserveBudget(maxBytes, maxLines, `${initialNotice}${keptFooter}`);
     const preview = truncateHead(composedOutput, {
       maxBytes: previewBudget.maxBytes,
       maxLines: previewBudget.maxLines,
@@ -154,7 +173,7 @@ export async function guardMcpOutput(
       fullOutputPath,
       writeError,
     );
-    const finalText = `${preview.content}\n\n${notice}`;
+    const finalText = `${preview.content}\n\n${notice}${keptFooter}`;
     const finalStats = textStats(finalText);
 
     guardedContent = [{ type: "text" as const, text: finalText }, ...imageBlocks];

package/mcp-script-worker.mjs

@@ -129,11 +129,15 @@ const PRELUDE_SOURCE = `(function (bridge) {
     get(_target, property) {
       if (property === "search") return (input) => request("search", { input });
       if (property === "describe") return (input) => request("describe", { input });
-      if (property === "call") return (path, args) => {
+      if (property === "call") return (path, args, options) => {
         if (typeof path !== "string" || path.trim() === "") {
           return Promise.resolve({ ok: false, error: { code: "invalid_tool_path", message: "tools.call(path, args) requires a non-empty tool path." } });
         }
-        return request("call", { path, args });
+        const server = options?.server;
+        if (server !== undefined && (typeof server !== "string" || server.trim() === "")) {
+          return Promise.resolve({ ok: false, error: { code: "invalid_tool_server", message: "tools.call(path, args, { server }) requires a non-empty server name." } });
+        }
+        return request("call", server === undefined ? { path, args } : { path, args, server });
       };
       if (typeof property !== "string" || reserved.has(property)) return undefined;
       return (args) => request("call", { path: property, args });