@zackbart/connecta 0.12.2 → 0.13.0

package/src/catalog-service.ts

@@ -25,6 +25,8 @@ import type {
 } from "./registry.js";
 import {
   connectorGuide,
+  connectorGuideRequired,
+  connectorGuideSummary,
   connectorSkillName,
 } from "./skills.js";
 import {
@@ -196,6 +198,7 @@ export interface CatalogDescribeArgs {
 interface CatalogSearchEntry {
   connector: Connector;
   guide?: string;
+  guideSummary?: string;
   tool: {
     name: string;
     address: string;
@@ -208,9 +211,34 @@ interface CatalogSearchEntry {
     requiredInputKeys?: string[];
     outputKeys?: string[];
     annotations?: ToolDef["annotations"];
+    guideRequired?: true;
+    guideRequiredReasons?: GuideRequiredReason[];
   };
 }
 
+type GuideRequiredReason =
+  | "connector_required"
+  | "approval_required"
+  | "schema_truncated";
+
+/**
+ * Reasons discovery can determine without reading arguments or guessing at a
+ * task. Summary-only conventions remain an agent decision; hard requirements
+ * are explicit and machine-readable.
+ */
+function guideRequiredReasons(
+  connector: Connector,
+  tool: ToolDef,
+  schemaTruncated: boolean,
+): GuideRequiredReason[] | undefined {
+  if (!connectorGuide(connector)) return undefined;
+  const reasons: GuideRequiredReason[] = [];
+  if (connectorGuideRequired(connector)) reasons.push("connector_required");
+  if (!isExplicitlyReadOnly(tool)) reasons.push("approval_required");
+  if (schemaTruncated) reasons.push("schema_truncated");
+  return reasons.length > 0 ? reasons : undefined;
+}
+
 /**
  * Code-mode key metadata for one match. Each half is omitted when its schema
  * does not resolve to an object shape, so a program reads "no metadata, use the
@@ -237,6 +265,19 @@ function schemaKeyMetadata(
   };
 }
 
+/**
+ * The classified-failure subset a scoped search may echo: enough to tell a
+ * transient outage from one an operator must clear, and nothing more. Kept as
+ * its own type rather than `CallErrorDetails` so widening the call-path
+ * classifier cannot widen this discovery-surface field by accident.
+ */
+interface CatalogFailureDetail {
+  code: string;
+  message: string;
+  retryable: boolean;
+  retryAfterMs?: number;
+}
+
 export interface CatalogSearchPage {
   entries: CatalogSearchEntry[];
   total: number;
@@ -253,6 +294,12 @@ export interface CatalogSearchPage {
     connectorScope?: string;
     unknownConnector?: true;
     unavailableConnectorCount?: number;
+    /** Bounded typed failure for an explicitly scoped unavailable catalog. */
+    catalogError?: CatalogFailureDetail;
+    guide?: string;
+    guideSummary?: string;
+    guideRequired?: true;
+    guideRequiredReasons?: GuideRequiredReason[];
     guidance?: string;
   };
 }
@@ -262,6 +309,9 @@ export interface CatalogDescription {
   name?: string;
   description?: string;
   guide?: string;
+  guideSummary?: string;
+  guideRequired?: true;
+  guideRequiredReasons?: GuideRequiredReason[];
   inputSchema?: unknown;
   outputSchema?: unknown;
   annotations?: ToolDef["annotations"];
@@ -656,10 +706,19 @@ export class CatalogService {
         match.tool.description,
         args.fullDescriptions === true,
       );
+      const requiredReasons = guideRequiredReasons(
+        match.connector,
+        match.tool,
+        renderedInput?.truncated === true || renderedOutput?.truncated === true,
+      );
+      const guideSummary = connectorGuideSummary(match.connector);
       return {
         connector: match.connector,
         ...(connectorGuide(match.connector)
-          ? { guide: connectorSkillName(match.connector.id) }
+          ? {
+              guide: connectorSkillName(match.connector.id),
+              ...(guideSummary ? { guideSummary } : {}),
+            }
           : {}),
         tool: {
           name: match.tool.name,
@@ -697,6 +756,12 @@ export class CatalogService {
           ...(match.tool.annotations
             ? { annotations: match.tool.annotations }
             : {}),
+          ...(requiredReasons
+            ? {
+                guideRequired: true as const,
+                guideRequiredReasons: requiredReasons,
+              }
+            : {}),
         },
       };
     });
@@ -732,6 +797,27 @@ export class CatalogService {
     const unavailableCatalogs = catalogs.filter(
       (catalog) => catalog.status === "rejected",
     ).length;
+    // Named field by field rather than spread: `CallErrorDetails` also carries
+    // connector, operation, recovery, and nextAction, and a discovery read is
+    // not a call — widening the classifier must not silently widen what a
+    // catalog search hands back.
+    const scopedCatalogError = ((): CatalogFailureDetail | undefined => {
+      if (!scopedConnector || catalogs[0]?.status !== "rejected") {
+        return undefined;
+      }
+      const error = classifyCallError(
+        catalogs[0].reason,
+        "catalog_lookup_failed",
+      );
+      return {
+        code: error.code,
+        message: boundedEchoText(error.message),
+        retryable: error.retryable,
+        ...(error.retryAfterMs === undefined
+          ? {}
+          : { retryAfterMs: error.retryAfterMs }),
+      };
+    })();
     const safetyLabel =
       safety === "readOnly"
         ? "read-only "
@@ -740,6 +826,14 @@ export class CatalogService {
           : "";
     const filterRecovery =
       safety === "all" ? "" : " Change safety to inspect the other tools.";
+    const scopedGuide =
+      matches.length === 0 && scopedConnector && connectorGuide(scopedConnector)
+        ? {
+            guide: connectorSkillName(scopedConnector.id),
+            guideSummary: connectorGuideSummary(scopedConnector),
+            required: connectorGuideRequired(scopedConnector),
+          }
+        : undefined;
     const guidance =
       queryTerms.length === 0
         ? undefined
@@ -748,8 +842,10 @@ export class CatalogService {
             ? `Connector "${args.connector}" is not configured in this deployment. Omit connector to search all configured tools.`
             : scopedConnector
               ? unavailableCatalogs > 0
-                ? `Connector "${scopedConnector.id}" could not be searched because its catalog was unavailable. Retry later.`
-                : `No matching ${safetyLabel}capability was found on connector "${scopedConnector.id}". Refine terms or browse it with an empty query.${filterRecovery}`
+                ? `Connector "${scopedConnector.id}" could not be searched because its catalog was unavailable. Inspect catalogError for the typed reason and recovery detail.`
+                : scopedGuide?.required
+                  ? `No matching ${safetyLabel}capability was found on connector "${scopedConnector.id}". Fetch queryAnalysis.guide before calling, then refine terms or browse with an empty query.${filterRecovery}`
+                  : `No matching ${safetyLabel}capability was found on connector "${scopedConnector.id}". Refine terms or browse it with an empty query.${filterRecovery}`
               : unavailableCatalogs === 0
                 ? `No matching ${safetyLabel}capability is configured in this deployment. Refine terms, scope by connector, or browse with an empty query.${filterRecovery}`
                 : `No matching ${safetyLabel}capability was found in the catalogs that answered; ${unavailableCatalogs} connector catalog${unavailableCatalogs === 1 ? " was" : "s were"} unavailable. Refine terms, scope by connector, or browse with an empty query.${filterRecovery}`
@@ -789,6 +885,23 @@ export class CatalogService {
               ...(unavailableCatalogs > 0
                 ? { unavailableConnectorCount: unavailableCatalogs }
                 : {}),
+              ...(scopedCatalogError ? { catalogError: scopedCatalogError } : {}),
+              ...(scopedGuide
+                ? {
+                    guide: scopedGuide.guide,
+                    ...(scopedGuide.guideSummary
+                      ? { guideSummary: scopedGuide.guideSummary }
+                      : {}),
+                    ...(scopedGuide.required
+                      ? {
+                          guideRequired: true as const,
+                          guideRequiredReasons: [
+                            "connector_required" as const,
+                          ],
+                        }
+                      : {}),
+                  }
+                : {}),
               ...(guidance ? { guidance } : {}),
             },
           }
@@ -853,12 +966,27 @@ export class CatalogService {
         tool.description,
         args.fullDescriptions === true,
       );
+      const requiredReasons = guideRequiredReasons(
+        addressResolution.connector,
+        tool,
+        false,
+      );
+      const guideSummary = connectorGuideSummary(addressResolution.connector);
       return {
         address,
         name: tool.name,
         ...(description !== undefined ? { description } : {}),
         ...(connectorGuide(addressResolution.connector)
-          ? { guide: connectorSkillName(addressResolution.connector.id) }
+          ? {
+              guide: connectorSkillName(addressResolution.connector.id),
+              ...(guideSummary ? { guideSummary } : {}),
+            }
+          : {}),
+        ...(requiredReasons
+          ? {
+              guideRequired: true as const,
+              guideRequiredReasons: requiredReasons,
+            }
           : {}),
         inputSchema: renderSchema(input, format),
         ...(tool.outputSchema
@@ -877,6 +1005,7 @@ export function groupedSearchResult(page: CatalogSearchPage) {
     id: string;
     title?: string;
     guide?: string;
+    guideSummary?: string;
     tools: CatalogSearchEntry["tool"][];
   }> = [];
   const byConnector = new Map<string, (typeof groups)[number]>();
@@ -889,6 +1018,9 @@ export function groupedSearchResult(page: CatalogSearchPage) {
         id: entry.connector.id,
         ...(entry.connector.title ? { title: entry.connector.title } : {}),
         ...(entry.guide ? { guide: entry.guide } : {}),
+        ...(entry.guideSummary
+          ? { guideSummary: entry.guideSummary }
+          : {}),
         tools: [],
       };
       byConnector.set(entry.connector.id, group);
@@ -913,6 +1045,9 @@ export function flatSearchResult(page: CatalogSearchPage) {
     tools: page.entries.map((entry) => ({
       ...entry.tool,
       ...(entry.guide ? { guide: entry.guide } : {}),
+      ...(entry.guideSummary
+        ? { guideSummary: entry.guideSummary }
+        : {}),
     })),
     total: page.total,
     offset: page.offset,

package/src/connectors/api.ts

@@ -5,6 +5,7 @@ import type {
   ConnectorCredentialConfig,
   ConnectorCredentialValues,
   ConnectorContext,
+  ConnectorUsageGuide,
   CredentialTestResult,
   JsonSchema,
   ToolAnnotations,
@@ -41,10 +42,11 @@ export interface ApiOptions {
   /** Optional per-runtime downstream call-admission policy. */
   callAdmission?: ConnectorCallAdmissionPolicy;
   /**
-   * Optional agent-facing usage guide (markdown) served by the `skills`
-   * meta-tool as `connector:<id>`. See `Connector.usageGuide`.
+   * Optional agent-facing usage guide served by `skills` as
+   * `connector:<id>`. A string is markdown; the structured form adds bounded
+   * discovery metadata. See `Connector.usageGuide`.
    */
-  usageGuide?: string;
+  usageGuide?: string | ConnectorUsageGuide;
   /** Optional operator-managed credential exposed through ctx.credential and /credentials. */
   credential?: ConnectorCredentialConfig;
   /** Optional validation behind /credentials' Test action. */

package/src/connectors/remote-mcp.ts

@@ -21,6 +21,7 @@ import type {
   ConnectorCallAdmissionPolicy,
   ConnectorContext,
   ConnectorStatus,
+  ConnectorUsageGuide,
   Logger,
   ToolDef,
 } from "../types.js";
@@ -47,10 +48,11 @@ export interface RemoteMcpOptions {
   /** Optional per-runtime downstream call-admission policy. */
   callAdmission?: ConnectorCallAdmissionPolicy;
   /**
-   * Optional agent-facing usage guide (markdown) served by the `skills`
-   * meta-tool as `connector:<id>`. See `Connector.usageGuide`.
+   * Optional agent-facing usage guide served by `skills` as
+   * `connector:<id>`. A string is markdown; the structured form adds bounded
+   * discovery metadata. See `Connector.usageGuide`.
    */
-  usageGuide?: string;
+  usageGuide?: string | ConnectorUsageGuide;
   auth?: RemoteMcpAuth;
   /**
    * Downstream HTTP redirect policy. Defaults to `"none"`: every redirect is

package/src/execute.ts

@@ -28,6 +28,7 @@ import {
   InvocationService,
 } from "./invocation.js";
 import type { RegistryView } from "./registry.js";
+import { hasConnectorGuides } from "./skills.js";
 import { isExplicitlyReadOnly } from "./tool-safety.js";
 import type {
   Executor,
@@ -1272,20 +1273,22 @@ function discardedEmitsText(emitted: EmitCollector): string {
 
 const executeDescription = (
   emitBudgets: { maxBytes: number; maxBlocks: number },
-) => `The primary surface. Use for discovery beyond one lookup, two or more calls, dependent steps, loops, joins, branching, or reducing large results before they reach the model — connecta.search and connecta.describe browse and expand catalogs in the run, and connecta.batch handles independent calls. The exception is one call at an address already in hand: search_tools then one call_tool is cheaper than a program. Only tools explicitly annotated readOnlyHint: true are available. Each run is limited to ${EXECUTE_MAX_HOST_CALLS} host calls, connecta.batch to at most ${EXECUTE_MAX_BATCH_CALLS}; each host call has a ${EXECUTE_HOST_CALL_TIMEOUT_MS / 1_000}-second deadline.
+  connectorGuides: boolean,
+) => `Choose the route before discovery. Exactly one unknown-address read uses top-level search_tools then call_tool; a known address uses call_tool directly. This is the primary surface for everything wider. If any result will be reduced — even from one connector call — or work has dependent/multiple calls, loops, joins, or branches, make exactly one execute_code call that searches, selects, calls, and reduces before returning. A discovery-only program wastes its round trip: finish here, don't return catalog matches for a later call. Only readOnlyHint: true tools are available. Limits: ${EXECUTE_MAX_HOST_CALLS} host calls per run, ${EXECUTE_MAX_BATCH_CALLS} per batch, ${EXECUTE_HOST_CALL_TIMEOUT_MS / 1_000}-second host deadline.
 
 Write an async arrow function. It runs with NO network, filesystem, timers, or imports — the only capabilities are:
-- One global per connector: call every address <connectorId>.<toolName> from search_tools as <connectorId>.<toolName>(args), with a single args object matching the schema from connecta.describe. Names are sanitized to JS identifiers: characters outside [A-Za-z0-9_$] become "_" (my-service.get.thing → my_service.get_thing), leading digits get "_" prefixed, reserved words "_" appended.
+- Connector globals call <connectorId>.<toolName>(args) with one schema-matching args object. Sanitization: non-[A-Za-z0-9_$] → "_" (my-service.get.thing → my_service.get_thing), leading digit → "_" prefix, reserved word → "_" suffix.
 - connecta.call(address, args) and connecta.batch(calls) — call raw addresses. Every batch entry is { address, ok: true, data } or { address, ok: false, error, errorDetails: { code, retryable } }; destructure that, not a bare result.
-- connecta.search(args) and connecta.describe, taking { address: "<connectorId>.<toolName>" } or { addresses: [...] } — load and inspect request-local catalogs on demand. Use safety: "readOnly" to avoid advertising calls this sandbox cannot execute; it changes results, not authority. Matches carrying schemas also list inputKeys, requiredInputKeys, and outputKeys — the schema's own names, checkable before building args. A missing list means the schema is not a plain object shape, not that the tool has no fields — read the schema.
-- connecta.emit(block) — deliver MCP content beside the JSON return: exactly { type: "text", text } or { type: "image" | "audio", data (base64), mimeType }, nothing else. Blocks are appended on success only, spend no host calls, and are budgeted per run (${emitBudgets.maxBlocks} blocks, ${emitBudgets.maxBytes} serialized bytes); an over-budget or invalid emit throws catchably and accepts nothing.
-- connecta.ui(html, options?) — deliver one view. One argument is display-only; for live reads pass { reads: { name: { address, fixedArgs?, viewArgs? } } }, then markup calls connecta.read(name, args). Read-only is validated; fixed keys cannot be overridden, undeclared keys fail, and discovery, writes, and network stay unavailable. Success-only, no binding call cost, and one budget, not two (${emitBudgets.maxBytes} shared emit bytes); a second, over-budget, or invalid call throws catchably. The bytes stay out of context, so the model reads the return value, not the view: return the initial summary from its variables; later reads update only the view.
+- connecta.search(args) loads catalogs and must be followed by selection and calls in this program; set connector to the obvious id to load one, otherwise it loads all. For distinct operations, make separate short searches here. Require address/description to match the operation, then check requiredInputKeys, truncation, safety, and outputs; never take the first lexical or merely input-compatible match. Choose the best compatible match; do not require it to be the only match. Missing outputKeys means inspect outputSchema, not discard the candidate. Compatible means every required key has a task/prior-result value; do not prefer zero required keys. Put every requiredInputKey in call args. For dependencies, match an earlier outputKey to the later requiredInputKey. Use displayed names; [] means no required keys, not permission to invent args. Describe only a truncated/insufficient compact shape. Reducers use declared outputKeys, never guessed items/results roots. connecta.describe takes { address: "<connectorId>.<toolName>" } or { addresses: [...] }. Use safety: "readOnly" to avoid advertising calls this sandbox cannot execute; it changes results, not authority. A missing key list means a non-object shape, not no fields — read the schema.${connectorGuides ? " A match with guideRequired: true is a hard stop: do not call it; describing the exact schema clears only a schema_truncated reason, so for any other reason return the exact guide name, fetch that guide with the top-level skills tool, then write the informed call." : ""}
+- connecta.emit(block) — emit exactly { type: "text", text } or { type: "image" | "audio", data (base64), mimeType }. Success-only, no host call, ${emitBudgets.maxBlocks} blocks/${emitBudgets.maxBytes} bytes; invalid or over-budget throws before accepting.
+- connecta.ui(html, options?) — one success-only view. One arg is display-only; live reads use { reads: { name: { address, fixedArgs?, viewArgs? } } }, then markup calls connecta.read(name, args). Read admission is enforced; fixed keys cannot be overridden and undeclared keys fail. It shares the ${emitBudgets.maxBytes}-byte emit budget — one budget, not two; a second, over-budget, or invalid call throws catchably. Bytes stay out of context, so the model reads the return value, not the view: return the initial summary from its variables; later reads update only the view.
 - console.log(...) — captured and returned with the result.
 
-Tool calls return plain values (MCP text is JSON-parsed when possible) and throw on downstream errors — use try/catch. A thrown error carries only a message, so use connecta.batch when a program must tell a policy refusal from a transient failure. Never retry a failure whose retryable is false, and never retry a rate_limited one immediately — the sandbox has no timers. Return a JSON-serializable value; large results are truncated, so reduce data in code rather than return raw payloads.
+Dependent example (only when the second call requires a value returned by the first): async () => { const { tools } = await connecta.search({ query: "pipeline run job logs", safety: "readOnly", includeSchemas: "compact" }); const pick = (suffix) => { const match = tools.find((t) => t.address.endsWith(suffix)); if (!match) throw new Error("no tool for " + suffix); return match.address; }; const run = await connecta.call(pick(".get_run"), { runId: 42 }); const logs = await connecta.call(pick(".get_job_logs"), { jobId: run.failedJobId }); return [run, logs]; }
 
-Plain JavaScript only — no TypeScript syntax. For unknown-address dependent work, use one execute_code call: search inside it, read the compact schemas, continue to the dependent calls; do not return search results for a second execute_code call. Compact schemas are TypeScript-like strings, not JSON Schema objects: write the property names they display, never a positional guess or an invented alias.
-Dependent example (only when the second call requires a value returned by the first): async () => { const { tools } = await connecta.search({ query: "pipeline run job logs", safety: "readOnly", includeSchemas: "compact" }); const pick = (suffix) => { const match = tools.find((t) => t.address.endsWith(suffix)); if (!match) throw new Error("no tool for " + suffix); return match.address; }; const run = await connecta.call(pick(".get_run"), { runId: 42 }); const logs = await connecta.call(pick(".get_job_logs"), { jobId: run.failedJobId }); return [run, logs]; }`;
+Calls return plain values (JSON-parsing MCP text when possible) and throw; catch errors. A thrown error is only a message; connecta.batch tells a policy refusal from a transient failure. Never retry retryable: false or rate_limited immediately — there are no timers. Return JSON; large results truncate, so reduce instead of returning raw payloads.
+
+Plain JS, no TypeScript. Compact schemas are TypeScript-like, not JSON Schema: write the property names they display; never guess positions or aliases.`;
 
 /** Register the execute_code meta-tool. Only called when an executor is configured. */
 export function registerExecuteTool(
@@ -1340,11 +1343,16 @@ export function registerExecuteTool(
   server.registerTool(
     "execute_code",
     {
-      description: executeDescription(emitBudgets),
+      description: executeDescription(
+        emitBudgets,
+        hasConnectorGuides(registry.listConnectors()),
+      ),
       inputSchema: z.object({
         code: z
           .string()
-          .describe("A JavaScript async arrow function to execute."),
+          .describe(
+            "One complete JavaScript async arrow function. Consume search/describe results and finish the task inside it; returning catalog data for a later call spends a round trip and buys nothing.",
+          ),
         diagnostics: z
           .boolean()
           .optional()

package/src/index.ts

@@ -630,6 +630,7 @@ export type {
   ConnectorCredentialFieldConfig,
   ConnectorCredentialValues,
   ConnectorContext,
+  ConnectorUsageGuide,
   ConnectorStatus,
   CredentialTestResult,
   AdmittingExecutor,

package/src/meta-tools.ts

@@ -1372,7 +1372,7 @@ export function createMetaTools(
   };
 }
 
-const SEARCH_DESC = `Unknown address: use 2–4 distinctive action/object terms, not the full request; omit limit initially (default ${DEFAULT_SEARCH_LIMIT}) and page only if needed, up to ${MAX_SEARCH_LIMIT}. Partial and no-match searches report term coverage and next-step guidance. safety="readOnly" returns only calls available to call_tool and generated code; "approvalRequired" returns everything else; omitted or "all" preserves the complete catalog. This filters results, not authority. includeSchemas="compact" adds the input and any declared output shape, each bounded; plain-object schemas also expose inputKeys, requiredInputKeys, and outputKeys, while inputSchemaTruncated/outputSchemaTruncated mark shapes that need exact retrieval; matches also carry declared annotations. Call directly when sufficient. Empty query browses all.`;
+const SEARCH_DESC = `Use top-level search only for exactly one unreduced read, then call_tool, or for write-capable work, then call_destructive_tool. For read-only reduction, dependent or multiple calls, never search here: make one execute_code program that searches and calls. Use 2–4 distinctive action/object terms, not the full request; set connector to the obvious integration id to load one catalog instead of all; omit limit initially (default ${DEFAULT_SEARCH_LIMIT}), page to ${MAX_SEARCH_LIMIT} if needed. safety="readOnly" returns only calls available to call_tool/code; "approvalRequired" returns the rest; omitted/"all" returns all. This filters results, not authority. includeSchemas="compact" adds the input and any declared output shape, bounded; plain objects expose inputKeys, requiredInputKeys, and outputKeys; truncation flags mark incomplete shapes; matches also carry declared annotations. Require purpose/address fit plus compatible inputs, truncation, safety, and outputs — never the first lexical match. Empty query browses all.`;
 const CALL_DESC =
   'Use for ONE tool explicitly annotated readOnlyHint: true — the cheapest path for a single cold call. For two or more calls, dependent steps, loops, joins, or data reduction use execute_code, whose connecta.call and connecta.batch reach the same tools. Unannotated, write-capable, and destructive tools are refused and require call_destructive_tool. fields selects JSON dot-paths; traverse arrays with [] (for example results[].id). Misses return data plus `$connecta` feedback. 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 =
@@ -1396,9 +1396,11 @@ const SEARCH_WITH_DESCRIBE_DESC = `${SEARCH_DESC} Expand an ambiguous compact sh
  */
 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.',
+    " skills({}) also lists this deployment's scoped connector guides; fetch only an exact name listed there or carried by discovery, never one inferred from a connector id.",
   search:
-    " A connector group carrying `guide` has a usage guide; fetch it with skills({ name: <guide> }).",
+    " A result carrying `guide` also carries a bounded `guideSummary`. `guideRequired: true` is a hard stop: fetch that exact guide before calling. `guideRequiredReasons` explains why — `connector_required` and `approval_required` stand however you expand the schema; `schema_truncated` clears once describe returns the exact one. Otherwise fetch only when the summary names a connector convention relevant to the task. A complete, unambiguous read-only schema needs no otherwise-irrelevant guide fetch.",
+  destructive:
+    " Before a consequential call, inspect the address through discovery or describe and fetch any connector guide it names.",
 } as const;
 
 /** `base`, plus its guide note when any VISIBLE connector carries a guide. */
@@ -1533,7 +1535,11 @@ export function registerMetaTools(
   server.registerTool(
     "call_destructive_tool",
     {
-      description: CALL_DESTRUCTIVE_DESC,
+      description: describedFor(
+        registry,
+        CALL_DESTRUCTIVE_DESC,
+        "destructive",
+      ),
       inputSchema: z.object({
         ...CALL_INPUT_SCHEMA,
         // Bounded above, but with no lower bound: a model that sends `""` or

package/src/providers/mixpanel.ts

@@ -0,0 +1,220 @@
+import {
+  remoteMcp,
+  type RemoteMcpAuth,
+} from "../connectors/remote-mcp.js";
+import type {
+  Connector,
+  ConnectorCallAdmissionPolicy,
+  ToolDef,
+} from "../types.js";
+
+export type MixpanelRegion = "us" | "eu" | "in";
+
+export const MIXPANEL_MCP_ENDPOINTS: Readonly<
+  Record<MixpanelRegion, string>
+> = {
+  us: "https://mcp.mixpanel.com/mcp",
+  eu: "https://mcp-eu.mixpanel.com/mcp",
+  in: "https://mcp-in.mixpanel.com/mcp",
+};
+
+export interface MixpanelOptions {
+  /** Human-readable display name; defaults to "Mixpanel". */
+  title?: string;
+  /** Who should use this account and for what decisions. */
+  purpose: string;
+  /** Mixpanel data residency region. Defaults to "us". */
+  region?: MixpanelRegion;
+  /** OAuth by default; static headers support Mixpanel service accounts. */
+  auth?: RemoteMcpAuth;
+  /** Account-specific conventions appended to the maintained provider guide. */
+  instructions?: string;
+  /** Connector-specific inline result limit; omit to inherit the deployment. */
+  maxResultBytes?: number;
+}
+
+// Budget-only: a rejection computes its own retry-after from the window, and
+// declaring `retryAfterMs` here would be a queue setting without a queue —
+// which the admission controller refuses at construction.
+const MIXPANEL_ADMISSION: ConnectorCallAdmissionPolicy = {
+  rules: [
+    {
+      budget: {
+        kind: "rolling-window",
+        maxCalls: 600,
+        windowMs: 3_600_000,
+      },
+    },
+  ],
+};
+
+/** Tools whose official contract is observational rather than mutating. */
+const READ_ONLY_TOOLS = new Set([
+  "Run-Query",
+  "Get-Query-Schema",
+  "Get-Report",
+  "Display-Query",
+  "List-Dashboards",
+  "Get-Dashboard",
+  "Get-Business-Context",
+  "Get-Projects",
+  "List-Organizations",
+  "Get-Events",
+  "List-Properties",
+  "Get-Property-Values",
+  "Search-Entities",
+  "Get-Issues",
+  "Get-Lexicon-URL",
+  "Find-Duplicate-Groups",
+  "Get-Custom-Property",
+  "Get-Cohort",
+  "List-Cohorts",
+  "Describe-Cohort-Schema",
+  "Get-Lookup-Table",
+  "Get-Metric",
+  "List-Metrics",
+  "Get-User-Replays-Data",
+  "List-Experiments",
+  "Get-Experiment",
+  "Get-Experiment-Setup-Guidance",
+  "Get-Experiment-Results-Interpretation-Guidance",
+  "Explain-Experiment-Health-Check",
+  "Run-Experiment-Pre-Launch-Checks",
+  "Search-Prior-Experiments",
+  "List-Feature-Flags",
+  "Get-Feature-Flag",
+  "Get-Feature-Flag-Setup-Guidance",
+  "Get-Feature-Flag-Lifecycle-Guidance",
+]);
+
+/**
+ * The maintained write catalog. `"destructive"` tools modify or remove state
+ * that already exists; `"additive"` ones only bring something new into being.
+ * Both leave the read-only path — the distinction only decides whether the
+ * connection asserts `destructiveHint`, which shapes the host's approval copy.
+ */
+const WRITE_TOOLS: ReadonlyMap<string, "additive" | "destructive"> = new Map([
+  ["Create-Dashboard", "additive"],
+  ["Update-Dashboard", "destructive"],
+  ["Duplicate-Dashboard", "additive"],
+  ["Delete-Dashboard", "destructive"],
+  ["Edit-Event", "destructive"],
+  ["Edit-Property", "destructive"],
+  ["Bulk-Edit-Events", "destructive"],
+  ["Bulk-Edit-Properties", "destructive"],
+  ["Create-Tag", "additive"],
+  ["Rename-Tag", "destructive"],
+  ["Delete-Tag", "destructive"],
+  ["Dismiss-Issues", "destructive"],
+  ["Update-Business-Context", "destructive"],
+  ["Dismiss-Duplicate-Group", "destructive"],
+  ["Merge-Group", "destructive"],
+  ["Create-Custom-Property", "additive"],
+  ["Update-Custom-Property", "destructive"],
+  ["Create-Cohort", "additive"],
+  ["Update-Cohort", "destructive"],
+  ["Delete-Cohort", "destructive"],
+  ["Create-Lookup-Table", "additive"],
+  ["Update-Lookup-Table", "destructive"],
+  ["Create-Metric", "additive"],
+  ["Update-Metric", "destructive"],
+  ["Create-Experiment", "additive"],
+  ["Update-Experiment", "destructive"],
+  ["Create-Feature-Flag", "additive"],
+  ["Update-Feature-Flag", "destructive"],
+]);
+
+/**
+ * Fill in what the downstream leaves unsaid; never argue with what it says.
+ *
+ * A vetted classification may always tighten — that direction only ever routes
+ * more calls through `call_destructive_tool`. Loosening is the direction that
+ * needs the downstream's silence: an explicit `destructiveHint: true` or
+ * `readOnlyHint: false` on an allowlisted read name is the downstream telling
+ * us this release's allowlist is wrong, and it wins.
+ */
+function vettedSafety(definition: ToolDef): ToolDef {
+  const downstream = definition.annotations ?? {};
+  if (READ_ONLY_TOOLS.has(definition.name)) {
+    if (
+      downstream.destructiveHint === true ||
+      downstream.readOnlyHint === false
+    ) {
+      return definition;
+    }
+    return {
+      ...definition,
+      annotations: {
+        ...downstream,
+        readOnlyHint: true,
+        destructiveHint: downstream.destructiveHint ?? false,
+      },
+    };
+  }
+  if (WRITE_TOOLS.get(definition.name) === "destructive") {
+    return {
+      ...definition,
+      annotations: {
+        ...downstream,
+        readOnlyHint: false,
+        destructiveHint: true,
+      },
+    };
+  }
+  // Maintained additive creates and tools this release has never seen land
+  // here alike: not read-only, so the ordinary fail-closed path keeps them
+  // approval-visible, without claiming a create destroys anything.
+  return {
+    ...definition,
+    annotations: {
+      ...downstream,
+      readOnlyHint: false,
+    },
+  };
+}
+
+function usageGuide(purpose: string, instructions: string | undefined): string {
+  const accountInstructions = instructions?.trim();
+  return `# Mixpanel usage
+
+Account purpose: ${purpose}
+
+- Start with \`Get-Projects\`, then use \`Get-Business-Context\` for the selected project before interpreting its events or metrics.
+- Discover names with \`Get-Events\`, \`List-Properties\`, and \`Get-Property-Values\`; do not guess event or property spelling.
+- For a new analysis, fetch \`Get-Query-Schema\` before \`Run-Query\`. Reduce query results inside \`execute_code\` before returning them.
+- Use \`Get-Report\` when the request names an existing saved report. Use \`Run-Query\` for a new question.
+- Mixpanel limits MCP traffic to 600 requests per user per hour. Reuse discovery results within a run and avoid speculative fan-out.
+- Treat every create, update, edit, merge, dismiss, duplicate, or delete operation as a write. Connecta routes the maintained write catalog through \`call_destructive_tool\`; newly added tools also fail closed until classified.
+${
+    accountInstructions
+      ? `\n## Account instructions\n\n${accountInstructions}\n`
+      : ""
+  }`;
+}
+
+/** A maintained Mixpanel hosted-MCP connection. */
+export function mixpanel(id: string, options: MixpanelOptions): Connector {
+  const purpose = options.purpose.trim();
+  if (!purpose) {
+    throw new Error("mixpanel() requires a non-empty account purpose.");
+  }
+  const region = options.region ?? "us";
+  const connector = remoteMcp(id, {
+    url: MIXPANEL_MCP_ENDPOINTS[region],
+    title: options.title ?? "Mixpanel",
+    description: `Mixpanel product analytics — ${purpose}`,
+    auth: options.auth ?? { type: "oauth" },
+    requireHttps: true,
+    callAdmission: MIXPANEL_ADMISSION,
+    usageGuide: usageGuide(purpose, options.instructions),
+    ...(options.maxResultBytes !== undefined
+      ? { maxResultBytes: options.maxResultBytes }
+      : {}),
+  });
+  return {
+    ...connector,
+    async listTools(ctx) {
+      return (await connector.listTools(ctx)).map(vettedSafety);
+    },
+  };
+}