@zackbart/connecta 0.4.1 → 0.5.0

package/dist/index.d.ts

@@ -1,8 +1,39 @@
 import { Registry } from "./registry.js";
+import { type ToolkitConfig } from "./toolkits.js";
 import type { ActivityReadGate, ActivityStore } from "./activity.js";
 import type { Connector, ConnectaBranding, Executor, InboundAuth, KVStorage, Logger } from "./types.js";
 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.
@@ -46,7 +77,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;
     /**
@@ -121,6 +154,7 @@ export { bearerToken } from "./auth/bearer.js";
 export { memoryStorage } from "./storage/memory.js";
 export { CONNECTA_VERSION } from "./version.js";
 export type { Registry } from "./registry.js";
+export type { ToolkitConfig, ToolkitDefinition } from "./toolkits.js";
 export type { RemoteMcpOptions, RemoteMcpAuth } from "./connectors/remote-mcp.js";
 export type { ApiOptions, ApiTool } from "./connectors/api.js";
 export type { Connector, ConnectaBranding, ConnectorCredentialAccess, ConnectorCredentialConfig, ConnectorCredentialFieldConfig, ConnectorCredentialValues, ConnectorContext, ConnectorStatus, CredentialTestResult, ExecuteResult, Executor, ExecutorProvider, InboundAuth, UiAuthConfig, AuthResult, JsonSchema, KVStorage, Logger, ToolDef, ToolAnnotations, } from "./types.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -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 } from "./toolkits.js";
 import { memoryStorage } from "./storage/memory.js";
 import { CONNECTA_VERSION } from "./version.js";
 function defaultLogger() {
@@ -44,6 +46,25 @@ function warnInsecureConfig(config, inboundAuth, logger) {
             "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) {
@@ -74,6 +95,11 @@ export function createConnecta(config) {
         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({
@@ -95,6 +121,7 @@ export function createConnecta(config) {
         credentialVault,
         deploymentInfo: config.deploymentInfo,
         branding: config.branding,
+        ...(toolkits ? { toolkits } : {}),
     });
     return {
         fetch: (request, _env, ctx) => handler(request, ctx && typeof ctx.waitUntil === "function"

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/meta-tools.d.ts

@@ -1,6 +1,6 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type ActivityRequestContext } from "./activity.js";
-import type { Registry } from "./registry.js";
+import { type RegistryView } from "./registry.js";
 interface TextContent {
     type: "text";
     text: string;
@@ -38,6 +38,22 @@ export declare const MAX_RETRY_BACKOFF_MS = 10000;
  * `runCall`. Exported for direct testing.
  */
 export declare function retryBackoffMs(attempt: number, retryAfterMs: number | undefined): number | undefined;
+/**
+ * Move a byte `end` back to the nearest UTF-8 codepoint boundary in
+ * `(offset, total]`, so decoding `bytes[offset, end)` never splits a codepoint
+ * (which would emit U+FFFD and break byte-exact reassembly). If backing up
+ * would make no progress — a single codepoint wider than the window — extend
+ * 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.
+ */
+export declare function alignEndToCharBoundary(bytes: Uint8Array, offset: number, end: number, total: number): number;
 export interface SearchArgs {
     query?: string;
     connector?: string;
@@ -70,6 +86,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 {
@@ -98,11 +115,12 @@ 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 declare function createMetaTools(registry: Registry, baseUrl: string, opts?: {
+export declare function createMetaTools(registry: RegistryView, baseUrl: string, opts?: {
     maxResultBytes?: number;
     /** Deadline applied when a call passes no `timeoutMs`. Off when unset. */
     defaultToolTimeoutMs?: number;
@@ -121,7 +139,7 @@ export declare function createMetaTools(registry: Registry, baseUrl: string, opt
     authorizeConnector(args: AuthorizeArgs): Promise<ToolResult>;
 };
 /** Register the nine meta-tools onto an McpServer instance. */
-export declare function registerMetaTools(server: McpServer, registry: Registry, ctx: {
+export declare function registerMetaTools(server: McpServer, registry: RegistryView, ctx: {
     baseUrl: string;
     maxResultBytes?: number;
     defaultToolTimeoutMs?: number;

package/dist/meta-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"meta-tools.d.ts","sourceRoot":"","sources":["../src/meta-tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"meta-tools.d.ts","sourceRoot":"","sources":["../src/meta-tools.ts"],"names":[],"mappings":"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"}

package/dist/meta-tools.js

@@ -3,7 +3,8 @@ import { compactSchema, rankTools, summarizeDescription } from "./catalog.js";
 import { recordToolActivity, } from "./activity.js";
 import { unwrapMcpResult } from "./mcp-result.js";
 import { classifyCallError, ConnectorCallError, messageLooksRetryable, } from "./errors.js";
-import { AVAILABLE_SKILLS } from "./skills.js";
+import { isValidMaxResultBytes, MIN_MAX_RESULT_BYTES, resolveMaxResultBytes, } from "./registry.js";
+import { connectorGuide, connectorSkillName, hasConnectorGuides, listSkills, resolveSkill, } from "./skills.js";
 const RESULT_TTL_SECONDS = 900;
 export function jsonResult(obj) {
     return {
@@ -102,16 +103,25 @@ function isContinuationByte(b) {
  * 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(bytes, offset, end, total) {
+export function alignEndToCharBoundary(bytes, offset, end, total) {
     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++;
     }
@@ -210,12 +220,13 @@ async function guardValue(value, results, cap) {
 /**
  * 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, baseUrl, opts = {}) {
-    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
@@ -276,6 +287,13 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
             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.
@@ -423,21 +441,23 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
     }
     return {
         async skills(args = {}) {
+            const connectors = registry.listConnectors();
             if (!args.name) {
                 return {
                     content: [
                         {
                             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 }] };
         },
         async listConnectors(args = {}) {
@@ -459,11 +479,16 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                     }
                 }
                 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"
-                            : observed?.lastSuccessAt || c.kind === "api"
+                            : registry.hasObservedSuccess(c.id) || c.kind === "api"
                                 ? "ok"
                                 : "unknown",
                         ...(observed?.lastError ? { message: observed.lastError } : {}),
@@ -521,6 +546,9 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                             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,
@@ -540,6 +568,9 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                         id: match.connectorId,
                         ...(match.connectorTitle ? { title: match.connectorTitle } : {}),
                         description: match.connectorDescription,
+                        ...(match.connectorGuideSkill
+                            ? { guide: match.connectorGuideSkill }
+                            : {}),
                         tools: [],
                     };
                     byConnector.set(match.connectorId, group);
@@ -621,6 +652,9 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                     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
                         ? {
@@ -641,6 +675,16 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
             return (await runCall(args, "call_destructive_tool", { allowDestructive: true })).toolResult;
         },
         async getResult(args) {
+            // 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) {
@@ -649,7 +693,11 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
             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
@@ -768,10 +816,32 @@ const SEARCH_DESC = 'Start here when a tool address is unknown. Exact/name match
 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 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. Unknown/expired id is an error.";
+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). 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 = "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 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> }).",
+};
+/** `base`, plus its guide note when any VISIBLE connector carries a guide. */
+function describedFor(registry, base, note) {
+    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
@@ -799,7 +869,7 @@ export function registerMetaTools(server, registry, ctx) {
         activity: ctx.activity,
     });
     server.registerTool("skills", {
-        description: SKILLS_DESC,
+        description: describedFor(registry, SKILLS_DESC, "skills"),
         inputSchema: { name: z.string().optional() },
         annotations: {
             readOnlyHint: true,
@@ -814,7 +884,7 @@ export function registerMetaTools(server, registry, ctx) {
         annotations: READ_ONLY_REMOTE,
     }, async (args) => mt.listConnectors(args));
     server.registerTool("search_tools", {
-        description: SEARCH_DESC,
+        description: describedFor(registry, SEARCH_DESC, "search"),
         inputSchema: {
             query: z.string().optional(),
             connector: z.string().optional(),
@@ -826,7 +896,7 @@ export function registerMetaTools(server, registry, ctx) {
         annotations: READ_ONLY_REMOTE,
     }, async (args) => mt.searchTools(args));
     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(),
@@ -885,7 +955,10 @@ export function registerMetaTools(server, registry, ctx) {
         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,
     }, async (args) => mt.getResult(args));