@zackbart/connecta 0.18.2 → 0.19.0

package/CHANGELOG.md

@@ -2,6 +2,102 @@
 
 All notable changes to this package are documented here.
 
+## 0.19.0 — 2026-08-25
+
+This release is a smaller, simpler package with no behavioral change for a
+deployment. A deployment can ignore everything here. The one packaging change
+is to maintainer history: six finished design records now live in the repository
+at their GitHub URLs instead of shipping in the npm package, cutting 91 KB from
+the package. The constitution is a fifth of its former size and keeps the same
+decisions. The core shrank from 28,756 to 27,417 lines and the tests from 42,341
+to 40,375 before the final pure-suite splits, which put 198 lines back — a
+copied preamble the next pass moves into a fixture (#479). Two dead paths
+finally left with the rest: write-only health accessors on `RegistryView`,
+residue from #179, and the v1 persisted-catalog reader, unreachable since
+2026-07-28.
+
+### Changed
+
+- **Providers.** Every Cloudflare tool is built through `cfTool()` and
+  `compact()`, so the repeated schema headers, scope properties, and
+  conditional-spread projections are written once; the paged-list, delete-ack,
+  and passthrough handlers are shared while every tool keeps its own literal
+  name, description, annotations, and schemas; the authentication `Symbol` is
+  gone because the scheme is fixed per connector (#465, #467). Cloudflare and
+  Notion share one Retry-After parser and one guarded JSON accessor, and
+  `callCloudflareContent` still classifies an unreadable error body by status
+  (#468). The hosted providers' comment blocks point at their guides instead of
+  restating them, and `api()` omits undefined options once (#463).
+- **Core.** Internal option types accept `undefined`, so `createConnecta` and
+  the registration helpers forward configuration directly (#462). One deadline,
+  sleep, and message helper serve the whole call path; `invocation.ts` lost its
+  hand-rolled controller, timer, and listener choreography with Retry-After,
+  per-phase timing, and health exclusion unchanged (#466). The catalog,
+  execution, remote-MCP, and operator-data paths share their failure envelopes,
+  close helpers, and result shapers (#472).
+- **Package and docs.** Six finished design records moved to
+  [`records/`](https://github.com/zackbart/connecta/tree/main/records), outside
+  the published files, and packed-link validation folded into the documentation
+  checker: −1,342 shipped lines, −91 KB (#464). `ethos.md` is the constitution
+  again — refusals, invariants, and what this is, at 1,188 words instead of
+  3,174, with every decision intact and a word cap replacing the line cap
+  (#471).
+- **Tests.** Shared fixtures replace 122 hand-rolled connector literals, five
+  fake downstream MCP servers, four fake Clerk auths, and the per-suite JSON-RPC
+  readers, deferreds, and logger spies (#473, #474, #475); the six
+  provider-registry suites are one `describe.each` and the provider error
+  mappings are tables (#476); repeated cases are `it.each` tables and the
+  duplicated assertion layers are gone (#477); the two largest suites are split
+  by subject (#460). Every `it()` and `expect()` that pins behavior survived —
+  3,400 fewer lines, no assertion dropped.
+- **Declined with numbers**, so nobody re-runs the experiment: a shared bounded
+  queue under both admission controllers measured −17 lines for a
+  hook-parameterised abstraction (#453); Effect as the core effect system
+  measured −4% of the core for +75 KB gzip and a second async paradigm (#470).
+
+### Removed
+
+- The write-only `HealthLog` and its `RegistryView` accessors: `healthFor`,
+  `hasObservedSuccess`, `observedSuccessAt`, and `peekTools`. `refreshTools` is
+  now private. This was residue from the removed proactive credential-liveness
+  design (#179).
+- The v1 persisted-catalog reader, unreachable since 2026-07-28. Its fixtures
+  now use the v2 manifest-and-chunks format.
+
+## 0.18.3 — 2026-08-25
+
+This change gives code mode memory where downstream MCP catalogs are usually
+silent: after a successful call with no declared output schema, Connecta keeps
+only the result's field names and broad JSON types and shows that open shape on
+later discovery. Nothing breaks, no deployment option changes, and providers
+that already declare outputs are untouched. The bounded cache lives only in the
+current process or Worker isolate and forgets each shape after 24 hours.
+Discovery still never executes a tool, and
+the new `outputSchemaSource: "observed"` marker is the warning label that keeps
+one or several real results from masquerading as a provider contract.
+
+### Added
+
+- **Passive observed output schemas.** Successful explicitly read-only calls
+  whose provider declared no `outputSchema` infer and merge an open
+  optional-field schema of names and broad JSON types. The inference retains no
+  arguments, scalar values, raw results, code, credentials, or errors. Property
+  names may be user-authored. It bounds depth, breadth, names, nodes, definition
+  size, and schema bytes; keeps at most 256 runtime entries; ties each entry to
+  the exact tool definition; and expires it after 24 hours.
+  Search and describe return it with `outputSchemaSource: "observed"`; a
+  declared schema always wins. Observation is synchronous, storage-free, and
+  unable to fail the call. The design follows new warm-cache evidence and two
+  live deployment audits: BePresent had 246/378 tools without output schemas,
+  while OneMany's maintained connectors declared all 90 (#442).
+
+### Changed
+
+- Removed the write-only per-connector call health log. Payload-free call
+  outcomes remain available through the activity sink.
+- Persisted catalog reads now require the version 2 manifest-and-chunks shape;
+  version 1 single-value catalogs are ignored and refreshed.
+
 ## 0.18.2 — 2026-08-18
 
 This patch closes the gap the RevenueCat rollout exposed on the same day 0.18.1
@@ -725,7 +821,7 @@ it back byte-identical after each operator mutation.
   constructor, schemas, validation path, handlers, and catalog service run, and
   only `fetch` is a probe that records the request (#350).
 - **Five provider audit reports** in
-  [`documentation/provider-audit.md`](./documentation/provider-audit.md), with
+  [`records/provider-audit.md`](https://github.com/zackbart/connecta/blob/main/records/provider-audit.md), with
   a verdict per convention, the fix for every miss, and every accepted
   exception recorded with its argument (#342).
 - **A convention test over the shipped surface.**
@@ -1508,7 +1604,7 @@ The channel is additive — a program that never calls `connecta.ui` produces th
 byte-for-byte prior response, no executor changed to carry it, and there is no
 new budget knob. Deployments do gain a `resources` capability and one extension
 declaration, both of which the design requires before any host will render.
-The design record is `documentation/mcp-ui-design.md` (#266); the contract is
+The design record is [`records/mcp-ui-design.md`](https://github.com/zackbart/connecta/blob/main/records/mcp-ui-design.md) (#266); the contract is
 `code-mode.md`'s "Rendered output" clauses (#277).
 
 ### Added
@@ -1584,7 +1680,7 @@ that cannot be projected, like a screenshot a downstream tool returned. The
 channel is additive: a program that never emits produces the byte-for-byte
 prior response, no executor changed to carry it, and deployments that do
 nothing get sensible budgets. The design record is
-`documentation/rich-output-design.md` (#267); the contract is `code-mode.md`'s
+[`records/rich-output-design.md`](https://github.com/zackbart/connecta/blob/main/records/rich-output-design.md) (#267); the contract is `code-mode.md`'s
 "Emitted output" clauses (#270).
 
 Agent recovery is now executable data instead of prose at the remaining local
@@ -1997,7 +2093,7 @@ tests confirm SDK v2 client close does not make it redundant.
   advances the existing generation fence before the SDK starts a fresh grant;
   pre-upgrade credentials bind in place on their first validated read.
 - **A complete in-repo disposition of the revision** in
-  [`documentation/mcp-2026-07-28.md`](./documentation/mcp-2026-07-28.md),
+  [`records/mcp-2026-07-28.md`](https://github.com/zackbart/connecta/blob/main/records/mcp-2026-07-28.md),
   including the declined and gated surfaces.
 
 ### Changed

package/README.md

@@ -67,6 +67,10 @@ Fifty issues in, one small object out. Your context window notices.
   classifications, imported one at a time.
 - **Let the agent work in code.** Search, chain, filter, join, and reduce
   inside the sandbox instead of round-tripping every call through the model.
+- **Teach undeclared result shapes by using them.** Successful read-only calls
+  retain field names and broad types in bounded runtime memory, never scalar
+  values, so later programs can project a remote MCP result its provider never
+  documented.
 - **Keep writes deliberate.** Only tools marked read-only run in a program.
   Everything else is a separate, visible call your client can gate.
 - **Run it where you like.** Node, a Docker container, or a Cloudflare Worker,

package/dist/catalog-service.d.ts

@@ -49,6 +49,7 @@ interface CatalogSearchEntry {
         description?: string;
         inputSchema?: unknown;
         outputSchema?: unknown;
+        outputSchemaSource?: "observed";
         inputSchemaTruncated?: true;
         outputSchemaTruncated?: true;
         inputKeys?: string[];
@@ -112,6 +113,7 @@ export interface CatalogDescription {
     guideRequiredReasons?: GuideRequiredReason[];
     inputSchema?: unknown;
     outputSchema?: unknown;
+    outputSchemaSource?: "observed";
     annotations?: ToolDef["annotations"];
     error?: string;
     errorDetails?: CatalogDescriptionFailureDetail;
@@ -149,13 +151,13 @@ export declare class CatalogService {
     private readonly loaded;
     private readonly loading;
     constructor(registry: RegistryView, baseUrl: string, options?: {
-        requestScope?: object;
-        probeTimeoutMs?: number;
-        concurrency?: number;
+        requestScope?: object | undefined;
+        probeTimeoutMs?: number | undefined;
+        concurrency?: number | undefined;
         /** The discovery route recovery records name. Default `search_tools`. */
-        searchRoute?: SearchRoute;
+        searchRoute?: SearchRoute | undefined;
         /** Runtime-owned tail for stale-while-revalidate catalog reads. */
-        defer?: DeferredWork;
+        defer?: DeferredWork | undefined;
     });
     /**
      * Send a caller back to discovery through the surface it can actually reach.
@@ -174,6 +176,10 @@ export declare class CatalogService {
     }, purpose: string): NonNullable<CallErrorDetails["nextAction"]>;
     loadConnector(id: string, callOptions?: ConnectorOperationOptions): Promise<ToolDef[]>;
     private loadForDiscovery;
+    private outputSchema;
+    private unknownAddressFailure;
+    private catalogLoadFailure;
+    private unknownToolFailure;
     resolveTool(address: string, callOptions?: ConnectorOperationOptions): Promise<CatalogResolution>;
     /**
      * Resolve the JavaScript-safe property used by a lazy code-mode namespace
@@ -203,6 +209,10 @@ export declare function groupedSearchResult(page: CatalogSearchPage): {
     };
     matchMode?: "partial";
     nextOffset?: number;
+    total: number;
+    offset: number;
+    limit: number;
+    hasMore: boolean;
     connectors: {
         id: string;
         title?: string;
@@ -210,10 +220,6 @@ export declare function groupedSearchResult(page: CatalogSearchPage): {
         guideSummary?: string;
         tools: CatalogSearchEntry["tool"][];
     }[];
-    total: number;
-    offset: number;
-    limit: number;
-    hasMore: boolean;
 };
 export declare function flatSearchResult(page: CatalogSearchPage): {
     queryAnalysis?: {
@@ -234,6 +240,10 @@ export declare function flatSearchResult(page: CatalogSearchPage): {
     };
     matchMode?: "partial";
     nextOffset?: number;
+    total: number;
+    offset: number;
+    limit: number;
+    hasMore: boolean;
     tools: {
         guideSummary?: string;
         guide?: string;
@@ -242,6 +252,7 @@ export declare function flatSearchResult(page: CatalogSearchPage): {
         description?: string;
         inputSchema?: unknown;
         outputSchema?: unknown;
+        outputSchemaSource?: "observed";
         inputSchemaTruncated?: true;
         outputSchemaTruncated?: true;
         inputKeys?: string[];
@@ -251,9 +262,5 @@ export declare function flatSearchResult(page: CatalogSearchPage): {
         guideRequired?: true;
         guideRequiredReasons?: GuideRequiredReason[];
     }[];
-    total: number;
-    offset: number;
-    limit: number;
-    hasMore: boolean;
 };
 export {};

package/dist/catalog-service.js

@@ -2,7 +2,7 @@ import { compactDiscoverySchema, compactSchema, lexicalCorpusStatistics, lexical
 import { mapSettledWithConcurrency, resolveDiscoveryConcurrency, } from "./concurrency.js";
 import { boundedEchoText, classifyCallError, framingError, } from "./errors.js";
 import { connectorGuide, connectorGuideRequired, connectorGuideSummary, connectorSkillName, } from "./skills.js";
-import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs, withAbortableTimeout, } from "./timeout.js";
+import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs, withDeadline, } from "./timeout.js";
 import { isExplicitlyReadOnly } from "./tool-safety.js";
 export const DEFAULT_SEARCH_LIMIT = 8;
 export const MAX_SEARCH_LIMIT = 100;
@@ -261,22 +261,58 @@ export class CatalogService {
         return loading;
     }
     loadForDiscovery(id, label) {
-        return withAbortableTimeout((signal) => this.loadConnector(id, {
+        return withDeadline((signal) => this.loadConnector(id, {
             signal,
             timeoutMs: this.probeTimeoutMs,
-        }), this.probeTimeoutMs, label);
+        }), {
+            timeoutMs: this.probeTimeoutMs,
+            timeoutError: new Error(`${label} timed out after ${this.probeTimeoutMs}ms`),
+        });
+    }
+    outputSchema(connectorId, tool) {
+        if (tool.outputSchema)
+            return { schema: tool.outputSchema };
+        const observed = this.registry.observedOutputSchema(connectorId, tool);
+        return observed
+            ? { schema: observed, source: "observed" }
+            : {};
+    }
+    unknownAddressFailure(address, query) {
+        return {
+            ok: false,
+            error: {
+                ...framingError("unknown_address", `Unknown address "${boundedEchoText(address)}"`),
+                nextAction: this.searchRecovery({ query: recoveryQuery(query) }, "Find the configured canonical address before retrying."),
+            },
+            catalogMs: 0,
+        };
+    }
+    catalogLoadFailure(cause, started, connector, toolName) {
+        return {
+            ok: false,
+            error: classifyCallError(cause, "catalog_lookup_failed"),
+            catalogMs: Date.now() - started,
+            connector,
+            toolName,
+            cause,
+        };
+    }
+    unknownToolFailure(toolName, connector, started) {
+        return {
+            ok: false,
+            error: {
+                ...framingError("unknown_tool", `Unknown tool "${boundedEchoText(toolName)}" on connector "${connector.id}"`),
+                nextAction: this.searchRecovery({ query: recoveryQuery(toolName), connector: connector.id }, "Find the connector's current canonical tool address."),
+            },
+            catalogMs: Date.now() - started,
+            connector,
+            toolName,
+        };
     }
     async resolveTool(address, callOptions = {}) {
         const resolved = this.registry.resolveAddress(address);
         if (!resolved) {
-            return {
-                ok: false,
-                error: {
-                    ...framingError("unknown_address", `Unknown address "${boundedEchoText(address)}"`),
-                    nextAction: this.searchRecovery({ query: recoveryQuery(address) }, "Find the configured canonical address before retrying."),
-                },
-                catalogMs: 0,
-            };
+            return this.unknownAddressFailure(address, address);
         }
         const started = Date.now();
         let tools;
@@ -284,30 +320,11 @@ export class CatalogService {
             tools = await this.loadConnector(resolved.connector.id, callOptions);
         }
         catch (cause) {
-            return {
-                ok: false,
-                error: classifyCallError(cause, "catalog_lookup_failed"),
-                catalogMs: Date.now() - started,
-                connector: resolved.connector,
-                toolName: resolved.toolName,
-                cause,
-            };
+            return this.catalogLoadFailure(cause, started, resolved.connector, resolved.toolName);
         }
         const definition = tools.find((tool) => tool.name === resolved.toolName);
         if (!definition) {
-            return {
-                ok: false,
-                error: {
-                    ...framingError("unknown_tool", `Unknown tool "${boundedEchoText(resolved.toolName)}" on connector "${resolved.connector.id}"`),
-                    nextAction: this.searchRecovery({
-                        query: recoveryQuery(resolved.toolName),
-                        connector: resolved.connector.id,
-                    }, "Find the connector's current canonical tool address."),
-                },
-                catalogMs: Date.now() - started,
-                connector: resolved.connector,
-                toolName: resolved.toolName,
-            };
+            return this.unknownToolFailure(resolved.toolName, resolved.connector, started);
         }
         return {
             ok: true,
@@ -327,14 +344,7 @@ export class CatalogService {
     async resolveToolAlias(connectorId, alias, aliasFor, callOptions = {}) {
         const connector = this.registry.getConnector(connectorId);
         if (!connector) {
-            return {
-                ok: false,
-                error: {
-                    ...framingError("unknown_address", `Unknown address "${boundedEchoText(`${connectorId}.${alias}`)}"`),
-                    nextAction: this.searchRecovery({ query: recoveryQuery(alias) }, "Find the configured canonical address before retrying."),
-                },
-                catalogMs: 0,
-            };
+            return this.unknownAddressFailure(`${connectorId}.${alias}`, alias);
         }
         const started = Date.now();
         let tools;
@@ -342,27 +352,11 @@ export class CatalogService {
             tools = await this.loadConnector(connector.id, callOptions);
         }
         catch (cause) {
-            return {
-                ok: false,
-                error: classifyCallError(cause, "catalog_lookup_failed"),
-                catalogMs: Date.now() - started,
-                connector,
-                toolName: alias,
-                cause,
-            };
+            return this.catalogLoadFailure(cause, started, connector, alias);
         }
         const [definition, ...collisions] = tools.filter((tool) => aliasFor(tool.name) === alias);
         if (!definition) {
-            return {
-                ok: false,
-                error: {
-                    ...framingError("unknown_tool", `Unknown tool "${boundedEchoText(alias)}" on connector "${connector.id}"`),
-                    nextAction: this.searchRecovery({ query: recoveryQuery(alias), connector: connector.id }, "Find the connector's current canonical tool address."),
-                },
-                catalogMs: Date.now() - started,
-                connector,
-                toolName: alias,
-            };
+            return this.unknownToolFailure(alias, connector, started);
         }
         if (collisions.length > 0) {
             const names = [definition, ...collisions]
@@ -486,16 +480,20 @@ export class CatalogService {
                 a.order - b.order);
         });
         const pageMatches = matches.slice(offset, offset + limit);
+        const withSchemas = args.includeSchemas;
         const entries = pageMatches.map((match) => {
+            const output = withSchemas
+                ? this.outputSchema(match.connector.id, match.tool)
+                : {};
             const input = match.tool.inputSchema ?? { type: "object" };
-            const renderedInput = args.includeSchemas
-                ? renderSearchSchema(input, args.includeSchemas)
+            const renderedInput = withSchemas
+                ? renderSearchSchema(input, withSchemas)
                 : undefined;
-            const renderedOutput = args.includeSchemas && match.tool.outputSchema
-                ? renderSearchSchema(match.tool.outputSchema, args.includeSchemas)
+            const renderedOutput = withSchemas && output.schema
+                ? renderSearchSchema(output.schema, withSchemas)
                 : undefined;
-            const schemaKeys = args.includeSchemas && args.includeSchemaKeys
-                ? schemaKeyMetadata(input, match.tool.outputSchema)
+            const schemaKeys = withSchemas && args.includeSchemaKeys
+                ? schemaKeyMetadata(input, output.schema)
                 : undefined;
             const description = summarizeDiscoveryDescription(match.tool.description, args.fullDescriptions === true);
             const requiredReasons = guideRequiredReasons(match.connector, match.tool, renderedInput?.truncated === true || renderedOutput?.truncated === true);
@@ -512,7 +510,7 @@ export class CatalogService {
                     name: match.tool.name,
                     address: `${match.connector.id}.${match.tool.name}`,
                     ...(description !== undefined ? { description } : {}),
-                    ...(args.includeSchemas
+                    ...(withSchemas
                         ? {
                             inputSchema: renderedInput?.schema,
                         }
@@ -520,11 +518,14 @@ export class CatalogService {
                     ...(renderedInput?.truncated
                         ? { inputSchemaTruncated: true }
                         : {}),
-                    ...(args.includeSchemas && match.tool.outputSchema
+                    ...(withSchemas && output.schema
                         ? {
                             outputSchema: renderedOutput?.schema,
                         }
                         : {}),
+                    ...(withSchemas && output.source
+                        ? { outputSchemaSource: output.source }
+                        : {}),
                     ...(renderedOutput?.truncated
                         ? { outputSchemaTruncated: true }
                         : {}),
@@ -657,41 +658,46 @@ export class CatalogService {
             (queryTerms.length > 0
                 ? matchMode === "partial"
                 : unknownConnectorGuidance !== undefined || unavailableCatalogs > 0);
-        const guidance = unsearchableQuery
-            ? (unknownConnectorGuidance ??
-                (scopedConnector && unavailableCatalogs > 0
+        const searchGuidance = () => {
+            if (unknownConnectorGuidance)
+                return unknownConnectorGuidance;
+            if (unsearchableQuery) {
+                return scopedConnector && unavailableCatalogs > 0
                     ? `Connector "${scopedConnector.id}" could not be searched because its catalog was unavailable. Inspect catalogError for the typed reason and recovery detail.`
-                    : "The query contained no searchable lexical terms. Use 2–4 ASCII action/object terms, or browse with an empty query."))
-            : queryTerms.length === 0
-                ? // A browse has no terms to advise about, so it stays silent unless
-                    // the scope itself failed: the guidance on a scoped miss recommends
-                    // browsing with an empty query, and that advice must not lead into a
-                    // dead end that looks like a connector with no tools.
-                    (unknownConnectorGuidance ??
-                        (unavailableCatalogs === 0
-                            ? undefined
-                            : scopedConnector
-                                ? `Connector "${scopedConnector.id}" could not be browsed because its catalog was unavailable. Inspect catalogError for the typed reason and recovery detail.`
-                                : `${unavailableCatalogs} connector catalog${unavailableCatalogs === 1 ? " was" : "s were"} unavailable, so this browse is incomplete. Scope by connector to see the typed reason.`))
-                : matches.length === 0
-                    ? (unknownConnectorGuidance ??
-                        (scopedConnector
-                            ? unavailableCatalogs > 0
-                                ? `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}`
-                            : (identityGuidance ??
-                                (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}`))))
-                    : matchMode === "partial"
-                        ? scopedConnector
-                            ? `No single tool on connector "${scopedConnector.id}" matched every term. Split distinct intents into separate searches.`
-                            : unavailableCatalogs === 0
-                                ? "No single tool matched every term. Split distinct intents into separate searches."
-                                : "No single tool matched every term in the catalogs that answered. Split distinct intents into separate searches."
-                        : undefined;
+                    : "The query contained no searchable lexical terms. Use 2–4 ASCII action/object terms, or browse with an empty query.";
+            }
+            if (queryTerms.length === 0) {
+                if (unavailableCatalogs === 0)
+                    return undefined;
+                return scopedConnector
+                    ? `Connector "${scopedConnector.id}" could not be browsed because its catalog was unavailable. Inspect catalogError for the typed reason and recovery detail.`
+                    : `${unavailableCatalogs} connector catalog${unavailableCatalogs === 1 ? " was" : "s were"} unavailable, so this browse is incomplete. Scope by connector to see the typed reason.`;
+            }
+            if (matches.length === 0) {
+                if (scopedConnector) {
+                    if (unavailableCatalogs > 0) {
+                        return `Connector "${scopedConnector.id}" could not be searched because its catalog was unavailable. Inspect catalogError for the typed reason and recovery detail.`;
+                    }
+                    return 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}`;
+                }
+                if (identityGuidance)
+                    return identityGuidance;
+                return 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}`;
+            }
+            if (matchMode !== "partial")
+                return undefined;
+            if (scopedConnector) {
+                return `No single tool on connector "${scopedConnector.id}" matched every term. Split distinct intents into separate searches.`;
+            }
+            return unavailableCatalogs === 0
+                ? "No single tool matched every term. Split distinct intents into separate searches."
+                : "No single tool matched every term in the catalogs that answered. Split distinct intents into separate searches.";
+        };
+        const guidance = searchGuidance();
         return {
             entries,
             total: matches.length,
@@ -813,6 +819,7 @@ export class CatalogService {
                 };
             }
             const input = tool.inputSchema ?? { type: "object" };
+            const output = this.outputSchema(addressResolution.connector.id, tool);
             const description = summarizeDescription(tool.description, args.fullDescriptions === true);
             const requiredReasons = guideRequiredReasons(addressResolution.connector, tool, false);
             const guideSummary = connectorGuideSummary(addressResolution.connector);
@@ -833,16 +840,28 @@ export class CatalogService {
                     }
                     : {}),
                 inputSchema: renderSchema(input, format),
-                ...(tool.outputSchema
+                ...(output.schema
                     ? {
-                        outputSchema: renderSchema(tool.outputSchema, format),
+                        outputSchema: renderSchema(output.schema, format),
                     }
                     : {}),
+                ...(output.source ? { outputSchemaSource: output.source } : {}),
                 ...(tool.annotations ? { annotations: tool.annotations } : {}),
             };
         });
     }
 }
+function pageTail(page) {
+    return {
+        total: page.total,
+        offset: page.offset,
+        limit: page.limit,
+        hasMore: page.hasMore,
+        ...(page.nextOffset !== undefined ? { nextOffset: page.nextOffset } : {}),
+        ...(page.matchMode ? { matchMode: page.matchMode } : {}),
+        ...(page.queryAnalysis ? { queryAnalysis: page.queryAnalysis } : {}),
+    };
+}
 export function groupedSearchResult(page) {
     const groups = [];
     const byConnector = new Map();
@@ -868,13 +887,7 @@ export function groupedSearchResult(page) {
     }
     return {
         connectors: groups,
-        total: page.total,
-        offset: page.offset,
-        limit: page.limit,
-        hasMore: page.hasMore,
-        ...(page.nextOffset !== undefined ? { nextOffset: page.nextOffset } : {}),
-        ...(page.matchMode ? { matchMode: page.matchMode } : {}),
-        ...(page.queryAnalysis ? { queryAnalysis: page.queryAnalysis } : {}),
+        ...pageTail(page),
     };
 }
 export function flatSearchResult(page) {
@@ -886,12 +899,6 @@ export function flatSearchResult(page) {
                 ? { guideSummary: entry.guideSummary }
                 : {}),
         })),
-        total: page.total,
-        offset: page.offset,
-        limit: page.limit,
-        hasMore: page.hasMore,
-        ...(page.nextOffset !== undefined ? { nextOffset: page.nextOffset } : {}),
-        ...(page.matchMode ? { matchMode: page.matchMode } : {}),
-        ...(page.queryAnalysis ? { queryAnalysis: page.queryAnalysis } : {}),
+        ...pageTail(page),
     };
 }