@zackbart/connecta 0.7.9 → 0.8.1

package/dist/meta-tools.js

@@ -1,18 +1,19 @@
 import { z } from "zod";
-import { compactSchema, rankTools, summarizeDescription } from "./catalog.js";
-import { recordToolActivity, } 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, } from "./connector-scope.js";
-import { unwrapMcpResult } from "./mcp-result.js";
-import { classifyCallError, ConnectorCallError, messageLooksRetryable, } from "./errors.js";
-import { isCallAdmissionError } from "./call-admission.js";
+import { classifyCallError, messageLooksRetryable, } from "./errors.js";
+import { InvocationService, MAX_RETRY_BACKOFF_MS, retryBackoffMs, } from "./invocation.js";
 import { isValidMaxResultBytes, MIN_MAX_RESULT_BYTES, resolveMaxResultBytes, } from "./registry.js";
-import { connectorGuide, connectorSkillName, hasConnectorGuides, listSkills, resolveSkill, } from "./skills.js";
+import { hasConnectorGuides, listSkills, resolveSkill, } from "./skills.js";
 import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs, withAbortableTimeout, } from "./timeout.js";
-import { credentialVerdictApplies } from "./credential-health.js";
+export { MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_RETRY_BACKOFF_MS, MAX_SEARCH_LIMIT, retryBackoffMs, };
 const RESULT_TTL_SECONDS = 900;
+const enc = new TextEncoder();
+const dec = new TextDecoder();
 export function jsonResult(obj) {
     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 }
             : {}),
@@ -24,68 +25,8 @@ export function errorResult(message) {
 function msg(err) {
     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();
-export class DiscoveryPolicyError extends Error {
-    code;
-    constructor(code, message) {
-        super(message);
-        this.code = code;
-        this.name = "DiscoveryPolicyError";
-    }
-}
-/** Validate before ranking so a huge page request does no proportional work. */
-export function discoverySearchLimit(value) {
-    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) {
-    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, hint) {
-    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, hint) {
-    boundedDiscoveryText(value, hint);
+function errorDetails(code, message) {
+    return { code, message, retryable: messageLooksRetryable(message) };
 }
 function discoveryErrorResult(error) {
     const result = jsonResult({
@@ -98,8 +39,9 @@ function discoveryErrorResult(error) {
     result.isError = true;
     return result;
 }
-function discoveryResult(value, hint) {
+async function discoveryResult(operation, hint) {
     try {
+        const value = await operation();
         const text = boundedDiscoveryText(value, hint);
         return {
             content: [{ type: "text", text }],
@@ -115,57 +57,12 @@ function discoveryResult(value, hint) {
         throw err;
     }
 }
-/**
- * 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, retryAfterMs) {
-    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, message) {
-    return { code, message, retryable: messageLooksRetryable(message) };
-}
-function callerCancelledDetails() {
-    return {
-        code: "cancelled",
-        message: "Tool call was cancelled by the caller.",
-        retryable: false,
-    };
-}
-function isCallerCancellation(error, signal) {
-    return (signal?.aborted === true ||
-        (isCallAdmissionError(error) && error.admissionKind === "cancelled"));
-}
 /** True if `b` is a UTF-8 continuation byte (0b10xxxxxx). */
 function isContinuationByte(b) {
-    return (b & 0xc0) === 0x80;
+    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
  * at or past {@link MIN_RESULT_OFFSET}. Shared by the registered zod schema and
@@ -180,7 +77,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) {
+function isValidResultOffset(value) {
     return Number.isInteger(value) && value >= MIN_RESULT_OFFSET;
 }
 /**
@@ -236,9 +133,10 @@ export function alignEndToCharBoundary(bytes, offset, end, total) {
 // --- fields selection (feature 2) -----------------------------------------
 /** Resolve a dot-path (segments) against a value; `key[]` maps the tail over an array. */
 function resolvePath(value, segments) {
-    if (segments.length === 0)
+    const seg = segments[0];
+    if (seg === undefined)
         return value;
-    const [seg, ...rest] = segments;
+    const rest = segments.slice(1);
     const isArr = seg.endsWith("[]");
     const key = isArr ? seg.slice(0, -2) : seg;
     let next = value;
@@ -276,7 +174,7 @@ function applyFieldsToContent(content, fields) {
         catch {
             return b;
         }
-        return { ...b, text: JSON.stringify(applyFields(parsed, fields), null, 2) };
+        return { ...b, text: JSON.stringify(applyFields(parsed, fields)) };
     });
 }
 // --- result-size guard + get_result (feature 1) ---------------------------
@@ -295,8 +193,8 @@ function applyFieldsToContent(content, fields) {
  * 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) {
-    const serialized = JSON.stringify(value, null, 2);
+function serializeResultText(value) {
+    const serialized = JSON.stringify(value);
     return serialized === undefined ? String(value) : serialized;
 }
 /**
@@ -377,7 +275,7 @@ async function guardValue(value, results, cap) {
 async function guardContent(content, results, cap) {
     let text;
     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
@@ -414,309 +312,106 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
     const batchCap = registry.maxBatchResultBytes;
     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 = (label, operation) => withAbortableTimeout((signal) => operation({ signal, timeoutMs: probeTimeoutMs }), probeTimeoutMs, label);
-    /** Shared call path used by call tools and batch_call: safety → fields → size guard. */
+    /** MCP adapter: shared invocation semantics plus MCP-only result shaping. */
     async function runCall(call, source, options = {}) {
-        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, errorCode) => {
-            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) => {
-            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;
-        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;
-        while (true) {
-            attempts++;
-            let permit;
-            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;
-            let onAbort;
-            let attemptFailed = false;
-            let attemptError;
-            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;
-                const cancelled = controller
-                    ? new Promise((_, 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;
-                if (resolved.connector.kind === "mcp" && mcpResult?.isError) {
-                    throw new Error(mcpResult.content?.map((block) => block.text).join("") ||
-                        "Downstream tool call failed");
-                }
-            }
-            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((resolve) => {
-                                let settled = false;
-                                const finish = (value) => {
-                                    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;
-                    }
-                    // 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.
+        const outcome = await invocation.invoke(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);
+                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,
+                    };
                 }
-                if (!callerCancelled && !isCallAdmissionError(attemptError)) {
-                    registry.recordFailure(resolved.connector.id, Date.now() - started, attemptError);
+                if (resolved.connector.kind === "mcp") {
+                    const mcpResult = result;
+                    let content = mcpResult?.content ?? [];
+                    if (fields)
+                        content = applyFieldsToContent(content, fields);
+                    return { toolResult: await guardContent(content, results, cap) };
                 }
-                return failed(details);
-            }
-            break;
-        }
-        registry.recordSuccess(resolved.connector.id, Date.now() - started);
-        const processingStarted = Date.now();
-        try {
-            const mr = result;
-            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");
+                const value = fields ? applyFields(result, fields) : result;
                 return {
-                    toolResult: jsonResult({
-                        ok: true,
-                        data: value,
-                        durationMs,
-                        attempts,
-                        ...(call.diagnostics ? { timing: diagnostics } : {}),
-                    }),
-                    durationMs,
-                    attempts,
-                    timing: diagnostics,
+                    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;
             }
-            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(),
-                };
-            }
-            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 {
         async skills(args = {}) {
@@ -745,12 +440,15 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
             // 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 inspect = async (c) => {
                 const statusStarted = Date.now();
                 const observed = registry.healthFor(c.id);
-                const verdict = await registry.credentialHealthFor(c.id);
+                const drift = await registry.credentialDriftFor(c.id);
                 let status;
-                if (probe) {
+                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));
                     }
@@ -761,73 +459,20 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                         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"
                         : registry.hasObservedSuccess(c.id) || c.kind === "api"
                             ? "ok"
                             : "unknown";
                     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"
-                            : derived,
+                        state: 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).
+                // 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();
-                // 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 }
-                            : {}),
-                    });
-                }
                 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
@@ -855,15 +500,6 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                                         state: "auth_required",
                                         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", message: msg(err) };
@@ -873,9 +509,6 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                 }
                 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 } : {}),
@@ -885,19 +518,18 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                     checkedAt,
                     latencyMs,
                     probe,
-                    ...(latestObserved ?? observed ?? {}),
-                    ...(credentialCheck ? { credentialCheck } : {}),
-                    ...("authorizationUrl" in status && status.authorizationUrl
-                        ? { authorizationUrl: status.authorizationUrl }
-                        : {}),
-                    ...(status.message ? { message: status.message } : {}),
+                    ...(latestObserved ?? observed),
+                    ...("authorizationUrl" in status &&
+                        status.authorizationUrl && {
+                        authorizationUrl: status.authorizationUrl,
+                    }),
+                    ...(status.message && { message: status.message }),
                 };
-            });
-            if (!probe) {
-                return jsonResult({ connectors: await Promise.all(pending) });
+            };
+            const settled = await mapSettledWithConcurrency(connectors, discoveryConcurrency, inspect);
+            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;
@@ -906,175 +538,10 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
             return jsonResult({ connectors: out });
         },
         async searchTools(args) {
-            const q = args.query ?? "";
-            let limit;
-            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) => Boolean(c))
-                : registry.listConnectors();
-            const matches = [];
-            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";
-            const collectMatches = (mode) => {
-                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 = [];
-            const byConnector = new Map();
-            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 }
-                    : {}),
-            }, "Request a smaller limit, omit fullDescriptions, or use compact schemas.");
+            return discoveryResult(async () => groupedSearchResult(await catalog.search(args)), "Request a smaller limit, omit fullDescriptions, or use compact schemas.");
         },
         async describeTools(args) {
-            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) => 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();
-            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 }, 'Split the address list or use format: "compact".');
+            return discoveryResult(async () => ({ tools: await catalog.describe(args) }), 'Split the address list or use format: "compact".');
         },
         async callTool(args) {
             return (await runCall(args, "call_tool")).toolResult;
@@ -1133,13 +600,25 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
             const batchStarted = Date.now();
             const settled = await Promise.allSettled(args.calls.map((c) => 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,
@@ -1157,19 +636,19 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                         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 }
                             : {}),
                     };
@@ -1180,7 +659,7 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                     result: r.toolResult.content,
                     durationMs: r.durationMs,
                     attempts: r.attempts,
-                    ...((args.calls[i].diagnostics ?? args.diagnostics)
+                    ...((call.diagnostics ?? args.diagnostics)
                         ? { timing: r.timing }
                         : {}),
                 };
@@ -1220,6 +699,21 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                             ...(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) }
+                                : {}),
                         },
                     };
                 }),
@@ -1233,28 +727,58 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                 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(`Connector "${connector.id}": authorization required but no URL is available — retry authorize_connector.`);
                 }
                 return jsonResult({
                     connector: connector.id,
+                    recovery: "oauth",
                     status: status.state,
                     ...(status.authorizationUrl
                         ? {
@@ -1277,13 +801,13 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
     };
 }
 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.';
 const CALL_DESTRUCTIVE_DESC = "Invoke any tool that is not explicitly annotated readOnlyHint: true, including unannotated, write-capable, or destructive tools. The MCP destructiveHint on this meta-tool lets the host request human approval before execution. Use only after reviewing the downstream tool schema and consequences.";
 const GET_RESULT_DESC = "Page a truncated result stashed by call_tool/batch_call. Input { id, offset?, maxBytes? } → { text, offset, nextOffset?, totalBytes } sliced by byte offset. maxBytes is a whole number of bytes >= 1 (omit for the deployment default) and offset a whole number of bytes >= 0; an offset inside a multi-byte character is moved back to that character's first byte and the offset served is returned. Unknown/expired id is an error.";
 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.";
+const AUTHORIZE_DESC = "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.';
 /**
  * Sentences appended to a meta-tool description only when this connection
@@ -1291,10 +815,7 @@ const SKILLS_DESC = 'List or fetch concise guidance for choosing among Connecta
  * 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: ' skills({}) also lists this deployment\'s per-connector usage guides as "connector:<connectorId>"; fetch the guide for a connector before working with it for the first time.',
@@ -1325,24 +846,37 @@ const READ_ONLY_LOCAL = {
     idempotentHint: true,
     openWorldHint: false,
 };
+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, registry, ctx) {
     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("skills", {
         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));
     server.registerTool("list_connectors", {
         description: LIST_DESC,
@@ -1372,30 +906,14 @@ export function registerMetaTools(server, registry, ctx) {
     }, async (args) => mt.describeTools(args));
     server.registerTool("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,
     }, async (args) => mt.callTool(args));
     server.registerTool("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,
@@ -1433,15 +951,7 @@ export function registerMetaTools(server, registry, ctx) {
         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(),