@zackbart/connecta 0.6.1 → 0.7.1

package/src/index.ts

@@ -28,6 +28,84 @@ import type {
   Logger,
 } from "./types.js";
 
+/** Payload-free activity storage and operator-read policy. */
+export interface ConnectaActivityConfig {
+  /**
+   * Privacy-minimal downstream tool activity storage. Writes are best-effort
+   * and never change tool results. Implement `list` to enable the Activity UI.
+   */
+  store: ActivityStore;
+  /**
+   * Optional authorization gate for the Activity read API. MCP authentication
+   * is still required first. Omit to admit every authenticated actor.
+   */
+  readGate?: ActivityReadGate;
+  /** Stable deployment label included in activity events, e.g. "production". */
+  deploymentId?: string;
+}
+
+/** Operator-vault encryption and proactive credential-health tuning. */
+export interface ConnectaCredentialsConfig {
+  /**
+   * Base64-encoded 32-byte AES key for credentials managed on /credentials.
+   * Keep this in the runtime's secret store, never in KV or source control.
+   */
+  encryptionKey?: string;
+  /**
+   * Tuning for proactive credential liveness checks that let a connector's
+   * status flip to `auth_required` before an agent's call fails. Defaults: one
+   * check per connector per 15 minutes, four in flight, 30 seconds each,
+   * triggered opportunistically by inbound authenticated traffic.
+   *
+   * Optional even without an encryption key because downstream OAuth connectors
+   * manage their own grants. `Connecta.checkCredentials()` runs the same checks
+   * on demand for a Worker cron trigger or Node interval.
+   */
+  health?: CredentialHealthConfig;
+}
+
+/** Tool-catalog caching, persistence, stale fallback, and probe deadlines. */
+export interface ConnectaDiscoveryConfig {
+  /** Tool-list cache TTL (seconds). Default 300. */
+  catalogTtlSeconds?: number;
+  /**
+   * Persist serializable remote tool catalogs in storage so cold isolates can
+   * discover tools without a downstream handshake. Default true.
+   */
+  persistCatalog?: boolean;
+  /**
+   * How long an expired persisted catalog remains available as a fallback
+   * when a live refresh fails. Default 3600 seconds.
+   */
+  staleCatalogSeconds?: number;
+  /**
+   * Deadline (ms) for each downstream probe/catalog call fanned out by
+   * `list_connectors`, `search_tools`, and `describe_tools`. Defaults to
+   * 30_000. A timed-out connector degrades independently; this does not apply
+   * to tool calls or currently abort the underlying fetch.
+   */
+  probeTimeoutMs?: number;
+}
+
+/** Deployment-wide call deadlines and inline-result paging threshold. */
+export interface ConnectaCallsConfig {
+  /**
+   * Deadline (ms) for `call_tool`/`batch_call` calls that pass no `timeoutMs`.
+   * An explicit per-call value wins. Opt-in: unset by default, so existing
+   * long-running calls gain no surprise deadline.
+   *
+   * This bounds one attempt, not all retries. `execute_code` host calls are
+   * unaffected because they already carry their own bound.
+   */
+  defaultTimeoutMs?: number;
+  /**
+   * Max inline result size (bytes) before truncation and `get_result` paging.
+   * Must be a finite whole number >= 1; invalid values warn and fall back to
+   * 50_000. Connectors may override it individually.
+   */
+  maxResultBytes?: number;
+}
+
 export interface ConnectaConfig {
   connectors: Connector[];
   /**
@@ -62,18 +140,6 @@ export interface ConnectaConfig {
    * address, or an address naming no tool on an in-code connector all throw.
    */
   toolkits?: ToolkitConfig;
-  /**
-   * Privacy-minimal downstream tool activity storage. Writes are best-effort
-   * and never change tool results. Implement `list` to enable the Activity UI.
-   */
-  activity?: ActivityStore;
-  /**
-   * Optional authorization gate for the Activity read API. MCP authentication
-   * is still required first. Omit to admit every authenticated actor.
-   */
-  activityReadGate?: ActivityReadGate;
-  /** Stable deployment label included in activity events, e.g. "production". */
-  activityDeploymentId?: string;
   /** Inbound auth adapters. Includes bearerToken(...); omit for open (dev). */
   auth?: InboundAuth | InboundAuth[];
   /** KVStorage impl. Defaults to memoryStorage(). */
@@ -83,78 +149,17 @@ export interface ConnectaConfig {
    * HTTPS URL also redirects matching inbound HTTP requests to HTTPS.
    */
   publicUrl?: string;
-  /**
-   * Base64-encoded 32-byte AES key for connector credentials managed in /ui.
-   * Keep this in the runtime's secret store, never in KV or source control.
-   */
-  credentialEncryptionKey?: string;
+  /** Payload-free tool activity storage and operator-read policy. */
+  activity?: ConnectaActivityConfig;
+  /** Operator credential vault and proactive liveness-check settings. */
+  credentials?: ConnectaCredentialsConfig;
+  /** Tool-catalog caching, persistence, stale fallback, and probe deadlines. */
+  discovery?: ConnectaDiscoveryConfig;
+  /** Deployment-wide call deadlines and result paging threshold. */
+  calls?: ConnectaCallsConfig;
   /** Optional browser UI and OAuth result-page labels. */
   branding?: ConnectaBranding;
   logger?: Logger;
-  /** Tool-list cache TTL (seconds). Default 300. */
-  toolCacheTtlSeconds?: number;
-  /**
-   * Persist serializable remote tool catalogs in storage so cold isolates can
-   * discover tools without a downstream handshake. Default true.
-   */
-  persistToolCatalog?: boolean;
-  /**
-   * How long an expired persisted catalog remains available as a fallback
-   * when a live refresh fails. Default 3600 seconds.
-   */
-  toolCatalogStaleSeconds?: number;
-  /**
-   * Max inline result size (bytes) before call_tool/batch_call truncate and
-   * stash the full text for get_result paging. Must be a whole number of bytes
-   * >= 1; anything else (0, negative, fractional, NaN, Infinity) warns at
-   * startup and falls back to the default 50_000.
-   */
-  maxResultBytes?: number;
-  /**
-   * Deadline (ms) applied to call_tool/batch_call calls that pass no
-   * `timeoutMs`, giving the connector both a budget (`ctx.timeoutMs`) and a
-   * cancellation signal (`ctx.signal`). An explicit per-call `timeoutMs` always
-   * wins. **Opt-in — undefined by default**, because switching it on globally
-   * would put a deadline on every call in an existing deployment and the
-   * failure mode is a working long-running call starting to time out.
-   * `execute_code` host calls are unaffected; they already carry a 15 s bound.
-   *
-   * Bounds a single attempt, not the whole call — the same as an explicit
-   * `timeoutMs` has always done. A call that also passes `maxRetries` can
-   * therefore run to roughly `(maxRetries + 1)` times this value plus backoff.
-   * `maxRetries` defaults to 0, so this is the total for every call that does
-   * not explicitly ask to retry.
-   */
-  defaultToolTimeoutMs?: number;
-  /**
-   * Deadline (ms) applied to each individual downstream probe/catalog call that
-   * the discovery meta-tools fan out — `list_connectors` (with `probe`),
-   * `search_tools`, and `describe_tools` — so a single hung connector can no
-   * longer stall the whole meta-tool call. **Defaults to a generous 30_000**,
-   * chosen to trip only on a pathological hang, not on a realistically slow
-   * probe, so having it on by default will not break existing deployments.
-   * Bounds one downstream call, not the whole fan-out: a connector that outruns
-   * it degrades to an unavailable/errored entry while the rest are unaffected.
-   *
-   * Does NOT apply to `call_tool`/`batch_call` — those carry their own budget
-   * via `defaultToolTimeoutMs` or a per-call `timeoutMs`. Note this bounds the
-   * caller-facing wait only; the underlying fetch is not currently aborted, so
-   * real cancellation of the downstream request is a deferred follow-up.
-   */
-  probeTimeoutMs?: number;
-  /**
-   * Tuning for the proactive credential liveness checks (issue #24) that let a
-   * connector's status flip to `auth_required` *before* an agent's call fails.
-   * Defaults are safe to leave alone: at most one check per connector per 15
-   * minutes, four in flight, 30 s each, triggered opportunistically by inbound
-   * authenticated traffic. Only connectors holding a credential connecta stores
-   * — an operator-managed `credential`, or a downstream-OAuth grant — are ever
-   * checked, and a check never calls a downstream tool.
-   *
-   * `Connecta.checkCredentials()` is the same check on demand, for a Worker cron
-   * trigger or a Node interval.
-   */
-  credentialHealth?: CredentialHealthConfig;
   serverInfo?: {
     name?: string;
     version?: string;
@@ -193,7 +198,7 @@ export interface Connecta {
    *
    * Returns one outcome per connector considered, including why a connector was
    * skipped (`fresh` is the rate limit: a connector checked less than
-   * `credentialHealth.intervalSeconds` ago is not re-checked unless `force`).
+   * `credentials.health.intervalSeconds` ago is not re-checked unless `force`).
    * Never rejects on a connector failure — a broken connector becomes an `error`
    * verdict. Needs a base URL for connector contexts: `publicUrl` supplies it,
    * or pass one.
@@ -223,6 +228,59 @@ function normalizeAuth(auth: ConnectaConfig["auth"]): InboundAuth[] {
   });
 }
 
+const LEGACY_CONFIG_MIGRATIONS = [
+  ["activityReadGate", "activity.readGate"],
+  ["activityDeploymentId", "activity.deploymentId"],
+  ["credentialEncryptionKey", "credentials.encryptionKey"],
+  ["credentialHealth", "credentials.health"],
+  ["toolCacheTtlSeconds", "discovery.catalogTtlSeconds"],
+  ["persistToolCatalog", "discovery.persistCatalog"],
+  ["toolCatalogStaleSeconds", "discovery.staleCatalogSeconds"],
+  ["probeTimeoutMs", "discovery.probeTimeoutMs"],
+  ["defaultToolTimeoutMs", "calls.defaultTimeoutMs"],
+  ["maxResultBytes", "calls.maxResultBytes"],
+] as const;
+
+const hasOwn = (value: object, key: PropertyKey): boolean =>
+  Object.prototype.hasOwnProperty.call(value, key);
+
+/**
+ * Fail closed at the public boundary: a JavaScript caller on the v0.6 shape
+ * must receive one complete migration error, never silently lose an option to
+ * a default. This runs before createConnecta reads any other config field.
+ */
+function assertNoLegacyConfig(config: ConnectaConfig): void {
+  const candidate = config as unknown as Record<PropertyKey, unknown>;
+  const found: Array<readonly [string, string]> = [];
+  if (hasOwn(candidate, "activity")) {
+    const activity = candidate.activity;
+    const isObject =
+      typeof activity === "object" && activity !== null;
+    // A valid v0.6 ActivityStore can itself own a backend field named `store`.
+    // Its required `record` method (including a prototype method) therefore
+    // takes precedence over the otherwise-new wrapper shape.
+    const hasLegacyRecord =
+      isObject &&
+      typeof (activity as { record?: unknown }).record === "function";
+    if (
+      activity !== undefined &&
+      (!isObject ||
+        hasLegacyRecord ||
+        !hasOwn(activity, "store"))
+    ) {
+      found.push(["activity", "activity.store"]);
+    }
+  }
+  for (const migration of LEGACY_CONFIG_MIGRATIONS) {
+    if (hasOwn(candidate, migration[0])) found.push(migration);
+  }
+  if (found.length === 0) return;
+  throw new Error(
+    "Unsupported v0.6.x ConnectaConfig options. Migrate each path for v0.7.0:\n" +
+      found.map(([oldPath, newPath]) => `- ${oldPath} -> ${newPath}`).join("\n"),
+  );
+}
+
 /**
  * One-time construction warnings for deployment shapes that run fine but are
  * usually unintended. Warning-only — never throws and never changes behavior;
@@ -333,12 +391,12 @@ function warnInsecureConfig(
     );
   }
 
-  // /ui renders exactly one provider's browser sign-in config — the first that
-  // offers one, which is the same `find` the /ui route performs — and that
+  // Operator shells render exactly one provider's browser sign-in config — the
+  // first that offers one, matching the server route's `find` — and that
   // provider's URLs reach the browser: frontendApiUrl as the loader's
   // `<script src>`, signInUrl/signUpUrl as the addresses ClerkJS navigates to.
   // Gate-or-drop like a branding href: rendering drops a rejected value and the
-  // dashboard then either reports that Clerk could not load or quietly signs in
+  // operator page then reports that Clerk could not load or quietly signs in
   // through Clerk's defaults — both confusing symptoms without this line naming
   // the cause. Checking only the rendered provider keeps the claim true — a
   // later provider's uiAuth never reaches the page, so there is nothing there
@@ -351,7 +409,7 @@ function warnInsecureConfig(
         `${droppedUiAuth.join(", ")} dropped: every uiAuth URL reaches the ` +
         "browser — as the sign-in loader's source, or as a place Clerk sends " +
         "the operator — so each must be an absolute https URL. A dropped " +
-        "value reaches no part of the page: without frontendApiUrl /ui renders " +
+        "value reaches no part of the page: without frontendApiUrl the operator shell renders " +
         "no loader and cannot start a sign-in, and without signInUrl/signUpUrl " +
         "it signs in through Clerk's defaults.",
     );
@@ -359,7 +417,7 @@ function warnInsecureConfig(
 
   // A credential test hook that cannot test the declared credential shape.
   // The shape picks the hook (see `credentialTestRule`) and the other one is
-  // never substituted, so the connector is simply not testable: /ui offers no
+  // never substituted, so the connector is simply not testable: /credentials offers no
   // Test action and the route answers 400. Without this line the only way to
   // discover the mistake is to click a button that isn't there.
   for (const connector of config.connectors) {
@@ -367,20 +425,23 @@ function warnInsecureConfig(
     if (!mismatch) continue;
     logger.warn(
       `[connecta] connector "${connector.id}" cannot test its credential: ` +
-        `${describeCredentialTestMismatch(mismatch)}. /ui offers no Test ` +
+        `${describeCredentialTestMismatch(mismatch)}. /credentials offers no Test ` +
         `action and POST /ui/credentials/${connector.id}/test answers 400 ` +
         "until the matching hook is implemented.",
     );
   }
 
-  // OAuth connectors whose callback performs no state/CSRF check: the public
-  // /oauth/callback/<id> route would exchange any delivered code.
+  // OAuth connectors whose callback cannot perform a state/CSRF check. The
+  // public route refuses every callback for these connectors rather than hand
+  // an unverified code to finishAuth, so this warning explains why auth cannot
+  // complete instead of describing a vulnerability the server permits.
   for (const connector of oauthConnectors) {
     if (!connector.verifyState) {
       logger.warn(
         `[connecta] connector "${connector.id}" has an OAuth callback with no ` +
-          `state/CSRF check: /oauth/callback/${connector.id} will exchange any ` +
-          "delivered code. Implement `verifyState` (the shipped remoteMcp " +
+          `state/CSRF check: /oauth/callback/${connector.id} refuses every ` +
+          "callback rather than exchange an unverified code. Implement " +
+          "`verifyState` to complete authorization (the shipped remoteMcp " +
           "connector already does).",
       );
     }
@@ -388,26 +449,28 @@ function warnInsecureConfig(
 }
 
 export function createConnecta(config: ConnectaConfig): Connecta {
+  assertNoLegacyConfig(config);
   const storage = config.storage ?? memoryStorage();
   const logger = config.logger ?? defaultLogger();
   const credentialConnectors = config.connectors.filter((c) => c.credential);
-  if (credentialConnectors.length > 0 && !config.credentialEncryptionKey) {
+  const encryptionKey = config.credentials?.encryptionKey;
+  if (credentialConnectors.length > 0 && !encryptionKey) {
     throw new Error(
-      `credentialEncryptionKey is required by connector credentials: ${credentialConnectors.map((c) => c.id).join(", ")}`,
+      `credentials.encryptionKey is required by connector credentials: ${credentialConnectors.map((c) => c.id).join(", ")}`,
     );
   }
-  const credentialVault = config.credentialEncryptionKey
-    ? new CredentialVault(storage, config.credentialEncryptionKey)
+  const credentialVault = encryptionKey
+    ? new CredentialVault(storage, encryptionKey)
     : undefined;
   const registry = new Registry(config.connectors, {
     storage,
     logger,
     credentialVault,
-    toolCacheTtlSeconds: config.toolCacheTtlSeconds,
-    persistToolCatalog: config.persistToolCatalog,
-    toolCatalogStaleSeconds: config.toolCatalogStaleSeconds,
-    maxResultBytes: config.maxResultBytes,
-    credentialHealth: config.credentialHealth,
+    toolCacheTtlSeconds: config.discovery?.catalogTtlSeconds,
+    persistToolCatalog: config.discovery?.persistCatalog,
+    toolCatalogStaleSeconds: config.discovery?.staleCatalogSeconds,
+    maxResultBytes: config.calls?.maxResultBytes,
+    credentialHealth: config.credentials?.health,
   });
   // Throws on every structural mistake it can see (see resolveToolkits): a
   // typo must not become a scope the operator never wrote. Note this is about
@@ -430,12 +493,12 @@ export function createConnecta(config: ConnectaConfig): Connecta {
       version: config.serverInfo?.version ?? CONNECTA_VERSION,
     },
     logger,
-    activity: config.activity,
-    activityReadGate: config.activityReadGate,
-    activityDeploymentId: config.activityDeploymentId,
+    activity: config.activity?.store,
+    activityReadGate: config.activity?.readGate,
+    activityDeploymentId: config.activity?.deploymentId,
     executor: config.executor,
-    defaultToolTimeoutMs: config.defaultToolTimeoutMs,
-    probeTimeoutMs: config.probeTimeoutMs,
+    defaultToolTimeoutMs: config.calls?.defaultTimeoutMs,
+    probeTimeoutMs: config.discovery?.probeTimeoutMs,
     credentialVault,
     deploymentInfo: config.deploymentInfo,
     branding: config.branding,
@@ -511,7 +574,11 @@ export type {
   CredentialHealthRecord,
 } from "./credential-health.js";
 
-export type { RemoteMcpOptions, RemoteMcpAuth } from "./connectors/remote-mcp.js";
+export type {
+  RemoteMcpOptions,
+  RemoteMcpAuth,
+  RemoteMcpRedirectPolicy,
+} from "./connectors/remote-mcp.js";
 export type { ApiOptions, ApiTool } from "./connectors/api.js";
 export type {
   Connector,

package/src/meta-tools.ts

@@ -6,6 +6,7 @@ import {
   type ActivityCallSource,
   type ActivityRequestContext,
 } from "./activity.js";
+import { closeConnectorScope } from "./connector-scope.js";
 import { unwrapMcpResult } from "./mcp-result.js";
 import {
   classifyCallError,
@@ -64,12 +65,126 @@ function msg(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
-const DEFAULT_SEARCH_LIMIT = 25;
+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 discoveryErrorResult(error: DiscoveryPolicyError): ToolResult {
+  const result = jsonResult({
+    error: {
+      code: error.code,
+      message: error.message,
+      retryable: false,
+    },
+  });
+  result.isError = true;
+  return result;
+}
+
+function discoveryResult(value: unknown, hint: string): ToolResult {
+  try {
+    const text = boundedDiscoveryText(value, hint);
+    return {
+      content: [{ type: "text", text }],
+      ...(value !== null && typeof value === "object" && !Array.isArray(value)
+        ? { structuredContent: value as Record<string, unknown> }
+        : {}),
+    };
+  } catch (err) {
+    if (err instanceof DiscoveryPolicyError) {
+      return discoveryErrorResult(err);
+    }
+    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
@@ -458,9 +573,9 @@ export interface SkillArgs {
  * optional tenth tool, is registered separately by registerExecuteTool.)
  *
  * The deployment-wide result-size cap is read off the registry view rather than
- * passed in: `ConnectaConfig.maxResultBytes` and the per-connector override are
- * the only places a cap is set, so there is one answer to where a deployment
- * sets it (issue #44).
+ * passed in: `ConnectaConfig.calls.maxResultBytes` and the per-connector
+ * override are the only places a cap is set, so there is one answer to where a
+ * deployment sets it (issue #44).
  */
 export function createMetaTools(
   registry: RegistryView,
@@ -788,8 +903,12 @@ export function createMetaTools(
 
     async listConnectors(args: ListArgs = {}): Promise<ToolResult> {
       const probe = args.probe ?? true;
+      // Live inventory owns a short-lived scope separate from the request's
+      // call scope. Closing it cannot defeat call_tool/batch/execute_code reuse.
+      const connectors = registry.listConnectors();
+      const scope = probe ? {} : requestScope;
       const out = await Promise.all(
-        registry.listConnectors().map(async (c) => {
+        connectors.map(async (c) => {
           const statusStarted = Date.now();
           const observed = registry.healthFor(c.id);
           const verdict = await registry.credentialHealthFor(c.id);
@@ -799,7 +918,7 @@ export function createMetaTools(
           if (probe) {
             try {
               status = await withTimeout(
-                registry.statusFor(c.id, baseUrl, requestScope),
+                registry.statusFor(c.id, baseUrl, scope),
                 probeTimeoutMs,
                 `list_connectors probe of "${c.id}"`,
               );
@@ -886,7 +1005,7 @@ export function createMetaTools(
           if (probe && status.state === "ok") {
             try {
               tools = await withTimeout(
-                registry.refreshTools(c.id, baseUrl, requestScope),
+                registry.refreshTools(c.id, baseUrl, scope),
                 probeTimeoutMs,
                 `list_connectors catalog refresh of "${c.id}"`,
               );
@@ -918,13 +1037,31 @@ export function createMetaTools(
             ...(status.message ? { message: status.message } : {}),
           };
         }),
-      );
+      ).finally(async () => {
+        if (!probe) return;
+        await Promise.all(
+          connectors.map((connector) =>
+            closeConnectorScope(
+              connector,
+              registry.contextFor(connector.id, baseUrl, scope),
+            ),
+          ),
+        );
+      });
       return jsonResult({ connectors: out });
     },
 
     async searchTools(args: SearchArgs): Promise<ToolResult> {
       const q = args.query ?? "";
-      const limit = Math.max(1, Math.trunc(args.limit ?? DEFAULT_SEARCH_LIMIT));
+      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(
@@ -1035,17 +1172,28 @@ export function createMetaTools(
         offset + page.length < matches.length
           ? offset + page.length
           : undefined;
-      return jsonResult({
-        connectors: groups,
-        total: matches.length,
-        offset,
-        limit,
-        hasMore: nextOffset !== undefined,
-        ...(nextOffset !== undefined ? { nextOffset } : {}),
-      });
+      return discoveryResult(
+        {
+          connectors: groups,
+          total: matches.length,
+          offset,
+          limit,
+          hasMore: nextOffset !== undefined,
+          ...(nextOffset !== undefined ? { nextOffset } : {}),
+        },
+        "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,
@@ -1116,7 +1264,10 @@ export function createMetaTools(
           ...(tool.annotations ? { annotations: tool.annotations } : {}),
         };
       });
-      return jsonResult({ tools: out });
+      return discoveryResult(
+        { tools: out },
+        'Split the address list or use format: "compact".',
+      );
     },
 
     async callTool(args: CallArgs): Promise<ToolResult> {
@@ -1312,10 +1463,8 @@ 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. includeSchemas="compact" usually removes the describe_tools round trip.';
-const DESCRIBE_DESC =
-  'Inspect 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 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 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 =
@@ -1429,7 +1578,7 @@ export function registerMetaTools(
       inputSchema: {
         query: z.string().optional(),
         connector: z.string().optional(),
-        limit: z.number().int().positive().optional(),
+        limit: z.number().int().positive().max(MAX_SEARCH_LIMIT).optional(),
         offset: z.number().int().nonnegative().optional(),
         fullDescriptions: z.boolean().optional(),
         includeSchemas: z.enum(["compact", "json"]).optional(),
@@ -1444,7 +1593,7 @@ export function registerMetaTools(
     {
       description: describedFor(registry, DESCRIBE_DESC, "describe"),
       inputSchema: {
-        addresses: z.array(z.string()),
+        addresses: z.array(z.string()).max(MAX_DESCRIBE_ADDRESSES),
         format: z.enum(["compact", "json"]).optional(),
         fullDescriptions: z.boolean().optional(),
       },