@zackbart/connecta 0.4.0 → 0.5.0

package/src/index.ts

@@ -1,6 +1,8 @@
 import { CredentialVault } from "./credentials.js";
 import { Registry } from "./registry.js";
 import { createFetchHandler } from "./server.js";
+import { droppedBrandingUrls } from "./ui.js";
+import { resolveToolkits, type ToolkitConfig } from "./toolkits.js";
 import { memoryStorage } from "./storage/memory.js";
 import { CONNECTA_VERSION } from "./version.js";
 import type { ActivityReadGate, ActivityStore } from "./activity.js";
@@ -15,6 +17,36 @@ import type {
 
 export interface ConnectaConfig {
   connectors: Connector[];
+  /**
+   * Named scoped views over `connectors`, selected per client connection with
+   * `?toolkit=<name>` on the `/mcp` URL. One deployment belongs to one org;
+   * a toolkit is the slice of it a group of team members sees.
+   *
+   * ```ts
+   * toolkits: {
+   *   support: { connectors: ["zendesk", "notion"] },
+   *   exec: {
+   *     connectors: ["zendesk", "notion", "gmail"],
+   *     excludeTools: ["gmail.send_message"],
+   *   },
+   * }
+   * ```
+   *
+   * Inside a toolkit-scoped session every meta-tool behaves as if out-of-scope
+   * connectors and tools do not exist, and an out-of-scope address fails
+   * exactly as a nonexistent one does. No `?toolkit=` ⇒ the full registry, so
+   * adding toolkits changes nothing for connections that don't ask for one; an
+   * unknown name is an error, never a silent fallback.
+   *
+   * Toolkits scope VISIBILITY, not identity: they do not decide *which* team
+   * member may select which toolkit. Gate that in `auth` (per-member binding is
+   * a follow-up).
+   *
+   * Definitions are validated at construction: an unknown connector id, an
+   * empty connector selection, an empty `includeTools`, a malformed tool
+   * 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.
@@ -58,7 +90,9 @@ export interface ConnectaConfig {
   toolCatalogStaleSeconds?: number;
   /**
    * Max inline result size (bytes) before call_tool/batch_call truncate and
-   * stash the full text for get_result paging. Default 50_000.
+   * 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;
   /**
@@ -77,6 +111,22 @@ export interface ConnectaConfig {
    * 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;
   serverInfo?: {
     name?: string;
     version?: string;
@@ -122,6 +172,83 @@ function normalizeAuth(auth: ConnectaConfig["auth"]): InboundAuth[] {
   });
 }
 
+/**
+ * One-time construction warnings for deployment shapes that run fine but are
+ * usually unintended. Warning-only — never throws and never changes behavior;
+ * each condition emits at most one `logger.warn`. Iterates connectors once.
+ */
+function warnInsecureConfig(
+  config: ConnectaConfig,
+  inboundAuth: InboundAuth[],
+  logger: Logger,
+): void {
+  const oauthConnectors = config.connectors.filter((c) => c.finishAuth);
+  const hasCredentialConnector = config.connectors.some((c) => c.credential);
+
+  // Open mode (no inbound auth) with connectors that expose credentials or
+  // downstream OAuth: any caller reaches everything, including the vault.
+  if (
+    inboundAuth.length === 0 &&
+    (hasCredentialConnector || oauthConnectors.length > 0)
+  ) {
+    logger.warn(
+      "[connecta] running with no inbound authentication: any caller can " +
+        "invoke every connector and read or overwrite stored credentials. " +
+        "Configure `auth` (for example bearerToken(...) or Clerk) to gate access.",
+    );
+  }
+
+  // Unset publicUrl with OAuth connectors: the downstream redirect_uri is
+  // derived per-request from the attacker-influenced inbound Host header.
+  if (oauthConnectors.length > 0 && !config.publicUrl) {
+    logger.warn(
+      "[connecta] publicUrl is unset while OAuth connectors are configured: " +
+        "the downstream OAuth redirect_uri is derived per-request from the " +
+        "inbound Host header, so an attacker who controls that header can point " +
+        "it at their own host and capture the authorization code. Set " +
+        "`publicUrl` to a fixed https origin.",
+    );
+  }
+
+  // Toolkits with no inbound auth: a toolkit is a scoped VIEW selected by the
+  // caller, not an authentication boundary. With nothing gating /mcp, any
+  // caller picks any toolkit — or omits the parameter and sees everything.
+  if (inboundAuth.length === 0 && config.toolkits) {
+    logger.warn(
+      "[connecta] toolkits are configured but there is no inbound " +
+        "authentication: a toolkit is a scoped view a client selects with " +
+        "?toolkit=, not an access check, so any caller can choose any toolkit " +
+        "or omit the parameter and see every connector. Configure `auth` " +
+        "(for example bearerToken(...) or Clerk).",
+    );
+  }
+
+  // Branding URLs that failed their scheme gate. Rendering silently falls back
+  // (a bad URL must not take the page down), so this warning is the only way an
+  // operator learns their value never reached the page.
+  const dropped = droppedBrandingUrls(config.branding);
+  if (dropped.length > 0) {
+    logger.warn(
+      `[connecta] branding ${dropped.join(", ")} dropped: a branding URL is ` +
+        "used as an href, so it must be an absolute http(s) URL (favicon.href " +
+        "may also be a root-relative path). The default is rendered instead.",
+    );
+  }
+
+  // OAuth connectors whose callback performs no state/CSRF check: the public
+  // /oauth/callback/<id> route would exchange any delivered code.
+  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 " +
+          "connector already does).",
+      );
+    }
+  }
+}
+
 export function createConnecta(config: ConnectaConfig): Connecta {
   const storage = config.storage ?? memoryStorage();
   const logger = config.logger ?? defaultLogger();
@@ -143,9 +270,16 @@ export function createConnecta(config: ConnectaConfig): Connecta {
     toolCatalogStaleSeconds: config.toolCatalogStaleSeconds,
     maxResultBytes: config.maxResultBytes,
   });
+  // 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
+  // the scope being *intended*, not about it being an access check — a toolkit
+  // scopes visibility, and `auth` remains the thing deciding who gets in.
+  const toolkits = resolveToolkits(config.toolkits, config.connectors);
+  const inboundAuth = normalizeAuth(config.auth);
+  warnInsecureConfig(config, inboundAuth, logger);
   const handler = createFetchHandler({
     registry,
-    auth: normalizeAuth(config.auth),
+    auth: inboundAuth,
     publicUrl: config.publicUrl,
     serverInfo: {
       ...config.serverInfo,
@@ -158,9 +292,11 @@ export function createConnecta(config: ConnectaConfig): Connecta {
     activityDeploymentId: config.activityDeploymentId,
     executor: config.executor,
     defaultToolTimeoutMs: config.defaultToolTimeoutMs,
+    probeTimeoutMs: config.probeTimeoutMs,
     credentialVault,
     deploymentInfo: config.deploymentInfo,
     branding: config.branding,
+    ...(toolkits ? { toolkits } : {}),
   });
   return {
     fetch: (request, _env, ctx) =>
@@ -190,6 +326,9 @@ export { CONNECTA_VERSION } from "./version.js";
 // the class itself, the credential vault, and the meta-tool/sandbox factories
 // are internal factoring and are deliberately not part of the API surface.
 export type { Registry } from "./registry.js";
+// Config-as-code shapes for `ConnectaConfig.toolkits`. The resolved `Toolkit`
+// and the `ScopedRegistry` that enforces it are internal factoring.
+export type { ToolkitConfig, ToolkitDefinition } from "./toolkits.js";
 
 export type { RemoteMcpOptions, RemoteMcpAuth } from "./connectors/remote-mcp.js";
 export type { ApiOptions, ApiTool } from "./connectors/api.js";

package/src/meta-tools.ts

@@ -13,9 +13,20 @@ import {
   messageLooksRetryable,
   type CallErrorDetails,
 } from "./errors.js";
-import type { Registry } from "./registry.js";
-import { AVAILABLE_SKILLS } from "./skills.js";
-import type { KVStorage, ToolDef } from "./types.js";
+import {
+  isValidMaxResultBytes,
+  MIN_MAX_RESULT_BYTES,
+  resolveMaxResultBytes,
+  type RegistryView,
+} from "./registry.js";
+import {
+  connectorGuide,
+  connectorSkillName,
+  hasConnectorGuides,
+  listSkills,
+  resolveSkill,
+} from "./skills.js";
+import type { ConnectorStatus, KVStorage, ToolDef } from "./types.js";
 
 interface TextContent {
   type: "text";
@@ -72,6 +83,42 @@ function normalizeTimeoutMs(value: number | undefined): number | undefined {
   return Math.max(1, Math.trunc(value));
 }
 
+/**
+ * Generous default bound for a single downstream probe/catalog call in the
+ * list/search/describe fan-out. High enough to trip only on a pathological
+ * hang, not a realistically slow probe.
+ */
+const DEFAULT_PROBE_TIMEOUT_MS = 30_000;
+
+/**
+ * Reject `promise` after `ms` if it has not settled, so one hung downstream
+ * cannot stall a whole fan-out. NOTE: this bounds only the caller-facing wait —
+ * the registry probe methods take no AbortSignal, so the underlying fetch is
+ * NOT cancelled and keeps running in the background. Real cancellation
+ * (AbortSignal plumbed through the registry) is a deferred follow-up.
+ */
+function withTimeout<T>(
+  promise: Promise<T>,
+  ms: number,
+  label: string,
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`${label} timed out after ${ms}ms`));
+    }, ms);
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err);
+      },
+    );
+  });
+}
+
 /**
  * How long to wait before the next attempt, or `undefined` for "don't retry".
  *
@@ -114,19 +161,28 @@ function isContinuationByte(b: number): boolean {
  * forward to the end of that codepoint instead so paging always advances.
  * Assumes `offset` is itself a codepoint boundary (offsets are the prior
  * `nextOffset`, which this function guarantees, and 0 is always a boundary).
+ *
+ * The return is always `> offset` while `offset < total`, whatever `end` is
+ * asked for. That is the belt-and-braces half of issue #32: cap validation
+ * keeps an empty window from arising in the first place, and this keeps an
+ * empty window from turning into a `nextOffset === offset` paging loop if one
+ * ever does. Exported for direct testing of that invariant.
  */
-function alignEndToCharBoundary(
+export function alignEndToCharBoundary(
   bytes: Uint8Array,
   offset: number,
   end: number,
   total: number,
 ): number {
   if (end >= total) return total;
-  let e = end;
+  // A window that reaches no further than `offset` yields no bytes and no
+  // progress; widen it to one byte and let the codepoint walk below finish it.
+  const wanted = Math.max(end, offset + 1);
+  let e = wanted;
   while (e > offset && isContinuationByte(bytes[e])) e--;
   if (e === offset) {
     // Window is narrower than the codepoint at `offset`; take the whole thing.
-    e = end;
+    e = wanted;
     while (e < total && isContinuationByte(bytes[e])) e++;
   }
   return e;
@@ -274,6 +330,7 @@ export interface CallArgs {
 export interface GetResultArgs {
   id: string;
   offset?: number;
+  /** Page size in bytes; a whole number >= 1. Defaults to the deployment cap. */
   maxBytes?: number;
 }
 export interface BatchCall {
@@ -303,22 +360,30 @@ export interface SkillArgs {
 /**
  * The nine meta-tool handlers over a registry. Exported for direct testing;
  * registerMetaTools() wires them onto an McpServer. `opts.maxResultBytes`
- * overrides the registry's default result-size cap; `opts.defaultToolTimeoutMs`
+ * overrides the registry's default result-size cap (a connector's own
+ * `maxResultBytes` overrides it in turn); `opts.defaultToolTimeoutMs`
  * supplies a deadline for calls that don't carry one. (execute_code, the
  * optional tenth tool, is registered separately by registerExecuteTool.)
  */
 export function createMetaTools(
-  registry: Registry,
+  registry: RegistryView,
   baseUrl: string,
   opts: {
     maxResultBytes?: number;
     /** Deadline applied when a call passes no `timeoutMs`. Off when unset. */
     defaultToolTimeoutMs?: number;
+    /** Per-connector deadline for the list/search/describe probe fan-out. Default 30_000. */
+    probeTimeoutMs?: number;
     activity?: ActivityRequestContext;
   } = {},
 ) {
-  const cap = opts.maxResultBytes ?? registry.maxResultBytes;
+  const globalCap = resolveMaxResultBytes(
+    opts.maxResultBytes,
+    registry.maxResultBytes,
+  );
   const defaultToolTimeoutMs = normalizeTimeoutMs(opts.defaultToolTimeoutMs);
+  const probeTimeoutMs =
+    normalizeTimeoutMs(opts.probeTimeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS;
   // 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.
@@ -402,6 +467,16 @@ export function createMetaTools(
       );
     }
     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.
@@ -592,6 +667,7 @@ export function createMetaTools(
 
   return {
     async skills(args: SkillArgs = {}): Promise<ToolResult> {
+      const connectors = registry.listConnectors();
       if (!args.name) {
         return {
           content: [
@@ -599,19 +675,15 @@ export function createMetaTools(
               type: "text",
               text:
                 'Available skills. Fetch one with skills({ name: "<name>" }).\n\n' +
-                AVAILABLE_SKILLS.map(
-                  (skill) => `- \`${skill.name}\` — ${skill.description}`,
-                ).join("\n"),
+                listSkills(connectors)
+                  .map((skill) => `- \`${skill.name}\` — ${skill.description}`)
+                  .join("\n"),
             },
           ],
         };
       }
-      const skill = AVAILABLE_SKILLS.find((item) => item.name === args.name);
-      if (!skill) {
-        return errorResult(
-          `Unknown skill "${args.name}". Available: ${AVAILABLE_SKILLS.map((item) => item.name).join(", ")}.`,
-        );
-      }
+      const skill = resolveSkill(args.name, connectors);
+      if (!skill.found) return errorResult(skill.message);
       return { content: [{ type: "text", text: skill.content }] };
     },
 
@@ -622,25 +694,50 @@ export function createMetaTools(
           const checkedAt = new Date().toISOString();
           const statusStarted = Date.now();
           const observed = registry.healthFor(c.id);
-          let status = probe
-            ? await registry.statusFor(c.id, baseUrl, requestScope)
-            : {
-                state:
-                  observed?.consecutiveFailures &&
-                  observed.consecutiveFailures > 0
-                    ? ("error" as const)
-                    : observed?.lastSuccessAt || c.kind === "api"
-                      ? ("ok" as const)
-                      : ("unknown" as const),
-                ...(observed?.lastError ? { message: observed.lastError } : {}),
-              };
+          let status:
+            | ConnectorStatus
+            | { state: "ok" | "error" | "unknown"; message?: string };
+          if (probe) {
+            try {
+              status = await withTimeout(
+                registry.statusFor(c.id, baseUrl, requestScope),
+                probeTimeoutMs,
+                `list_connectors probe of "${c.id}"`,
+              );
+            } catch (err) {
+              // A probe that outran probeTimeoutMs (or otherwise threw)
+              // degrades this connector to an error status rather than
+              // hanging the whole list_connectors call.
+              status = { state: "error", message: msg(err) };
+            }
+          } else {
+            // "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.
+            status = {
+              state:
+                observed?.consecutiveFailures &&
+                observed.consecutiveFailures > 0
+                  ? ("error" as const)
+                  : registry.hasObservedSuccess(c.id) || c.kind === "api"
+                    ? ("ok" as const)
+                    : ("unknown" as const),
+              ...(observed?.lastError ? { message: observed.lastError } : {}),
+            };
+          }
           let tools = registry.peekTools(c.id);
           // An auth_required status may have just started OAuth. A second
           // listTools probe would overwrite its state/verifier while returning
           // the first (now stale) authorization URL.
           if (probe && status.state === "ok") {
             try {
-              tools = await registry.refreshTools(c.id, baseUrl, requestScope);
+              tools = await withTimeout(
+                registry.refreshTools(c.id, baseUrl, requestScope),
+                probeTimeoutMs,
+                `list_connectors catalog refresh of "${c.id}"`,
+              );
               registry.recordSuccess(c.id, Date.now() - statusStarted);
             } catch (err) {
               status = { state: "error" as const, message: msg(err) };
@@ -682,12 +779,19 @@ export function createMetaTools(
         connectorId: string;
         connectorTitle?: string;
         connectorDescription?: string;
+        connectorGuideSkill?: string;
         tool: ToolDef;
         score: number;
         order: number;
       }> = [];
       const catalogs = await Promise.allSettled(
-        conns.map((c) => registry.getTools(c.id, baseUrl, requestScope)),
+        conns.map((c) =>
+          withTimeout(
+            registry.getTools(c.id, baseUrl, requestScope),
+            probeTimeoutMs,
+            `search_tools probe of "${c.id}"`,
+          ),
+        ),
       );
       let orderBase = 0;
       catalogs.forEach((catalog, connectorIndex) => {
@@ -698,6 +802,9 @@ export function createMetaTools(
               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,
@@ -712,6 +819,8 @@ export function createMetaTools(
         id: string;
         title?: string;
         description?: string;
+        /** Skill name of this connector's usage guide, when it has one. */
+        guide?: string;
         tools: Array<{
           name: string;
           address: string;
@@ -729,6 +838,9 @@ export function createMetaTools(
             id: match.connectorId,
             ...(match.connectorTitle ? { title: match.connectorTitle } : {}),
             description: match.connectorDescription,
+            ...(match.connectorGuideSkill
+              ? { guide: match.connectorGuideSkill }
+              : {}),
             tools: [],
           };
           byConnector.set(match.connectorId, group);
@@ -791,7 +903,13 @@ export function createMetaTools(
         ),
       ];
       const loaded = await Promise.allSettled(
-        connectorIds.map((id) => registry.getTools(id, baseUrl, requestScope)),
+        connectorIds.map((id) =>
+          withTimeout(
+            registry.getTools(id, baseUrl, requestScope),
+            probeTimeoutMs,
+            `describe_tools probe of "${id}"`,
+          ),
+        ),
       );
       const catalogs = new Map<string, ToolDef[] | Error>();
       loaded.forEach((result, index) => {
@@ -827,6 +945,9 @@ export function createMetaTools(
             tool.description,
             args.fullDescriptions === true,
           ),
+          ...(connectorGuide(resolved.connector)
+            ? { guide: connectorSkillName(resolved.connector.id) }
+            : {}),
           inputSchema: format === "json" ? schema : compactSchema(schema),
           ...(tool.outputSchema
             ? {
@@ -853,6 +974,20 @@ export function createMetaTools(
     },
 
     async getResult(args: GetResultArgs): Promise<ToolResult> {
+      // Client-supplied page size: a normal input-validation error, not a
+      // clamp. Callers arriving over MCP are rejected earlier by the
+      // registered zod schema and never reach this branch, so it exists for
+      // in-process callers of createMetaTools — which have no schema in front
+      // of them — and to keep the rule true of the handler on its own terms.
+      if (
+        args.maxBytes !== undefined &&
+        !isValidMaxResultBytes(args.maxBytes)
+      ) {
+        return errorResult(
+          `Invalid maxBytes ${args.maxBytes}: must be a whole number of bytes ` +
+            `>= ${MIN_MAX_RESULT_BYTES}. Omit it to use the deployment default.`,
+        );
+      }
       const results = registry.resultsStorage();
       const stored = await results.get(`result:${args.id}`);
       if (stored === null || stored === undefined) {
@@ -861,7 +996,11 @@ export function createMetaTools(
       const bytes = enc.encode(stored);
       const total = bytes.length;
       const offset = Math.max(0, Math.trunc(args.offset ?? 0));
-      const maxBytes = args.maxBytes ?? cap;
+      // Page size only: a stashed result carries no connector identity, so
+      // get_result keeps the deployment-wide default when none is requested.
+      // Both sides are validated by now — the argument above, `globalCap` at
+      // intake — so `offset + maxBytes` always reaches past `offset`.
+      const maxBytes = args.maxBytes ?? globalCap;
       // Align the slice end to a codepoint boundary so a multi-byte char is
       // never split across pages (which would emit U+FFFD on both sides).
       // `nextOffset` is this aligned end, so it is a valid boundary for the
@@ -1004,7 +1143,7 @@ const CALL_DESC =
 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. Unknown/expired id is an error.";
+  "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). 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.";
 const AUTHORIZE_DESC =
@@ -1012,6 +1151,37 @@ const AUTHORIZE_DESC =
 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
+ * actually has connector guides. Tool descriptions are always-loaded context,
+ * 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.
+ */
+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.',
+  search:
+    " A connector group carrying `guide` has a usage guide; fetch it with skills({ name: <guide> }).",
+  describe:
+    " An entry carrying `guide` belongs to a connector with a usage guide; fetch it with skills({ name: <guide> }).",
+} as const;
+
+/** `base`, plus its guide note when any VISIBLE connector carries a guide. */
+function describedFor(
+  registry: RegistryView,
+  base: string,
+  note: keyof typeof GUIDE_NOTES,
+): string {
+  return hasConnectorGuides(registry.listConnectors())
+    ? base + GUIDE_NOTES[note]
+    : base;
+}
+
 /**
  * Connecta refuses downstream tools that are not explicitly annotated
  * read-only, so its own meta-tools must carry the same hints — otherwise a
@@ -1035,24 +1205,26 @@ const READ_ONLY_LOCAL = {
 /** Register the nine meta-tools onto an McpServer instance. */
 export function registerMetaTools(
   server: McpServer,
-  registry: Registry,
+  registry: RegistryView,
   ctx: {
     baseUrl: string;
     maxResultBytes?: number;
     defaultToolTimeoutMs?: number;
+    probeTimeoutMs?: number;
     activity?: ActivityRequestContext;
   },
 ): void {
   const mt = createMetaTools(registry, ctx.baseUrl, {
     maxResultBytes: ctx.maxResultBytes,
     defaultToolTimeoutMs: ctx.defaultToolTimeoutMs,
+    probeTimeoutMs: ctx.probeTimeoutMs,
     activity: ctx.activity,
   });
 
   server.registerTool(
     "skills",
     {
-      description: SKILLS_DESC,
+      description: describedFor(registry, SKILLS_DESC, "skills"),
       inputSchema: { name: z.string().optional() },
       annotations: {
         readOnlyHint: true,
@@ -1077,7 +1249,7 @@ export function registerMetaTools(
   server.registerTool(
     "search_tools",
     {
-      description: SEARCH_DESC,
+      description: describedFor(registry, SEARCH_DESC, "search"),
       inputSchema: {
         query: z.string().optional(),
         connector: z.string().optional(),
@@ -1094,7 +1266,7 @@ export function registerMetaTools(
   server.registerTool(
     "describe_tools",
     {
-      description: DESCRIBE_DESC,
+      description: describedFor(registry, DESCRIBE_DESC, "describe"),
       inputSchema: {
         addresses: z.array(z.string()),
         format: z.enum(["compact", "json"]).optional(),
@@ -1173,7 +1345,10 @@ export function registerMetaTools(
       inputSchema: {
         id: z.string(),
         offset: z.number().int().nonnegative().optional(),
-        maxBytes: z.number().int().positive().optional(),
+        // Same rule as isValidMaxResultBytes, expressed for the wire: sharing
+        // the floor constant keeps the schema from drifting away from the
+        // in-handler check if MIN_MAX_RESULT_BYTES ever moves.
+        maxBytes: z.number().int().min(MIN_MAX_RESULT_BYTES).optional(),
       },
       annotations: READ_ONLY_LOCAL,
     },