@zackbart/connecta 0.7.9 → 0.8.1

package/src/meta-tools.ts

@@ -1,23 +1,38 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { compactSchema, rankTools, summarizeDescription } from "./catalog.js";
-import {
-  recordToolActivity,
-  type ActivityCallSource,
-  type ActivityRequestContext,
+import type {
+  ActivityCallSource,
+  ActivityRequestContext,
 } from "./activity.js";
+import {
+  boundedDiscoveryText,
+  CatalogService,
+  DEFAULT_SEARCH_LIMIT,
+  DiscoveryPolicyError,
+  groupedSearchResult,
+  MAX_DESCRIBE_ADDRESSES,
+  MAX_DISCOVERY_RESULT_BYTES,
+  MAX_SEARCH_LIMIT,
+} from "./catalog-service.js";
+import {
+  mapSettledWithConcurrency,
+  resolveDiscoveryConcurrency,
+} from "./concurrency.js";
 import {
   closeConnectorScope,
   type DeferredWork,
 } from "./connector-scope.js";
-import { unwrapMcpResult } from "./mcp-result.js";
 import {
   classifyCallError,
-  ConnectorCallError,
   messageLooksRetryable,
   type CallErrorDetails,
 } from "./errors.js";
-import { isCallAdmissionError } from "./call-admission.js";
+import {
+  InvocationService,
+  MAX_RETRY_BACKOFF_MS,
+  retryBackoffMs,
+  type InvocationTiming,
+} from "./invocation.js";
 import {
   isValidMaxResultBytes,
   MIN_MAX_RESULT_BYTES,
@@ -25,8 +40,6 @@ import {
   type RegistryView,
 } from "./registry.js";
 import {
-  connectorGuide,
-  connectorSkillName,
   hasConnectorGuides,
   listSkills,
   resolveSkill,
@@ -36,8 +49,15 @@ import {
   normalizeTimeoutMs,
   withAbortableTimeout,
 } from "./timeout.js";
-import { credentialVerdictApplies } from "./credential-health.js";
-import type { ConnectorStatus, KVStorage, ToolDef } from "./types.js";
+import type { ConnectorStatus, KVStorage } from "./types.js";
+
+export {
+  MAX_DESCRIBE_ADDRESSES,
+  MAX_DISCOVERY_RESULT_BYTES,
+  MAX_RETRY_BACKOFF_MS,
+  MAX_SEARCH_LIMIT,
+  retryBackoffMs,
+};
 
 interface TextContent {
   type: "text";
@@ -51,10 +71,12 @@ export interface ToolResult {
 }
 
 const RESULT_TTL_SECONDS = 900;
+const enc = new TextEncoder();
+const dec = new TextDecoder();
 
 export function jsonResult(obj: unknown): ToolResult {
   return {
-    content: [{ type: "text", text: JSON.stringify(obj, null, 2) }],
+    content: [{ type: "text", text: JSON.stringify(obj) }],
     ...(obj !== null && typeof obj === "object" && !Array.isArray(obj)
       ? { structuredContent: obj as Record<string, unknown> }
       : {}),
@@ -69,95 +91,8 @@ function msg(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
-export const DEFAULT_SEARCH_LIMIT = 25;
-/**
- * A discovery page is for choosing the next tool, not exporting the catalog.
- * One hundred leaves room for broad browsing while keeping each deliberate
- * page far below the catalog sizes Connecta supports.
- */
-export const MAX_SEARCH_LIMIT = 100;
-/** Same one-request work bound for address-based discovery. */
-export const MAX_DESCRIBE_ADDRESSES = 100;
-/**
- * Final UTF-8 ceiling for a generated search/describe response. The count
- * limits are the ordinary guard; this catches unusually large full schemas or
- * descriptions that make even a bounded page expensive.
- */
-export const MAX_DISCOVERY_RESULT_BYTES = 256_000;
-const enc = new TextEncoder();
-const dec = new TextDecoder();
-
-type ErrorDetails = CallErrorDetails;
-
-export class DiscoveryPolicyError extends Error {
-  constructor(
-    readonly code: "invalid_args" | "result_too_large",
-    message: string,
-  ) {
-    super(message);
-    this.name = "DiscoveryPolicyError";
-  }
-}
-
-/** Validate before ranking so a huge page request does no proportional work. */
-export function discoverySearchLimit(value: unknown): number {
-  if (value === undefined) return DEFAULT_SEARCH_LIMIT;
-  if (
-    typeof value !== "number" ||
-    !Number.isInteger(value) ||
-    value < 1 ||
-    value > MAX_SEARCH_LIMIT
-  ) {
-    throw new DiscoveryPolicyError(
-      "invalid_args",
-      `limit must be a whole number from 1 through ${MAX_SEARCH_LIMIT}. Page through larger catalogs with offset.`,
-    );
-  }
-  return value;
-}
-
-/** Validate the raw list so duplicate addresses consume the same bound. */
-export function discoveryAddresses(value: unknown): unknown[] {
-  if (!Array.isArray(value)) {
-    throw new DiscoveryPolicyError(
-      "invalid_args",
-      "addresses must be an array.",
-    );
-  }
-  if (value.length > MAX_DESCRIBE_ADDRESSES) {
-    throw new DiscoveryPolicyError(
-      "invalid_args",
-      `addresses must contain at most ${MAX_DESCRIBE_ADDRESSES} entries. Split a larger list across describe_tools calls.`,
-    );
-  }
-  return value;
-}
-
-/** Serialize once and count the exact bytes jsonResult would emit. */
-function boundedDiscoveryText(
-  value: unknown,
-  hint: string,
-): string {
-  const text = JSON.stringify(value, null, 2);
-  if (text === undefined) {
-    throw new TypeError("Discovery result is not JSON-serializable.");
-  }
-  const bytes = enc.encode(text).length;
-  if (bytes > MAX_DISCOVERY_RESULT_BYTES) {
-    throw new DiscoveryPolicyError(
-      "result_too_large",
-      `Discovery result is ${bytes} UTF-8 bytes, over the ${MAX_DISCOVERY_RESULT_BYTES}-byte ceiling. ${hint}`,
-    );
-  }
-  return text;
-}
-
-/** Apply the same final result guard to code-mode discovery helpers. */
-export function assertDiscoveryResultSize(
-  value: unknown,
-  hint: string,
-): void {
-  boundedDiscoveryText(value, hint);
+function errorDetails(code: string, message: string): CallErrorDetails {
+  return { code, message, retryable: messageLooksRetryable(message) };
 }
 
 function discoveryErrorResult(error: DiscoveryPolicyError): ToolResult {
@@ -172,8 +107,12 @@ function discoveryErrorResult(error: DiscoveryPolicyError): ToolResult {
   return result;
 }
 
-function discoveryResult(value: unknown, hint: string): ToolResult {
+async function discoveryResult(
+  operation: () => unknown | Promise<unknown>,
+  hint: string,
+): Promise<ToolResult> {
   try {
+    const value = await operation();
     const text = boundedDiscoveryText(value, hint);
     return {
       content: [{ type: "text", text }],
@@ -189,71 +128,14 @@ function discoveryResult(value: unknown, hint: string): ToolResult {
   }
 }
 
-/**
- * The longest the engine will park a synchronous inbound request in *waiting
- * alone*. The engine already treats ~15 s as the outer bound of one reasonable
- * connector call (EXECUTE_HOST_CALL_TIMEOUT_MS), so sleeping for minutes trades
- * a fast, informative failure for a hung one. A connector-reported window this
- * long isn't truncated — it's declined (see `retryBackoffMs`) and reported
- * verbatim as `error.retryAfterMs`, so the agent, which can afford to wait,
- * decides when to re-issue.
- */
-export const MAX_RETRY_BACKOFF_MS = 10_000;
-
-/**
- * How long to wait before the next attempt, or `undefined` for "don't retry".
- *
- * A connector that read a `Retry-After` header knows the window exactly, so it
- * is honoured **exactly or not at all**: truncating an exponential *guess* is
- * harmless, but truncating a *known* window means deliberately retrying inside
- * a rate limit — the harm this channel exists to prevent. A window longer than
- * `MAX_RETRY_BACKOFF_MS` therefore declines the retry rather than shortening
- * it. (`retryAfterMs` is normalized non-negative, so `0` means "retry now".)
- * Connectors that report no window keep the historical exponential guess.
- *
- * Waits are per attempt, matching the per-attempt `timeoutMs` race in
- * `runCall`. Exported for direct testing.
- */
-export function retryBackoffMs(
-  attempt: number,
-  retryAfterMs: number | undefined,
-): number | undefined {
-  if (retryAfterMs === undefined) {
-    return Math.min(250 * 2 ** (attempt - 1), 1_000);
-  }
-  return retryAfterMs <= MAX_RETRY_BACKOFF_MS ? retryAfterMs : undefined;
-}
-
-/** Details for failures that never reached a connector (no thrown value). */
-function errorDetails(code: string, message: string): ErrorDetails {
-  return { code, message, retryable: messageLooksRetryable(message) };
-}
-
-function callerCancelledDetails(): ErrorDetails {
-  return {
-    code: "cancelled",
-    message: "Tool call was cancelled by the caller.",
-    retryable: false,
-  };
-}
-
-function isCallerCancellation(
-  error: unknown,
-  signal: AbortSignal | undefined,
-): boolean {
-  return (
-    signal?.aborted === true ||
-    (isCallAdmissionError(error) && error.admissionKind === "cancelled")
-  );
-}
 
 /** True if `b` is a UTF-8 continuation byte (0b10xxxxxx). */
-function isContinuationByte(b: number): boolean {
-  return (b & 0xc0) === 0x80;
+function isContinuationByte(b: number | undefined): boolean {
+  return b !== undefined && (b & 0xc0) === 0x80;
 }
 
 /** Smallest accepted `get_result` byte offset. */
-export const MIN_RESULT_OFFSET = 0;
+const MIN_RESULT_OFFSET = 0;
 
 /**
  * The one definition of a usable `get_result` offset: a whole number of bytes
@@ -269,7 +151,7 @@ export const MIN_RESULT_OFFSET = 0;
  * error. An offset past the end of the payload stays legal: it is a whole
  * number of bytes, and it answers with an empty final page.
  */
-export function isValidResultOffset(value: number): boolean {
+function isValidResultOffset(value: number): boolean {
   return Number.isInteger(value) && value >= MIN_RESULT_OFFSET;
 }
 
@@ -333,8 +215,9 @@ export function alignEndToCharBoundary(
 
 /** Resolve a dot-path (segments) against a value; `key[]` maps the tail over an array. */
 function resolvePath(value: unknown, segments: string[]): unknown {
-  if (segments.length === 0) return value;
-  const [seg, ...rest] = segments;
+  const seg = segments[0];
+  if (seg === undefined) return value;
+  const rest = segments.slice(1);
   const isArr = seg.endsWith("[]");
   const key = isArr ? seg.slice(0, -2) : seg;
   let next: unknown = value;
@@ -375,7 +258,7 @@ function applyFieldsToContent(
     } catch {
       return b;
     }
-    return { ...b, text: JSON.stringify(applyFields(parsed, fields), null, 2) };
+    return { ...b, text: JSON.stringify(applyFields(parsed, fields)) };
   });
 }
 
@@ -396,8 +279,8 @@ function applyFieldsToContent(
  * the three give one answer to the same question. A value JSON cannot serialize
  * at all (a BigInt) still throws, as before, and is reported as a failure.
  */
-export function serializeResultText(value: unknown): string {
-  const serialized = JSON.stringify(value, null, 2);
+function serializeResultText(value: unknown): string {
+  const serialized = JSON.stringify(value);
   return serialized === undefined ? String(value) : serialized;
 }
 
@@ -511,7 +394,7 @@ async function guardContent(
 ): Promise<ToolResult> {
   let text: string;
   try {
-    text = JSON.stringify(content, null, 2);
+    text = JSON.stringify(content);
   } catch {
     // A block carrying a BigInt or a cycle cannot be serialized, so it cannot
     // be measured, stashed, or paged either — there is nothing this guard could
@@ -551,7 +434,7 @@ export interface ListArgs {
   /** When false, return cached/observed health without downstream I/O. */
   probe?: boolean;
 }
-export type ResultMode = "mcp" | "value";
+type ResultMode = "mcp" | "value";
 export interface CallArgs {
   address: string;
   args?: Record<string, unknown>;
@@ -573,15 +456,7 @@ export interface GetResultArgs {
   /** Page size in bytes; a whole number >= 1. Defaults to the deployment cap. */
   maxBytes?: number;
 }
-export interface BatchCall {
-  address: string;
-  args?: Record<string, unknown>;
-  fields?: string[];
-  resultMode?: ResultMode;
-  timeoutMs?: number;
-  maxRetries?: number;
-  diagnostics?: boolean;
-}
+export type BatchCall = CallArgs;
 export interface BatchArgs {
   calls: BatchCall[];
   resultMode?: ResultMode;
@@ -616,6 +491,8 @@ export function createMetaTools(
     defaultToolTimeoutMs?: number;
     /** Per-connector deadline for the list/search/describe probe fan-out. Default 30_000. */
     probeTimeoutMs?: number;
+    /** Maximum simultaneous connector discovery operations. Default 4. */
+    discoveryConcurrency?: number;
     activity?: ActivityRequestContext;
     /** Inbound request cancellation shared by direct and batch child calls. */
     requestSignal?: AbortSignal;
@@ -629,10 +506,19 @@ export function createMetaTools(
   const defaultToolTimeoutMs = normalizeTimeoutMs(opts.defaultToolTimeoutMs);
   const probeTimeoutMs =
     normalizeTimeoutMs(opts.probeTimeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS;
+  const discoveryConcurrency = resolveDiscoveryConcurrency(
+    opts.discoveryConcurrency,
+  );
   // createMetaTools() is called once per inbound MCP request. Sharing this
   // identity lets remote connectors reuse one downstream client inside that
   // request without leaking request-bound I/O into the next one.
   const requestScope = {};
+  const catalog = new CatalogService(registry, baseUrl, {
+    requestScope,
+    probeTimeoutMs,
+    concurrency: discoveryConcurrency,
+  });
+  const invocation = new InvocationService(registry, catalog, opts.activity);
   const withProbeDeadline = <T>(
     label: string,
     operation: (options: {
@@ -650,370 +536,120 @@ export function createMetaTools(
     toolResult: ToolResult;
     durationMs: number;
     attempts: number;
-    timing: {
-      catalogMs: number;
-      admissionMs: number;
-      connectorMs: number;
-      backoffMs: number;
-      resultProcessingMs: number;
-      totalMs: number;
-    };
+    timing: InvocationTiming;
     value?: unknown;
-    error?: ErrorDetails;
+    error?: CallErrorDetails;
   }
 
-  /** Shared call path used by call tools and batch_call: safety → fields → size guard. */
+  interface ProcessedCallResult {
+    toolResult: ToolResult;
+    value?: unknown;
+  }
+
+  /** MCP adapter: shared invocation semantics plus MCP-only result shaping. */
   async function runCall(
     call: BatchCall,
     source: ActivityCallSource,
     options: { allowDestructive?: boolean } = {},
   ): Promise<RunCallOutcome> {
-    const started = Date.now();
-    let catalogMs = 0;
-    let admissionMs = 0;
-    let connectorMs = 0;
-    let backoffMs = 0;
-    let resultProcessingMs = 0;
-    let attempts = 0;
-    const timing = () => ({
-      catalogMs,
-      admissionMs,
-      connectorMs,
-      backoffMs,
-      resultProcessingMs,
-      totalMs: Date.now() - started,
-    });
-    const resolved = registry.resolveAddress(call.address);
-    const record = (
-      outcome: "success" | "error" | "timeout" | "cancelled",
-      errorCode?: string,
-    ) => {
-      if (!resolved) return;
-      recordToolActivity(opts.activity, {
-        connectorId: resolved.connector.id,
-        toolName: resolved.toolName,
-        address: `${resolved.connector.id}.${resolved.toolName}`,
-        source,
-        outcome,
-        durationMs: Date.now() - started,
-        attempts,
-        ...(errorCode ? { errorCode } : {}),
-      });
-    };
-    const failed = (error: ErrorDetails): RunCallOutcome => {
-      const durationMs = Date.now() - started;
-      const diagnostics = timing();
-      record(
-        error.code === "timeout"
-          ? "timeout"
-          : error.code === "cancelled"
-            ? "cancelled"
-            : "error",
-        error.code,
-      );
-      return {
-        toolResult:
-          call.resultMode === "value"
-            ? jsonResult({
-                ok: false,
-                error,
-                durationMs,
-                attempts,
-                ...(call.diagnostics ? { timing: diagnostics } : {}),
-              })
-            : errorResult(error.message),
-        durationMs,
-        attempts,
-        timing: diagnostics,
-        error,
-      };
-    };
-    if (!resolved) {
-      return failed(
-        errorDetails("unknown_address", `Unknown address "${call.address}"`),
-      );
-    }
     const results = registry.resultsStorage();
-    // Result-size cap for THIS call: the connector's own override wins, then
-    // the deployment-wide value, then the built-in default (already folded
-    // into `globalCap`). Resolved per call so one batch_call can mix a
-    // tight-capped connector with siblings on the global cap. An override the
-    // registry already warned about at startup is dropped here, so the
-    // connector simply inherits `globalCap`.
-    const cap = resolveMaxResultBytes(
-      resolved.connector.maxResultBytes,
-      globalCap,
-    );
     const fields = call.fields && call.fields.length > 0 ? call.fields : null;
-    // An explicit per-call deadline always wins; the config default only fills
-    // the gap, and stays off entirely when the deployment sets none.
     const timeoutMs = normalizeTimeoutMs(call.timeoutMs) ?? defaultToolTimeoutMs;
-    const maxRetries = Math.min(
-      2,
-      Math.max(0, Math.trunc(call.maxRetries ?? 0)),
-    );
-    const catalogStarted = Date.now();
-    let definition: ToolDef | undefined;
-    try {
-      definition = (
-        await registry.getTools(resolved.connector.id, baseUrl, requestScope)
-      ).find((tool) => tool.name === resolved.toolName);
-    } catch (err) {
-      catalogMs += Date.now() - catalogStarted;
-      if (opts.requestSignal?.aborted) {
-        return failed(callerCancelledDetails());
-      }
-      // A connector whose catalog cannot be fetched is as unusable as one whose
-      // execution fails, so it feeds health accounting the same way the
-      // execution catch below does — otherwise a connector every call_tool
-      // fails against (a revoked downstream grant, say) still reads clean from
-      // the cheap `list_connectors({ probe: false })` signal.
-      //
-      // Recorded HERE rather than inside the registry's catalog fetch on
-      // purpose: `registry` is this connection's VIEW, so a toolkit-scoped
-      // session records into its own log as well as the deployment-wide one,
-      // which `Registry.refreshTools` could not reach. A cache hit that avoids
-      // a live listTools call therefore records nothing either way — it is not
-      // evidence of health, and success stays what it has always been: an
-      // actual downstream call that returned.
-      registry.recordFailure(resolved.connector.id, Date.now() - started, err);
-      // classifyCallError so a typed auth_required thrown while listing tools
-      // (e.g. a revoked downstream OAuth grant) keeps its code.
-      return failed(classifyCallError(err, "catalog_lookup_failed"));
-    }
-    catalogMs += Date.now() - catalogStarted;
-    if (!definition) {
-      return failed(
-        errorDetails(
-          "unknown_tool",
-          `Unknown tool "${resolved.toolName}" on connector "${resolved.connector.id}"`,
-        ),
-      );
-    }
-    const explicitlyReadOnly =
-      definition.annotations?.readOnlyHint === true &&
-      definition.annotations?.destructiveHint !== true;
-    if (!explicitlyReadOnly && !options.allowDestructive) {
-      return failed(
-        errorDetails(
-          "destructive_tool_requires_approval",
-          `Tool "${call.address}" is not explicitly read-only. Invoke it through call_destructive_tool so the MCP host can request explicit approval.`,
-        ),
-      );
-    }
-    const retrySafe =
-      definition.annotations?.readOnlyHint === true ||
-      definition.annotations?.idempotentHint === true;
-
-    let result: unknown;
-    while (true) {
-      attempts++;
-      let permit: Awaited<ReturnType<RegistryView["admitCall"]>> | undefined;
-      const controller =
-        timeoutMs || opts.requestSignal ? new AbortController() : undefined;
-      const forwardAbort = () =>
-        controller?.abort(opts.requestSignal?.reason);
-      if (opts.requestSignal?.aborted) forwardAbort();
-      else {
-        opts.requestSignal?.addEventListener("abort", forwardAbort, {
-          once: true,
-        });
-      }
-      let timer: ReturnType<typeof setTimeout> | undefined;
-      let onAbort: (() => void) | undefined;
-      let attemptFailed = false;
-      let attemptError: unknown;
-      try {
-        const admissionStarted = Date.now();
-        try {
-          permit = await registry.admitCall(resolved.connector.id, {
-            toolName: resolved.toolName,
-            args: call.args ?? {},
-            signal: opts.requestSignal,
-          });
-        } finally {
-          admissionMs += Date.now() - admissionStarted;
-        }
-        const ctx = registry.contextFor(
-          resolved.connector.id,
-          baseUrl,
-          requestScope,
-          { signal: controller?.signal, timeoutMs },
-        );
-        let rejectCancelled!: (reason: unknown) => void;
-        const cancelled = controller
-          ? new Promise<never>((_, reject) => {
-              rejectCancelled = reject;
-            })
-          : undefined;
-        onAbort = () => {
-          rejectCancelled(
-            controller?.signal.reason ??
-              new ConnectorCallError("timeout", "Tool call was cancelled"),
-          );
-        };
-        controller?.signal.addEventListener("abort", onAbort, { once: true });
-        if (controller?.signal.aborted) onAbort();
-        if (controller?.signal.aborted) await cancelled;
-        if (timeoutMs) {
-          timer = setTimeout(() => {
-            controller?.abort(
-              new ConnectorCallError(
-                "timeout",
-                `Tool call timed out after ${timeoutMs}ms`,
-              ),
-            );
-          }, timeoutMs);
-        }
-        const connectorStarted = Date.now();
-        try {
-          const pending = resolved.connector.callTool(
-            resolved.toolName,
-            call.args ?? {},
-            ctx,
-          );
-          result = cancelled
-            ? await Promise.race([pending, cancelled])
-            : await pending;
-        } finally {
-          connectorMs += Date.now() - connectorStarted;
-        }
-        const mcpResult = result as {
-          content?: TextContent[];
-          isError?: boolean;
-        };
-        if (resolved.connector.kind === "mcp" && mcpResult?.isError) {
-          throw new Error(
-            mcpResult.content?.map((block) => block.text).join("") ||
-              "Downstream tool call failed",
+    const outcome = await invocation.invoke<ProcessedCallResult>(
+      call.address,
+      call.args ?? {},
+      {
+        source,
+        ...(options.allowDestructive !== undefined
+          ? { allowDestructive: options.allowDestructive }
+          : {}),
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        ...(call.maxRetries !== undefined
+          ? { maxRetries: call.maxRetries }
+          : {}),
+        ...(opts.requestSignal !== undefined
+          ? { requestSignal: opts.requestSignal }
+          : {}),
+        unwrapResult: call.resultMode === "value",
+        processResult: async (result, resolved) => {
+          // Result-size cap for THIS call: the connector's own override wins,
+          // then the deployment-wide value, then the built-in default (already
+          // folded into `globalCap`). Resolved per call so one batch_call can
+          // mix a tight-capped connector with siblings on the global cap. An
+          // override the registry already warned about at startup is dropped
+          // here, so the connector simply inherits `globalCap`.
+          const cap = resolveMaxResultBytes(
+            resolved.connector.maxResultBytes,
+            globalCap,
           );
-        }
-      } catch (err) {
-        attemptFailed = true;
-        attemptError = err;
-      } finally {
-        if (timer) clearTimeout(timer);
-        if (onAbort) {
-          controller?.signal.removeEventListener("abort", onAbort);
-        }
-        opts.requestSignal?.removeEventListener("abort", forwardAbort);
-        permit?.release();
-      }
-      if (attemptFailed) {
-        const callerCancelled = isCallerCancellation(
-          attemptError,
-          opts.requestSignal,
-        );
-        const details = callerCancelled
-          ? callerCancelledDetails()
-          : classifyCallError(attemptError);
-        if (
-          !callerCancelled &&
-          attempts <= maxRetries &&
-          retrySafe &&
-          details.retryable
-        ) {
-          const wait = retryBackoffMs(attempts, details.retryAfterMs);
-          if (wait !== undefined) {
-            const backoffStarted = Date.now();
-            if (wait > 0) {
-              const completed = await new Promise<boolean>((resolve) => {
-                let settled = false;
-                const finish = (value: boolean) => {
-                  if (settled) return;
-                  settled = true;
-                  clearTimeout(timer);
-                  opts.requestSignal?.removeEventListener("abort", cancel);
-                  resolve(value);
-                };
-                const timer = setTimeout(() => finish(true), wait);
-                const cancel = () => finish(false);
-                opts.requestSignal?.addEventListener("abort", cancel, {
-                  once: true,
-                });
-                if (opts.requestSignal?.aborted) cancel();
-              });
-              backoffMs += Date.now() - backoffStarted;
-              if (!completed) return failed(callerCancelledDetails());
-            } else {
-              backoffMs += Date.now() - backoffStarted;
-            }
-            continue;
+          if (call.resultMode === "value") {
+            let value = fields ? applyFields(result, fields) : result;
+            value = await guardValue(value, results, cap);
+            return {
+              toolResult: jsonResult({ ok: true, data: value }),
+              value,
+            };
           }
-          // The reported window is longer than the engine will park a
-          // synchronous request for. Fall through to failure with
-          // retryAfterMs reported verbatim so the agent can re-issue.
-        }
-        if (!callerCancelled && !isCallAdmissionError(attemptError)) {
-          registry.recordFailure(
-            resolved.connector.id,
-            Date.now() - started,
-            attemptError,
-          );
-        }
-        return failed(details);
-      }
-      break;
-    }
-
-    registry.recordSuccess(resolved.connector.id, Date.now() - started);
-    const processingStarted = Date.now();
-    try {
-      const mr = result as { content?: TextContent[]; isError?: boolean };
-      if (call.resultMode === "value") {
-        let value = unwrapMcpResult(resolved.connector.kind, result);
-        if (fields) value = applyFields(value, fields);
-        value = await guardValue(value, results, cap);
-        resultProcessingMs += Date.now() - processingStarted;
-        const durationMs = Date.now() - started;
-        const diagnostics = timing();
-        record("success");
-        return {
-          toolResult: jsonResult({
-            ok: true,
-            data: value,
-            durationMs,
-            attempts,
-            ...(call.diagnostics ? { timing: diagnostics } : {}),
-          }),
-          durationMs,
-          attempts,
-          timing: diagnostics,
-          value,
-        };
-      }
-      if (resolved.connector.kind === "mcp") {
-        let content = mr?.content ?? [];
-        if (fields) content = applyFieldsToContent(content, fields);
-        const toolResult = await guardContent(content, results, cap);
-        resultProcessingMs += Date.now() - processingStarted;
-        record("success");
-        return {
-          toolResult,
-          durationMs: Date.now() - started,
-          attempts,
-          timing: timing(),
-        };
+          if (resolved.connector.kind === "mcp") {
+            const mcpResult = result as { content?: TextContent[] };
+            let content = mcpResult?.content ?? [];
+            if (fields) content = applyFieldsToContent(content, fields);
+            return { toolResult: await guardContent(content, results, cap) };
+          }
+          const value = fields ? applyFields(result, fields) : result;
+          return {
+            toolResult: await guardText(
+              serializeResultText(value),
+              results,
+              cap,
+            ),
+            value,
+          };
+        },
+      },
+    );
+    if (!outcome.ok) {
+      const failedResult =
+        outcome.error.code === "auth_required" ||
+        call.resultMode === "value"
+          ? jsonResult({
+              ok: false,
+              error: outcome.error,
+              durationMs: outcome.durationMs,
+              attempts: outcome.attempts,
+              ...(call.diagnostics ? { timing: outcome.timing } : {}),
+            })
+          : errorResult(outcome.error.message);
+      if (outcome.error.code === "auth_required") {
+        failedResult.isError = true;
       }
-      const value = fields ? applyFields(result, fields) : result;
-      const toolResult = await guardText(
-        serializeResultText(value),
-        results,
-        cap,
-      );
-      resultProcessingMs += Date.now() - processingStarted;
-      record("success");
       return {
-        toolResult,
-        durationMs: Date.now() - started,
-        attempts,
-        timing: timing(),
-        value,
+        toolResult: failedResult,
+        durationMs: outcome.durationMs,
+        attempts: outcome.attempts,
+        timing: outcome.timing,
+        error: outcome.error,
       };
-    } catch (err) {
-      resultProcessingMs += Date.now() - processingStarted;
-      return failed(errorDetails("result_processing_failed", msg(err)));
     }
+    const valueModeResult =
+      call.resultMode === "value"
+        ? jsonResult({
+            ok: true,
+            data: outcome.value.value,
+            durationMs: outcome.durationMs,
+            attempts: outcome.attempts,
+            ...(call.diagnostics ? { timing: outcome.timing } : {}),
+          })
+        : outcome.value.toolResult;
+    return {
+      toolResult: valueModeResult,
+      durationMs: outcome.durationMs,
+      attempts: outcome.attempts,
+      timing: outcome.timing,
+      ...(Object.prototype.hasOwnProperty.call(outcome.value, "value")
+        ? { value: outcome.value.value }
+        : {}),
+    };
   }
 
   return {
@@ -1044,181 +680,118 @@ export function createMetaTools(
       // call scope. Closing it cannot defeat call_tool/batch/execute_code reuse.
       const connectors = registry.listConnectors();
       const scope = probe ? {} : requestScope;
-      const pending = connectors.map(
-        async (c) => {
-          const statusStarted = Date.now();
-          const observed = registry.healthFor(c.id);
-          const verdict = await registry.credentialHealthFor(c.id);
-          let status:
-            | ConnectorStatus
-            | { state: "ok" | "error" | "unknown"; message?: string };
-          if (probe) {
-            try {
-              status = await withProbeDeadline(
-                `list_connectors probe of "${c.id}"`,
-                (options) =>
-                  registry.statusFor(c.id, baseUrl, scope, options),
-              );
-            } catch (err) {
-              // A probe that outran probeTimeoutMs (or otherwise threw)
-              // degrades this connector to an error status rather than
-              // hanging the whole list_connectors call.
-              status = { state: "error", message: msg(err) };
-            }
-          } else if (
-            verdict &&
-            // Deployment-wide, deliberately, like `hasObservedSuccess` beside
-            // it: a sibling toolkit's successful call proves the shared
-            // credential works, and a verdict retired for one view but not
-            // another would make the same connector read differently per scope
-            // for a reason that has nothing to do with scope.
-            credentialVerdictApplies(verdict, registry.observedSuccessAt(c.id))
-          ) {
-            // The proactive layer (issue #24): a liveness check already found
-            // the stored credential dead, so say so on the cheap path instead of
-            // waiting for an agent's real call to discover it. Only while it is
-            // the freshest evidence — a successful call since then retires it.
-            status = {
-              state: verdict.state,
-              ...(verdict.message ? { message: verdict.message } : {}),
-              ...(verdict.authorizationUrl
-                ? { authorizationUrl: verdict.authorizationUrl }
-                : {}),
-            };
-          } else {
-            // "error" comes from THIS view's own observations — a sibling
-            // toolkit's failure is not this session's experience — while
-            // ok/unknown may lean on the deployment-wide success signal, since
-            // "the connector answers at all" is a fact about the connector.
-            // Unscoped, the two are the same log, so this is unchanged there.
-            const derived =
-              observed?.consecutiveFailures && observed.consecutiveFailures > 0
-                ? ("error" as const)
-                : registry.hasObservedSuccess(c.id) || c.kind === "api"
-                  ? ("ok" as const)
-                  : ("unknown" as const);
-            status = {
-              // A successful liveness check upgrades "unknown" — nothing has
-              // been called yet, but the credential was verified, which is how
-              // re-authorization shows up here as ok rather than as an absence
-              // of evidence. It never DOWNgrades an observed failure: a real
-              // call that failed is stronger evidence than a background check.
-              state:
-                derived === "unknown" && verdict?.state === "ok"
-                  ? ("ok" as const)
-                  : derived,
-              ...(observed?.lastError ? { message: observed.lastError } : {}),
-            };
-          }
-          // Stamped where the observation actually happened — after the status
-          // probe, not before it. A 30-second probe stamped at its start would
-          // report a verdict older than it is, and would lose the race against a
-          // real call that succeeded WHILE it ran (that success must retire the
-          // verdict, and only an honest timestamp says so).
-          const checkedAt = new Date().toISOString();
-          // A live status probe IS a liveness observation of the stored
-          // credential, so it updates the same verdict a background check
-          // writes: the cached read afterwards agrees with what the operator
-          // just saw, and they are not swept again moments later. Recorded from
-          // the STATUS phase only, and only when the connector actually answered
-          // — a catalog refresh below is not a credential check (the sweep never
-          // fetches one), it is already counted in the health log, and letting
-          // its failure land here would spend the freshness budget on it. The
-          // registry ignores this for connectors storing no credential of ours.
-          if (probe && (status.state === "ok" || status.state === "auth_required")) {
-            await registry.recordCredentialHealth(c.id, {
-              state: status.state,
-              checkedAt,
-              ...(status.message ? { message: status.message } : {}),
-              ...("authorizationUrl" in status && status.authorizationUrl
-                ? { authorizationUrl: status.authorizationUrl }
-                : {}),
-            });
+      const inspect = async (c: (typeof connectors)[number]) => {
+        const statusStarted = Date.now();
+        const observed = registry.healthFor(c.id);
+        const drift = await registry.credentialDriftFor(c.id);
+        let status:
+          | ConnectorStatus
+          | { state: "ok" | "error" | "unknown"; message?: string };
+        if (drift) {
+          status = { state: "auth_required", message: drift };
+        } else if (probe) {
+          try {
+            status = await withProbeDeadline(
+              `list_connectors probe of "${c.id}"`,
+              (options) =>
+                registry.statusFor(c.id, baseUrl, scope, options),
+            );
+          } catch (err) {
+            // A probe that outran probeTimeoutMs (or otherwise threw)
+            // degrades this connector to an error status rather than
+            // hanging the whole list_connectors call.
+            status = { state: "error", message: msg(err) };
           }
-          let tools = registry.peekTools(c.id);
-          // An auth_required status may have just started OAuth. A second
-          // listTools probe would overwrite its state/verifier while returning
-          // the first (now stale) authorization URL.
-          if (probe && status.state === "ok") {
-            try {
-              tools = await withProbeDeadline(
-                `list_connectors catalog refresh of "${c.id}"`,
-                (options) =>
-                  registry.refreshTools(c.id, baseUrl, scope, options),
-              );
-              registry.recordSuccess(c.id, Date.now() - statusStarted);
-            } catch (err) {
-              const details = classifyCallError(err);
-              if (details.code === "auth_required") {
-                let authStatus: ConnectorStatus | undefined;
-                try {
-                  authStatus = await withProbeDeadline(
-                    `list_connectors authorization status of "${c.id}"`,
-                    (options) =>
-                      registry.statusFor(c.id, baseUrl, scope, options),
-                  );
-                } catch {
-                  // The typed auth verdict is still authoritative; this second
-                  // read exists only to recover the connector's pending URL.
-                }
-                status =
-                  authStatus?.state === "auth_required"
-                    ? authStatus
-                    : {
-                        state: "auth_required" as const,
-                        message: details.message,
-                      };
-                await registry.recordCredentialHealth(c.id, {
-                  state: "auth_required",
-                  checkedAt,
-                  ...(status.message ? { message: status.message } : {}),
-                  ...("authorizationUrl" in status &&
-                  status.authorizationUrl
-                    ? { authorizationUrl: status.authorizationUrl }
-                    : {}),
-                });
-              } else {
-                status = { state: "error" as const, message: msg(err) };
+        } else {
+          const derived =
+            observed?.consecutiveFailures && observed.consecutiveFailures > 0
+              ? ("error" as const)
+              : registry.hasObservedSuccess(c.id) || c.kind === "api"
+                ? ("ok" as const)
+                : ("unknown" as const);
+          status = {
+            state: derived,
+            ...(observed?.lastError ? { message: observed.lastError } : {}),
+          };
+        }
+        // Stamped after any live probe so the response reports when its
+        // observation completed, not when a potentially slow request began.
+        const checkedAt = new Date().toISOString();
+        let tools = registry.peekTools(c.id);
+        // An auth_required status may have just started OAuth. A second
+        // listTools probe would overwrite its state/verifier while returning
+        // the first (now stale) authorization URL.
+        if (probe && status.state === "ok") {
+          try {
+            tools = await withProbeDeadline(
+              `list_connectors catalog refresh of "${c.id}"`,
+              (options) =>
+                registry.refreshTools(c.id, baseUrl, scope, options),
+            );
+            registry.recordSuccess(c.id, Date.now() - statusStarted);
+          } catch (err) {
+            const details = classifyCallError(err);
+            if (details.code === "auth_required") {
+              let authStatus: ConnectorStatus | undefined;
+              try {
+                authStatus = await withProbeDeadline(
+                  `list_connectors authorization status of "${c.id}"`,
+                  (options) =>
+                    registry.statusFor(c.id, baseUrl, scope, options),
+                );
+              } catch {
+                // The typed auth verdict is still authoritative; this second
+                // read exists only to recover the connector's pending URL.
               }
-              registry.recordFailure(c.id, Date.now() - statusStarted, err);
+              status =
+                authStatus?.state === "auth_required"
+                  ? authStatus
+                  : {
+                      state: "auth_required" as const,
+                      message: details.message,
+                    };
+            } else {
+              status = { state: "error" as const, message: msg(err) };
             }
+            registry.recordFailure(c.id, Date.now() - statusStarted, err);
           }
-          const latencyMs = Date.now() - statusStarted;
-          const latestObserved = registry.healthFor(c.id);
-          const credentialCheck = probe
-            ? await registry.credentialHealthFor(c.id)
-            : verdict;
-          return {
-            id: c.id,
-            ...(c.title ? { title: c.title } : {}),
-            description: c.description,
-            toolCount: tools?.length ?? 0,
-            status: status.state,
-            checkedAt,
-            latencyMs,
-            probe,
-            ...(latestObserved ?? observed ?? {}),
-            ...(credentialCheck ? { credentialCheck } : {}),
-            ...("authorizationUrl" in status && status.authorizationUrl
-              ? { authorizationUrl: status.authorizationUrl }
-              : {}),
-            ...(status.message ? { message: status.message } : {}),
-          };
-        },
+        }
+        const latencyMs = Date.now() - statusStarted;
+        const latestObserved = registry.healthFor(c.id);
+        return {
+          id: c.id,
+          ...(c.title ? { title: c.title } : {}),
+          description: c.description,
+          toolCount: tools?.length ?? 0,
+          status: status.state,
+          checkedAt,
+          latencyMs,
+          probe,
+          ...(latestObserved ?? observed),
+          ...("authorizationUrl" in status &&
+            status.authorizationUrl && {
+              authorizationUrl: status.authorizationUrl,
+            }),
+          ...(status.message && { message: status.message }),
+        };
+      };
+      const settled = await mapSettledWithConcurrency(
+        connectors,
+        discoveryConcurrency,
+        inspect,
       );
-      if (!probe) {
-        return jsonResult({ connectors: await Promise.all(pending) });
+      if (probe) {
+        await mapSettledWithConcurrency(
+          connectors,
+          discoveryConcurrency,
+          (connector) =>
+            closeConnectorScope(
+              connector,
+              registry.contextFor(connector.id, baseUrl, scope),
+              opts.defer,
+            ),
+        );
       }
-      const settled = await Promise.allSettled(pending);
-      await Promise.all(
-        connectors.map((connector) =>
-          closeConnectorScope(
-            connector,
-            registry.contextFor(connector.id, baseUrl, scope),
-            opts.defer,
-          ),
-        ),
-      );
       const out = settled.map((result) => {
         if (result.status === "rejected") throw result.reason;
         return result.value;
@@ -1227,233 +800,16 @@ export function createMetaTools(
     },
 
     async searchTools(args: SearchArgs): Promise<ToolResult> {
-      const q = args.query ?? "";
-      let limit: number;
-      try {
-        limit = discoverySearchLimit(args.limit);
-      } catch (err) {
-        if (err instanceof DiscoveryPolicyError) {
-          return discoveryErrorResult(err);
-        }
-        throw err;
-      }
-      const offset = Math.max(0, Math.trunc(args.offset ?? 0));
-      const conns = args.connector
-        ? [registry.getConnector(args.connector)].filter(
-            (c): c is NonNullable<typeof c> => Boolean(c),
-          )
-        : registry.listConnectors();
-      const matches: Array<{
-        connectorId: string;
-        connectorTitle?: string;
-        connectorDescription?: string;
-        connectorGuideSkill?: string;
-        tool: ToolDef;
-        score: number;
-        order: number;
-      }> = [];
-      const catalogs = await Promise.allSettled(
-        conns.map((c) =>
-          withProbeDeadline(
-            `search_tools probe of "${c.id}"`,
-            (options) =>
-              registry.getTools(c.id, baseUrl, requestScope, options),
-          ),
-        ),
-      );
-      let matchMode: "all" | "partial" = "all";
-      const collectMatches = (mode: "all" | "partial") => {
-        matches.length = 0;
-        let orderBase = 0;
-        catalogs.forEach((catalog, connectorIndex) => {
-          const c = conns[connectorIndex];
-          if (catalog.status === "fulfilled") {
-            for (const ranked of rankTools(catalog.value, q, mode)) {
-              matches.push({
-                connectorId: c.id,
-                connectorTitle: c.title,
-                connectorDescription: c.description,
-                ...(connectorGuide(c)
-                  ? { connectorGuideSkill: connectorSkillName(c.id) }
-                  : {}),
-                tool: ranked.tool,
-                score: ranked.score,
-                order: orderBase + ranked.order,
-              });
-            }
-          }
-          orderBase +=
-            catalog.status === "fulfilled" ? catalog.value.length : 1;
-        });
-      };
-      collectMatches("all");
-      if (q.trim() && matches.length === 0) {
-        matchMode = "partial";
-        collectMatches(matchMode);
-      }
-      matches.sort((a, b) => b.score - a.score || a.order - b.order);
-      const page = matches.slice(offset, offset + limit);
-      const groups: {
-        id: string;
-        title?: string;
-        description?: string;
-        /** Skill name of this connector's usage guide, when it has one. */
-        guide?: string;
-        tools: Array<{
-          name: string;
-          address: string;
-          description?: string;
-          inputSchema?: unknown;
-          outputSchema?: unknown;
-          annotations?: ToolDef["annotations"];
-        }>;
-      }[] = [];
-      const byConnector = new Map<string, (typeof groups)[number]>();
-      for (const match of page) {
-        let group = byConnector.get(match.connectorId);
-        if (!group) {
-          group = {
-            id: match.connectorId,
-            ...(match.connectorTitle ? { title: match.connectorTitle } : {}),
-            description: match.connectorDescription,
-            ...(match.connectorGuideSkill
-              ? { guide: match.connectorGuideSkill }
-              : {}),
-            tools: [],
-          };
-          byConnector.set(match.connectorId, group);
-          groups.push(group);
-        }
-        const schema = match.tool.inputSchema ?? { type: "object" };
-        group.tools.push({
-          name: match.tool.name,
-          address: `${match.connectorId}.${match.tool.name}`,
-          description: summarizeDescription(
-            match.tool.description,
-            args.fullDescriptions === true,
-          ),
-          ...(args.includeSchemas
-            ? {
-                inputSchema:
-                  args.includeSchemas === "json"
-                    ? schema
-                    : compactSchema(schema),
-              }
-            : {}),
-          ...(args.includeSchemas && match.tool.outputSchema
-            ? {
-                outputSchema:
-                  args.includeSchemas === "json"
-                    ? match.tool.outputSchema
-                    : compactSchema(match.tool.outputSchema),
-              }
-            : {}),
-          ...(match.tool.annotations
-            ? { annotations: match.tool.annotations }
-            : {}),
-        });
-      }
-      const nextOffset =
-        offset + page.length < matches.length
-          ? offset + page.length
-          : undefined;
       return discoveryResult(
-        {
-          connectors: groups,
-          total: matches.length,
-          offset,
-          limit,
-          hasMore: nextOffset !== undefined,
-          ...(nextOffset !== undefined ? { nextOffset } : {}),
-          ...(matchMode === "partial" && matches.length > 0
-            ? { matchMode }
-            : {}),
-        },
+        async () =>
+          groupedSearchResult(await catalog.search(args)),
         "Request a smaller limit, omit fullDescriptions, or use compact schemas.",
       );
     },
 
     async describeTools(args: DescribeArgs): Promise<ToolResult> {
-      try {
-        discoveryAddresses(args.addresses);
-      } catch (err) {
-        if (err instanceof DiscoveryPolicyError) {
-          return discoveryErrorResult(err);
-        }
-        throw err;
-      }
-      const format = args.format ?? "compact";
-      const resolved = args.addresses.map((address) => ({
-        address,
-        resolved: registry.resolveAddress(address),
-      }));
-      const connectorIds = [
-        ...new Set(
-          resolved
-            .map((entry) => entry.resolved?.connector.id)
-            .filter((id): id is string => Boolean(id)),
-        ),
-      ];
-      const loaded = await Promise.allSettled(
-        connectorIds.map((id) =>
-          withProbeDeadline(
-            `describe_tools probe of "${id}"`,
-            (options) =>
-              registry.getTools(id, baseUrl, requestScope, options),
-          ),
-        ),
-      );
-      const catalogs = new Map<string, ToolDef[] | Error>();
-      loaded.forEach((result, index) => {
-        catalogs.set(
-          connectorIds[index],
-          result.status === "fulfilled"
-            ? result.value
-            : result.reason instanceof Error
-              ? result.reason
-              : new Error(String(result.reason)),
-        );
-      });
-      const out = resolved.map(({ address, resolved }) => {
-        if (!resolved) {
-          return { address, error: `Unknown address "${address}"` };
-        }
-        const catalog = catalogs.get(resolved.connector.id);
-        if (catalog instanceof Error) {
-          return { address, error: catalog.message };
-        }
-        const tool = catalog?.find((t) => t.name === resolved.toolName);
-        if (!tool) {
-          return {
-            address,
-            error: `Unknown tool "${resolved.toolName}" on connector "${resolved.connector.id}"`,
-          };
-        }
-        const schema = tool.inputSchema ?? { type: "object" };
-        return {
-          address,
-          name: tool.name,
-          description: summarizeDescription(
-            tool.description,
-            args.fullDescriptions === true,
-          ),
-          ...(connectorGuide(resolved.connector)
-            ? { guide: connectorSkillName(resolved.connector.id) }
-            : {}),
-          inputSchema: format === "json" ? schema : compactSchema(schema),
-          ...(tool.outputSchema
-            ? {
-                outputSchema:
-                  format === "json"
-                    ? tool.outputSchema
-                    : compactSchema(tool.outputSchema),
-              }
-            : {}),
-          ...(tool.annotations ? { annotations: tool.annotations } : {}),
-        };
-      });
       return discoveryResult(
-        { tools: out },
+        async () => ({ tools: await catalog.describe(args) }),
         'Split the address list or use format: "compact".',
       );
     },
@@ -1534,17 +890,29 @@ export function createMetaTools(
           runCall(
             {
               ...c,
-              resultMode: c.resultMode ?? args.resultMode,
-              timeoutMs: c.timeoutMs ?? args.timeoutMs,
-              maxRetries: c.maxRetries ?? args.maxRetries,
-              diagnostics: c.diagnostics ?? args.diagnostics,
+              ...((c.resultMode ?? args.resultMode) !== undefined
+                ? { resultMode: c.resultMode ?? args.resultMode }
+                : {}),
+              ...((c.timeoutMs ?? args.timeoutMs) !== undefined
+                ? { timeoutMs: c.timeoutMs ?? args.timeoutMs }
+                : {}),
+              ...((c.maxRetries ?? args.maxRetries) !== undefined
+                ? { maxRetries: c.maxRetries ?? args.maxRetries }
+                : {}),
+              ...((c.diagnostics ?? args.diagnostics) !== undefined
+                ? { diagnostics: c.diagnostics ?? args.diagnostics }
+                : {}),
             },
             "batch_call",
           ),
         ),
       );
       const results = settled.map((s, i) => {
-        const address = args.calls[i].address;
+        const call = args.calls[i];
+        if (!call) {
+          throw new Error("Batch result has no corresponding call");
+        }
+        const { address } = call;
         if (s.status === "rejected") {
           return {
             address,
@@ -1562,19 +930,19 @@ export function createMetaTools(
             errorDetails: r.error,
             durationMs: r.durationMs,
             attempts: r.attempts,
-            ...((args.calls[i].diagnostics ?? args.diagnostics)
+            ...((call.diagnostics ?? args.diagnostics)
               ? { timing: r.timing }
               : {}),
           };
         }
-        if ((args.calls[i].resultMode ?? args.resultMode) === "value") {
+        if ((call.resultMode ?? args.resultMode) === "value") {
           return {
             address,
             ok: true,
             data: r.value,
             durationMs: r.durationMs,
             attempts: r.attempts,
-            ...((args.calls[i].diagnostics ?? args.diagnostics)
+            ...((call.diagnostics ?? args.diagnostics)
               ? { timing: r.timing }
               : {}),
           };
@@ -1585,7 +953,7 @@ export function createMetaTools(
           result: r.toolResult.content,
           durationMs: r.durationMs,
           attempts: r.attempts,
-          ...((args.calls[i].diagnostics ?? args.diagnostics)
+          ...((call.diagnostics ?? args.diagnostics)
             ? { timing: r.timing }
             : {}),
         };
@@ -1629,6 +997,21 @@ export function createMetaTools(
               ...(details.retryAfterMs !== undefined
                 ? { retryAfterMs: details.retryAfterMs }
                 : {}),
+              ...(details.connector !== undefined
+                ? { connector: batchSummaryString(details.connector) }
+                : {}),
+              ...(details.operation !== undefined
+                ? { operation: batchSummaryString(details.operation) }
+                : {}),
+              ...(details.recovery !== undefined
+                ? { recovery: details.recovery }
+                : {}),
+              ...(details.nextAction !== undefined
+                ? { nextAction: details.nextAction }
+                : {}),
+              ...(details.retry !== undefined
+                ? { retry: batchSummaryString(details.retry) }
+                : {}),
             },
           };
         }),
@@ -1643,24 +1026,62 @@ export function createMetaTools(
         return errorResult(`Unknown connector "${args.connector}"`);
       }
       if (!connector.startAuth) {
-        return errorResult(
-          `Connector "${args.connector}" does not use downstream OAuth — its auth is static (headers/none), so there is nothing to authorize.`,
+        if (!connector.credential) {
+          return jsonResult({
+            connector: connector.id,
+            recovery: "unavailable",
+            message:
+              `Connector "${connector.id}" declares neither downstream OAuth ` +
+              "nor an operator-managed credential slot. Update the connector " +
+              "or deployment configuration before retrying.",
+          });
+        }
+        const ctx = registry.contextFor(
+          connector.id,
+          baseUrl,
+          requestScope,
         );
+        if (!ctx.credential) {
+          return jsonResult({
+            connector: connector.id,
+            recovery: "unavailable",
+            message:
+              "Credential storage is not configured. Configure " +
+              "credentials.encryptionKey, redeploy, then call " +
+              "authorize_connector again.",
+          });
+        }
+        const fields = connector.credential.fields?.map((field) => ({
+          name: field.name,
+          guidance: field.description ?? field.label,
+        })) ?? [
+          {
+            name: "value",
+            guidance:
+              connector.credential.description ??
+              connector.credential.label,
+          },
+        ];
+        return jsonResult({
+          connector: connector.id,
+          recovery: "operator_config",
+          credential: {
+            label: connector.credential.label,
+            fields,
+          },
+          operatorUrl: new URL("/credentials", baseUrl).toString(),
+          instructions:
+            "Have the operator open operatorUrl, set and test the credential, " +
+            "then retry the original call. No redeploy is needed. Credential " +
+            "mutation requires a Clerk-authenticated operator.",
+        });
       }
       const ctx = registry.contextFor(connector.id, baseUrl, requestScope);
       try {
-        const status = await connector.startAuth(ctx, { force: args.force });
-        // startAuth just spoke to the downstream about this exact credential, so
-        // its answer replaces any older liveness verdict — including the stale
-        // `auth_required` that sent the agent here, once it reports ok.
-        await registry.recordCredentialHealth(connector.id, {
-          state: status.state,
-          checkedAt: new Date().toISOString(),
-          ...(status.message ? { message: status.message } : {}),
-          ...(status.authorizationUrl
-            ? { authorizationUrl: status.authorizationUrl }
-            : {}),
-        });
+        const status = await connector.startAuth(
+          ctx,
+          args.force !== undefined ? { force: args.force } : {},
+        );
         if (status.state === "auth_required" && !status.authorizationUrl) {
           // auth_required with nothing to open is a dead end for the operator.
           return errorResult(
@@ -1669,6 +1090,7 @@ export function createMetaTools(
         }
         return jsonResult({
           connector: connector.id,
+          recovery: "oauth",
           status: status.state,
           ...(status.authorizationUrl
             ? {
@@ -1692,7 +1114,7 @@ export function createMetaTools(
 
 const LIST_DESC =
   "List connectors with status, cached tool count, and recent real-call health. Use probe=false for a fast inventory; use probe=true (default) only to diagnose live health or authorization.";
-const SEARCH_DESC = `Start here when a tool address is unknown. Exact/name matches rank above description matches; an empty query browses all. Pages contain at most ${MAX_SEARCH_LIMIT} tools. includeSchemas="compact" usually removes the describe_tools round trip.`;
+const SEARCH_DESC = `Start here when a tool address is unknown. Exact/name matches rank above description matches; an empty query browses all. The default page has ${DEFAULT_SEARCH_LIMIT} tools; explicit limit can request up to ${MAX_SEARCH_LIMIT}. includeSchemas="compact" usually removes the describe_tools round trip.`;
 const DESCRIBE_DESC = `Inspect up to ${MAX_DESCRIBE_ADDRESSES} known tool addresses when search_tools did not include a sufficient schema. Returns descriptions, input/output schemas, and behavior annotations; format "compact" is the default.`;
 const CALL_DESC =
   'Use for one tool explicitly annotated readOnlyHint: true. For 2–10 independent read-only calls use batch_call; for dependent steps or data reduction use execute_code when available. Unannotated, write-capable, and destructive tools are refused and require call_destructive_tool. fields selects JSON dot-paths, resultMode "value" unwraps results, timeoutMs sets a deadline, safe maxRetries are annotation-gated, diagnostics adds timing, and large results page through get_result.';
@@ -1703,7 +1125,7 @@ const GET_RESULT_DESC =
 const BATCH_DESC =
   "Use for 2–10 independent tools explicitly annotated readOnlyHint: true. Calls run in parallel with shared request-scoped clients; use execute_code when available instead for dependencies or in-sandbox reduction. Unannotated, write-capable, and destructive tools are refused. Batch timeout, safe retry, result mode, and diagnostics defaults may be overridden per call. An oversized final envelope returns ordered outcome summaries plus a get_result page handle.";
 const AUTHORIZE_DESC =
-  "Use after a connector reports auth_required. Starts downstream OAuth and returns an authorizationUrl for the operator to open. force=true wipes stored credentials first and restarts consent.";
+  "Use after auth_required. Returns an OAuth or operator-credential handoff, or reports required deployment configuration. force=true restarts OAuth only; this tool never accepts credentials.";
 const SKILLS_DESC =
   'List or fetch concise guidance for choosing among Connecta meta-tools. Call skills({ name: "usage" }) once when the routing workflow is unfamiliar; do not refetch it in the same task.';
 
@@ -1713,10 +1135,7 @@ const SKILLS_DESC =
  * so a deployment with no guides gets every base description unchanged rather
  * than paying for text about a feature it does not use.
  *
- * Registration is per connection and reads the connection's own registry view,
- * so under a toolkit these sentences reflect the SCOPED connector set: a scoped
- * session whose connectors carry no guides sees the base descriptions, and
- * never learns from a tool description that guides exist out of scope.
+ * Registration is per connection and reads the configured connector set.
  */
 const GUIDE_NOTES = {
   skills:
@@ -1758,6 +1177,16 @@ const READ_ONLY_LOCAL = {
   openWorldHint: false,
 } as const;
 
+const CALL_INPUT_SCHEMA = {
+  address: z.string(),
+  args: z.record(z.string(), z.unknown()).optional(),
+  fields: z.array(z.string()).optional(),
+  resultMode: z.enum(["mcp", "value"]).optional(),
+  timeoutMs: z.number().int().positive().optional(),
+  maxRetries: z.number().int().min(0).max(2).optional(),
+  diagnostics: z.boolean().optional(),
+};
+
 /** Register the nine meta-tools onto an McpServer instance. */
 export function registerMetaTools(
   server: McpServer,
@@ -1766,17 +1195,27 @@ export function registerMetaTools(
     baseUrl: string;
     defaultToolTimeoutMs?: number;
     probeTimeoutMs?: number;
+    discoveryConcurrency?: number;
     activity?: ActivityRequestContext;
     requestSignal?: AbortSignal;
     defer?: DeferredWork;
   },
 ): void {
   const mt = createMetaTools(registry, ctx.baseUrl, {
-    defaultToolTimeoutMs: ctx.defaultToolTimeoutMs,
-    probeTimeoutMs: ctx.probeTimeoutMs,
-    activity: ctx.activity,
-    requestSignal: ctx.requestSignal,
-    defer: ctx.defer,
+    ...(ctx.defaultToolTimeoutMs !== undefined
+      ? { defaultToolTimeoutMs: ctx.defaultToolTimeoutMs }
+      : {}),
+    ...(ctx.probeTimeoutMs !== undefined
+      ? { probeTimeoutMs: ctx.probeTimeoutMs }
+      : {}),
+    ...(ctx.discoveryConcurrency !== undefined
+      ? { discoveryConcurrency: ctx.discoveryConcurrency }
+      : {}),
+    ...(ctx.activity !== undefined ? { activity: ctx.activity } : {}),
+    ...(ctx.requestSignal !== undefined
+      ? { requestSignal: ctx.requestSignal }
+      : {}),
+    ...(ctx.defer !== undefined ? { defer: ctx.defer } : {}),
   });
 
   server.registerTool(
@@ -1784,12 +1223,7 @@ export function registerMetaTools(
     {
       description: describedFor(registry, SKILLS_DESC, "skills"),
       inputSchema: { name: z.string().optional() },
-      annotations: {
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: false,
-      },
+      annotations: READ_ONLY_LOCAL,
     },
     async (args) => mt.skills(args as SkillArgs),
   );
@@ -1839,15 +1273,7 @@ export function registerMetaTools(
     "call_tool",
     {
       description: CALL_DESC,
-      inputSchema: {
-        address: z.string(),
-        args: z.record(z.string(), z.unknown()).optional(),
-        fields: z.array(z.string()).optional(),
-        resultMode: z.enum(["mcp", "value"]).optional(),
-        timeoutMs: z.number().int().positive().optional(),
-        maxRetries: z.number().int().min(0).max(2).optional(),
-        diagnostics: z.boolean().optional(),
-      },
+      inputSchema: CALL_INPUT_SCHEMA,
       // call_tool admits only tools that are themselves explicitly read-only;
       // anything else is refused and routed to call_destructive_tool.
       annotations: READ_ONLY_REMOTE,
@@ -1859,15 +1285,7 @@ export function registerMetaTools(
     "call_destructive_tool",
     {
       description: CALL_DESTRUCTIVE_DESC,
-      inputSchema: {
-        address: z.string(),
-        args: z.record(z.string(), z.unknown()).optional(),
-        fields: z.array(z.string()).optional(),
-        resultMode: z.enum(["mcp", "value"]).optional(),
-        timeoutMs: z.number().int().positive().optional(),
-        maxRetries: z.number().int().min(0).max(2).optional(),
-        diagnostics: z.boolean().optional(),
-      },
+      inputSchema: CALL_INPUT_SCHEMA,
       annotations: {
         destructiveHint: true,
         readOnlyHint: false,
@@ -1920,17 +1338,7 @@ export function registerMetaTools(
       description: BATCH_DESC,
       inputSchema: {
         calls: z
-          .array(
-            z.object({
-              address: z.string(),
-              args: z.record(z.string(), z.unknown()).optional(),
-              fields: z.array(z.string()).optional(),
-              resultMode: z.enum(["mcp", "value"]).optional(),
-              timeoutMs: z.number().int().positive().optional(),
-              maxRetries: z.number().int().min(0).max(2).optional(),
-              diagnostics: z.boolean().optional(),
-            }),
-          )
+          .array(z.object(CALL_INPUT_SCHEMA))
           .min(1)
           .max(10),
         resultMode: z.enum(["mcp", "value"]).optional(),