@segmentstream-cloud/ontology 0.26.1 → 0.27.0

package/README.md

@@ -353,6 +353,24 @@ built-in `agent_chat`: reading or changing it needs a permission that names it,
   exist, and on `allow`, which version 0.2 replaced. It warns on an action no role may run
   and on `*:*`.
 
+## Discover the ontology over MCP
+
+Since 0.27.0, agents use `describe` without arguments for a compact entity index and `discover`
+for keyword, literal substring, or fuzzy metadata search. Inspect `entity:lead`,
+`action:lead.change_status`, or `measure:sales.revenue` refs with `describe` for complete definitions.
+Entity inspection includes all property metadata, relationships, permitted generated and authored
+actions with their input contracts, and computable measures. Related entities stay references.
+
+Index and search results carry `hash` and `next_cursor`; pass the cursor as `after` only when more
+results are needed. Complete inspection is not paginated. An optional `expected_hash` detects a
+changed deployment. Stored schema visibility does not grant permission to read records or run
+operations. `tools/list` continues to expose the standard permission-filtered operation tools.
+
+The MCP `ontology://describe` resource is the first index page as JSON. `ontology://catalog`
+remains an explicit full manifest export; REST descriptions and CLI catalog rendering retain
+whole-catalog behavior. Custom prompts expecting the old full no-argument MCP description should
+switch to progressive inspection or explicitly request the full export.
+
 ## Serve the ontology
 
 ```ts

package/dist/action.d.ts

@@ -18,7 +18,9 @@ export interface ActionContext<Input, Prepared = undefined> extends PrepareConte
 /** What `prepare` may fail with: the action errors, and connection calls that failed. */
 export type PrepareError = ActionError | ConnectionError;
 /**
- * How an action behaves. Agents confirm destructive or irreversible actions before preparation.
+ * How an action behaves. Agents confirm destructive, irreversible or external actions before
+ * preparation. Actions with connections are external even when both safety hints are false.
+ * Permitted, routine reversible actions can run without confirmation.
  * Custom actions without safety labels require confirmation for backwards compatibility.
  * Idempotence does not decide whether confirmation is needed.
  */

package/dist/names.d.ts

@@ -27,7 +27,7 @@ export declare const RESERVED_ENTITY_NAMES: readonly ["aggregate", "graph", "sta
 /** The MCP tools of every stored entity's reads: `lead_find`, `lead_get` and `lead_history`. */
 export declare const MCP_READ_TOOLS: readonly ["find", "get", "history"];
 /** The MCP tools of the ontology as a whole. No entity tool can take them: they have no underscore. */
-export declare const MCP_GLOBAL_TOOLS: readonly ["describe", "me", "aggregate"];
+export declare const MCP_GLOBAL_TOOLS: readonly ["describe", "discover", "me", "aggregate"];
 /** The longest tool name that Claude and OpenAI accept. */
 export declare const MCP_TOOL_NAME_MAX_LENGTH = 64;
 /** The MCP tool of an entity's read or action: `lead_find`, `lead_change_status`. */

package/dist/names.js

@@ -66,7 +66,7 @@ export const RESERVED_ENTITY_NAMES = [
 /** The MCP tools of every stored entity's reads: `lead_find`, `lead_get` and `lead_history`. */
 export const MCP_READ_TOOLS = ["find", "get", "history"];
 /** The MCP tools of the ontology as a whole. No entity tool can take them: they have no underscore. */
-export const MCP_GLOBAL_TOOLS = ["describe", "me", "aggregate"];
+export const MCP_GLOBAL_TOOLS = ["describe", "discover", "me", "aggregate"];
 /** The longest tool name that Claude and OpenAI accept. */
 export const MCP_TOOL_NAME_MAX_LENGTH = 64;
 /** The MCP tool of an entity's read or action: `lead_find`, `lead_change_status`. */

package/dist/service/discovery-schemas.d.ts

@@ -0,0 +1,143 @@
+import { Schema } from "effect";
+export declare const DescribeInput: Schema.Struct<{
+    readonly ref: Schema.optionalKey<Schema.String>;
+    readonly after: Schema.optionalKey<Schema.String>;
+    readonly limit: Schema.optionalKey<Schema.Int>;
+    readonly expected_hash: Schema.optionalKey<Schema.String>;
+}>;
+export type DescribeInput = typeof DescribeInput.Type;
+export declare const DiscoverInput: Schema.Struct<{
+    readonly query: Schema.String;
+    readonly kind: Schema.optionalKey<Schema.Literals<readonly ["entity", "action", "measure"]>>;
+    readonly entity: Schema.optionalKey<Schema.String>;
+    readonly mode: Schema.optionalKey<Schema.Literals<readonly ["auto", "literal", "fuzzy"]>>;
+    readonly after: Schema.optionalKey<Schema.String>;
+    readonly limit: Schema.optionalKey<Schema.Int>;
+    readonly expected_hash: Schema.optionalKey<Schema.String>;
+}>;
+export type DiscoverInput = typeof DiscoverInput.Type;
+export declare const IndexEntry: Schema.Struct<{
+    readonly storage: Schema.Literals<readonly ["stored", "warehouse"]>;
+    readonly capabilities: Schema.Struct<{
+        readonly read_records: Schema.Boolean;
+        readonly run_actions: Schema.Boolean;
+        readonly aggregate: Schema.Boolean;
+    }>;
+    readonly ref: Schema.String;
+    readonly name: Schema.String;
+    readonly label: Schema.String;
+    readonly description: Schema.String;
+    readonly summary_truncated: Schema.Boolean;
+}>;
+export type IndexEntry = typeof IndexEntry.Type;
+export declare const SearchMatch: Schema.Struct<{
+    readonly kind: Schema.Literals<readonly ["entity", "action", "measure"]>;
+    readonly entity: Schema.optionalKey<Schema.String>;
+    readonly matched_on: Schema.$Array<Schema.Struct<{
+        readonly field: Schema.String;
+        readonly excerpt: Schema.String;
+    }>>;
+    readonly ref: Schema.String;
+    readonly name: Schema.String;
+    readonly label: Schema.String;
+    readonly description: Schema.String;
+    readonly summary_truncated: Schema.Boolean;
+}>;
+export type SearchMatch = typeof SearchMatch.Type;
+/** One object root for clients validating MCP structured content. Definitions are request data. */
+export declare const DescribeOutput: Schema.Struct<{
+    readonly hash: Schema.String;
+    readonly kind: Schema.Literals<readonly ["index", "entity", "action", "measure"]>;
+    readonly ref: Schema.optionalKey<Schema.String>;
+    readonly total: Schema.optionalKey<Schema.Int>;
+    readonly entities: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly storage: Schema.Literals<readonly ["stored", "warehouse"]>;
+        readonly capabilities: Schema.Struct<{
+            readonly read_records: Schema.Boolean;
+            readonly run_actions: Schema.Boolean;
+            readonly aggregate: Schema.Boolean;
+        }>;
+        readonly ref: Schema.String;
+        readonly name: Schema.String;
+        readonly label: Schema.String;
+        readonly description: Schema.String;
+        readonly summary_truncated: Schema.Boolean;
+    }>>>;
+    readonly next_cursor: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly entity: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly action: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly measure: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+}>;
+export declare const DiscoverOutput: Schema.Struct<{
+    readonly hash: Schema.String;
+    readonly kind: Schema.Literal<"search">;
+    readonly query: Schema.String;
+    readonly total: Schema.Int;
+    readonly matches: Schema.$Array<Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["entity", "action", "measure"]>;
+        readonly entity: Schema.optionalKey<Schema.String>;
+        readonly matched_on: Schema.$Array<Schema.Struct<{
+            readonly field: Schema.String;
+            readonly excerpt: Schema.String;
+        }>>;
+        readonly ref: Schema.String;
+        readonly name: Schema.String;
+        readonly label: Schema.String;
+        readonly description: Schema.String;
+        readonly summary_truncated: Schema.Boolean;
+    }>>;
+    readonly next_cursor: Schema.NullOr<Schema.String>;
+}>;
+export declare const DescribeToolOutput: Schema.Union<readonly [Schema.Struct<{
+    readonly hash: Schema.String;
+    readonly kind: Schema.Literals<readonly ["index", "entity", "action", "measure"]>;
+    readonly ref: Schema.optionalKey<Schema.String>;
+    readonly total: Schema.optionalKey<Schema.Int>;
+    readonly entities: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly storage: Schema.Literals<readonly ["stored", "warehouse"]>;
+        readonly capabilities: Schema.Struct<{
+            readonly read_records: Schema.Boolean;
+            readonly run_actions: Schema.Boolean;
+            readonly aggregate: Schema.Boolean;
+        }>;
+        readonly ref: Schema.String;
+        readonly name: Schema.String;
+        readonly label: Schema.String;
+        readonly description: Schema.String;
+        readonly summary_truncated: Schema.Boolean;
+    }>>>;
+    readonly next_cursor: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly entity: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly action: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly measure: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+}>, Schema.Top, Schema.Top, Schema.Top, Schema.Struct<{
+    readonly error: Schema.Literals<readonly ["invalid_cursor", "ontology_version_mismatch", "discovery_too_large"]>;
+    readonly detail: Schema.String;
+    readonly request_id: Schema.String;
+    readonly hash: Schema.optionalKey<Schema.String>;
+}>]>;
+export declare const DiscoverToolOutput: Schema.Union<readonly [Schema.Struct<{
+    readonly hash: Schema.String;
+    readonly kind: Schema.Literal<"search">;
+    readonly query: Schema.String;
+    readonly total: Schema.Int;
+    readonly matches: Schema.$Array<Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["entity", "action", "measure"]>;
+        readonly entity: Schema.optionalKey<Schema.String>;
+        readonly matched_on: Schema.$Array<Schema.Struct<{
+            readonly field: Schema.String;
+            readonly excerpt: Schema.String;
+        }>>;
+        readonly ref: Schema.String;
+        readonly name: Schema.String;
+        readonly label: Schema.String;
+        readonly description: Schema.String;
+        readonly summary_truncated: Schema.Boolean;
+    }>>;
+    readonly next_cursor: Schema.NullOr<Schema.String>;
+}>, Schema.Top, Schema.Top, Schema.Top, Schema.Struct<{
+    readonly error: Schema.Literals<readonly ["invalid_cursor", "ontology_version_mismatch", "discovery_too_large"]>;
+    readonly detail: Schema.String;
+    readonly request_id: Schema.String;
+    readonly hash: Schema.optionalKey<Schema.String>;
+}>]>;

package/dist/service/discovery-schemas.js

@@ -0,0 +1,80 @@
+import { Schema } from "effect";
+import { ErrorSchemas } from "./schemas.js";
+const Cursor = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(2048));
+const Hash = Schema.String.check(Schema.isPattern(/^sha256:[a-f0-9]{64}$/));
+const limit = (maximum) => Schema.Int.check(Schema.isBetween({ minimum: 1, maximum }));
+export const DescribeInput = Schema.Struct({
+    ref: Schema.optionalKey(Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256))),
+    after: Schema.optionalKey(Cursor),
+    limit: Schema.optionalKey(limit(100)),
+    expected_hash: Schema.optionalKey(Hash),
+});
+export const DiscoverInput = Schema.Struct({
+    query: Schema.String.check(Schema.makeFilter((value) => value.trim().length > 0 && Array.from(value).length <= 512
+        ? true
+        : "Use a nonblank query of at most 512 Unicode code points.", { toJsonSchema: () => ({ minLength: 1, maxLength: 512, pattern: "\\S" }) })),
+    kind: Schema.optionalKey(Schema.Literals(["entity", "action", "measure"])),
+    entity: Schema.optionalKey(Schema.String.check(Schema.isPattern(/^[a-z][a-z0-9_]*$/))),
+    mode: Schema.optionalKey(Schema.Literals(["auto", "literal", "fuzzy"])),
+    after: Schema.optionalKey(Cursor),
+    limit: Schema.optionalKey(limit(50)),
+    expected_hash: Schema.optionalKey(Hash),
+});
+const Capabilities = Schema.Struct({
+    read_records: Schema.Boolean,
+    run_actions: Schema.Boolean,
+    aggregate: Schema.Boolean,
+});
+const Summary = {
+    ref: Schema.String,
+    name: Schema.String,
+    label: Schema.String,
+    description: Schema.String,
+    summary_truncated: Schema.Boolean,
+};
+export const IndexEntry = Schema.Struct({
+    ...Summary,
+    storage: Schema.Literals(["stored", "warehouse"]),
+    capabilities: Capabilities,
+});
+export const SearchMatch = Schema.Struct({
+    ...Summary,
+    kind: Schema.Literals(["entity", "action", "measure"]),
+    entity: Schema.optionalKey(Schema.String),
+    matched_on: Schema.Array(Schema.Struct({ field: Schema.String, excerpt: Schema.String })),
+});
+/** One object root for clients validating MCP structured content. Definitions are request data. */
+export const DescribeOutput = Schema.Struct({
+    hash: Schema.String,
+    kind: Schema.Literals(["index", "entity", "action", "measure"]),
+    ref: Schema.optionalKey(Schema.String),
+    total: Schema.optionalKey(Schema.Int),
+    entities: Schema.optionalKey(Schema.Array(IndexEntry)),
+    next_cursor: Schema.optionalKey(Schema.NullOr(Schema.String)),
+    entity: Schema.optionalKey(Schema.Record(Schema.String, Schema.Json)),
+    action: Schema.optionalKey(Schema.Record(Schema.String, Schema.Json)),
+    measure: Schema.optionalKey(Schema.Record(Schema.String, Schema.Json)),
+});
+export const DiscoverOutput = Schema.Struct({
+    hash: Schema.String,
+    kind: Schema.Literal("search"),
+    query: Schema.String,
+    total: Schema.Int,
+    matches: Schema.Array(SearchMatch),
+    next_cursor: Schema.NullOr(Schema.String),
+});
+const DiscoveryFailureOutput = Schema.Struct({
+    error: Schema.Literals(["invalid_cursor", "ontology_version_mismatch", "discovery_too_large"]),
+    detail: Schema.String,
+    request_id: Schema.String,
+    hash: Schema.optionalKey(Schema.String),
+});
+// Some MCP clients validate structured tool errors as well as successful results.
+const failures = [
+    ErrorSchemas.invalidRequest,
+    ErrorSchemas.notFound,
+    ErrorSchemas.internal,
+    DiscoveryFailureOutput,
+];
+export const DescribeToolOutput = Schema.Union([DescribeOutput, ...failures]);
+export const DiscoverToolOutput = Schema.Union([DiscoverOutput, ...failures]);

package/dist/service/discovery-search.d.ts

@@ -0,0 +1,27 @@
+import type { DiscoverInput, SearchMatch } from "./discovery-schemas.js";
+export interface SearchField {
+    readonly path: string;
+    readonly text: string;
+    readonly weight: number;
+}
+export interface SearchDocument {
+    readonly summary: Omit<SearchMatch, "matched_on">;
+    readonly fields: ReadonlyArray<SearchField>;
+}
+export declare function normalizeSearch(text: string): string;
+/** Rank only caller-projected documents; forbidden fields never affect ranking or explanations. */
+export declare function searchDocuments(documents: ReadonlyArray<SearchDocument>, input: DiscoverInput): {
+    readonly name: string;
+    readonly description: string;
+    readonly label: string;
+    readonly kind: "entity" | "measure" | "action";
+    readonly ref: string;
+    readonly summary_truncated: boolean;
+    readonly matched_on: readonly {
+        readonly field: string;
+        readonly excerpt: string;
+    }[];
+    readonly entity?: string | undefined;
+}[];
+/** Bytewise canonical-name ordering is independent of a function instance's locale. */
+export declare function compareRefs(left: string, right: string): number;

package/dist/service/discovery-search.js

@@ -0,0 +1,95 @@
+export function normalizeSearch(text) {
+    return text.normalize("NFKC").toLowerCase().replace(/ß/g, "ss").replace(/ς/g, "σ").trim();
+}
+function tokens(text) {
+    const words = text.replace(/([\p{Ll}\d])([\p{Lu}])/gu, "$1 $2");
+    return normalizeSearch(words).match(/[\p{L}\p{N}]+/gu) ?? [];
+}
+/** Bounded optimal-string-alignment distance, including adjacent transpositions. */
+function closeToken(left, right) {
+    const a = Array.from(left);
+    const b = Array.from(right);
+    const maximum = a.length < 4 ? 0 : a.length < 8 ? 1 : 2;
+    if (maximum === 0 || Math.abs(a.length - b.length) > maximum) {
+        return false;
+    }
+    let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+    let beforePrevious = previous;
+    for (let row = 1; row <= a.length; row++) {
+        const current = [row];
+        for (let column = 1; column <= b.length; column++) {
+            current[column] = Math.min((previous[column] ?? 0) + 1, (current[column - 1] ?? 0) + 1, (previous[column - 1] ?? 0) + (a[row - 1] === b[column - 1] ? 0 : 1));
+            if (row > 1 && column > 1 && a[row - 1] === b[column - 2] && a[row - 2] === b[column - 1]) {
+                current[column] = Math.min(current[column] ?? 0, (beforePrevious[column - 2] ?? 0) + 1);
+            }
+        }
+        if (Math.min(...current) > maximum) {
+            return false;
+        }
+        beforePrevious = previous;
+        previous = current;
+    }
+    return (previous[b.length] ?? Infinity) <= maximum;
+}
+function excerpt(text, query) {
+    const position = normalizeSearch(text).indexOf(query);
+    const characterPosition = Array.from(text.slice(0, Math.max(0, position))).length;
+    const start = Math.max(0, characterPosition - 40);
+    return Array.from(text)
+        .slice(start, start + 160)
+        .join("");
+}
+/** Rank only caller-projected documents; forbidden fields never affect ranking or explanations. */
+export function searchDocuments(documents, input) {
+    const query = normalizeSearch(input.query);
+    const terms = [...new Set(tokens(input.query))];
+    const ranked = [];
+    for (const document of documents) {
+        if ((input.kind !== undefined && document.summary.kind !== input.kind) ||
+            (input.entity !== undefined && document.summary.entity !== input.entity)) {
+            continue;
+        }
+        const explanations = [];
+        const covered = new Set();
+        let best = 0;
+        for (const field of document.fields) {
+            const normalized = normalizeSearch(field.text);
+            const phrase = normalized.includes(query);
+            let tier = phrase ? (normalized === query ? 5 : 4) : 0;
+            if (input.mode !== "literal") {
+                const words = tokens(field.text);
+                for (const term of terms) {
+                    if (words.some((word) => word === term || word.startsWith(term))) {
+                        covered.add(term);
+                        tier = Math.max(tier, 3);
+                    }
+                    else if (words.some((word) => closeToken(term, word))) {
+                        covered.add(term);
+                        tier = Math.max(tier, 2);
+                    }
+                }
+            }
+            if (tier > 0) {
+                const score = tier * 1_000_000 + field.weight;
+                best = Math.max(best, score);
+                explanations.push({ field: field.path, excerpt: excerpt(field.text, query), score });
+            }
+        }
+        if (best > 0) {
+            explanations.sort((a, b) => b.score - a.score || a.field.localeCompare(b.field, "en"));
+            ranked.push({
+                match: {
+                    ...document.summary,
+                    matched_on: explanations.slice(0, 3).map(({ field, excerpt }) => ({ field, excerpt })),
+                },
+                score: best + covered.size * 10_000,
+            });
+        }
+    }
+    ranked.sort((a, b) => b.score - a.score || compareRefs(a.match.ref, b.match.ref));
+    return ranked.map(({ match }) => match);
+}
+/** Bytewise canonical-name ordering is independent of a function instance's locale. */
+export function compareRefs(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}

package/dist/service/discovery.d.ts

@@ -0,0 +1,25 @@
+import { type PermissionHolder } from "../permissions.js";
+import type { BuiltApi } from "./api.js";
+import type { DescribeInput, DiscoverInput } from "./discovery-schemas.js";
+import { type McpTool } from "./mcp/tools.js";
+type JsonObject = Readonly<Record<string, unknown>>;
+export declare const DISCOVERY_RESULT_BYTES: number;
+declare const DiscoveryError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "DiscoveryError";
+} & Readonly<A>;
+/** Expected metadata errors retain their public reason without exposing excluded definitions. */
+export declare class DiscoveryError extends DiscoveryError_base<{
+    readonly error: "invalid_request" | "invalid_cursor" | "ontology_version_mismatch" | "not_found" | "discovery_too_large";
+    readonly detail: string;
+    readonly hash?: string;
+}> {
+}
+/** Exactly the successful MCP result envelope, including JSON's escaped text representation. */
+export declare function discoveryResultBytes(result: JsonObject): number;
+/** Immutable deployment metadata; authorization and projections are recomputed for every caller. */
+export declare function createDiscovery(built: BuiltApi, tools: ReadonlyArray<McpTool>): {
+    describe(input: DescribeInput, principal: PermissionHolder): JsonObject;
+    discover(input: DiscoverInput, principal: PermissionHolder): JsonObject;
+};
+export type Discovery = ReturnType<typeof createDiscovery>;
+export {};

package/dist/service/discovery.js

@@ -0,0 +1,457 @@
+import { createHash } from "node:crypto";
+import { Data } from "effect";
+import { encodeManifest } from "../manifest.js";
+import { effectivePermissions, isAllowed, permissionOf, READ_VERB, } from "../permissions.js";
+import { measureDescription, measuresFor, modelMeasureDescription, modelMeasuresFor, reachesOf, } from "../render.js";
+import { compareRefs, normalizeSearch, searchDocuments, } from "./discovery-search.js";
+import { visibleTools } from "./mcp/tools.js";
+export const DISCOVERY_RESULT_BYTES = 16 * 1024;
+const WIRE_NAME = "[a-z][a-z0-9_]*";
+const REFERENCE_PATTERN = new RegExp(`^(?:${[
+    `entity:${WIRE_NAME}`,
+    `action:${WIRE_NAME}\\.${WIRE_NAME}`,
+    `measure:${WIRE_NAME}(?:\\.${WIRE_NAME})?`,
+].join("|")})$`);
+/** Expected metadata errors retain their public reason without exposing excluded definitions. */
+export class DiscoveryError extends Data.TaggedError("DiscoveryError") {
+}
+function object(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function digest(value) {
+    return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+function preview(text, maximum) {
+    return Array.from(text).slice(0, maximum).join("");
+}
+function summary(ref, name, label, description) {
+    const shortLabel = preview(label, 120);
+    const shortDescription = preview(description, 240);
+    return {
+        ref,
+        name,
+        label: shortLabel,
+        description: shortDescription,
+        summary_truncated: shortLabel !== label || shortDescription !== description,
+    };
+}
+/** Exactly the successful MCP result envelope, including JSON's escaped text representation. */
+export function discoveryResultBytes(result) {
+    return Buffer.byteLength(JSON.stringify({
+        content: [{ type: "text", text: JSON.stringify(result) }],
+        structuredContent: result,
+    }));
+}
+function checkHash(hash, expected) {
+    if (expected !== undefined && expected !== hash) {
+        throw new DiscoveryError({
+            error: "ontology_version_mismatch",
+            detail: "The ontology changed. Repeat the relevant discovery or inspection with the current hash.",
+            hash,
+        });
+    }
+}
+function invalidCursor() {
+    throw new DiscoveryError({
+        error: "invalid_cursor",
+        detail: "Restart this index or search; its cursor is invalid.",
+    });
+}
+function page(input) {
+    const scope = digest([...new Set(input.permissions)].sort(compareRefs));
+    const request = digest(input.request);
+    let start = 0;
+    if (input.after !== undefined) {
+        let cursor;
+        try {
+            if (!/^[A-Za-z0-9_-]+$/.test(input.after)) {
+                return invalidCursor();
+            }
+            cursor = JSON.parse(Buffer.from(input.after, "base64url").toString("utf8"));
+        }
+        catch (error) {
+            if (error instanceof DiscoveryError) {
+                throw error;
+            }
+            return invalidCursor();
+        }
+        if (!object(cursor) || typeof cursor.hash !== "string") {
+            return invalidCursor();
+        }
+        checkHash(input.hash, cursor.hash);
+        if (cursor.scope !== scope || cursor.request !== request || typeof cursor.last !== "string") {
+            return invalidCursor();
+        }
+        const position = input.items.findIndex(({ ref }) => ref === cursor.last);
+        if (position < 0) {
+            return invalidCursor();
+        }
+        start = position + 1;
+    }
+    const cursorAfter = (last) => Buffer.from(JSON.stringify({ hash: input.hash, scope, request, last })).toString("base64url");
+    const selected = [];
+    let result = input.result(selected, null);
+    for (const item of input.items.slice(start, start + input.limit)) {
+        const candidate = [...selected, item];
+        const more = start + candidate.length < input.items.length;
+        const next = input.result(candidate, more ? cursorAfter(item.ref) : null);
+        if (discoveryResultBytes(next) > DISCOVERY_RESULT_BYTES) {
+            if (selected.length === 0) {
+                throw new DiscoveryError({
+                    error: "discovery_too_large",
+                    detail: "This discovery entry exceeds the response budget.",
+                });
+            }
+            break;
+        }
+        selected.push(item);
+        result = next;
+    }
+    return result;
+}
+function textFields(value, prefix = "", weight = 10) {
+    return ["name", "label", "plural", "description"].flatMap((key) => {
+        const text = value[key];
+        return typeof text === "string"
+            ? [{ path: prefix + key, text, weight: key === "description" ? weight : weight + 10 }]
+            : [];
+    });
+}
+/** JSON Schema field descriptions, including nested properties and local definitions. */
+function inputFields(schema, prefix = "input") {
+    const fields = [];
+    for (const [key, value] of Object.entries(schema)) {
+        if (key === "description" && typeof value === "string") {
+            fields.push({ path: `${prefix}.description`, text: value, weight: 10 });
+        }
+        else if (key === "properties" && object(value)) {
+            for (const [name, property] of Object.entries(value)) {
+                fields.push({ path: `${prefix}.properties.${name}.name`, text: name, weight: 20 });
+                if (object(property)) {
+                    fields.push(...inputFields(property, `${prefix}.properties.${name}`));
+                }
+            }
+        }
+        else if (object(value)) {
+            fields.push(...inputFields(value, `${prefix}.${key}`));
+        }
+        else if (Array.isArray(value)) {
+            value.forEach((branch, index) => {
+                if (object(branch)) {
+                    fields.push(...inputFields(branch, `${prefix}.${key}.${index}`));
+                }
+            });
+        }
+    }
+    return fields;
+}
+/** Immutable deployment metadata; authorization and projections are recomputed for every caller. */
+export function createDiscovery(built, tools) {
+    const { manifest } = built.plan.ontology;
+    const wire = encodeManifest(manifest);
+    const wireEntities = new Map(wire.entities.map((entity) => [entity.name, entity]));
+    const actionDefinitions = new Map();
+    const incoming = new Map();
+    for (const source of manifest.entities) {
+        source.relationships.forEach((relationship, index) => {
+            const edges = incoming.get(relationship.to) ?? [];
+            edges.push({ source, relationship, index });
+            incoming.set(relationship.to, edges);
+        });
+    }
+    for (const tool of tools) {
+        if (tool.target.kind !== "action") {
+            continue;
+        }
+        const { planned, action } = tool.target;
+        actionDefinitions.set(`action:${planned.name}.${action.name}`, {
+            name: action.name,
+            entity: { ref: `entity:${planned.name}` },
+            tool_name: tool.name,
+            generated: action.generated,
+            description: action.action.description,
+            tool_description: tool.description,
+            permissions: tool.permissions,
+            input_schema: tool.inputSchema,
+            annotations: tool.annotations,
+            connections: action.action.connections.map(({ key, description }) => ({ key, description })),
+        });
+    }
+    function projection(principal) {
+        const permissions = effectivePermissions(principal);
+        const holder = { permissions };
+        const visibleEntities = new Map(manifest.entities
+            .filter((entity) => entity.source === undefined ||
+            isAllowed(entity.permissions?.read ?? permissionOf(entity.name, READ_VERB), holder))
+            .map((entity) => [entity.name, entity]));
+        const actions = new Map();
+        for (const tool of visibleTools(tools, principal)) {
+            if (tool.target.kind === "action") {
+                const ref = `action:${tool.target.planned.name}.${tool.target.action.name}`;
+                actions.set(ref, actionDefinitions.get(ref));
+            }
+        }
+        const measures = new Map();
+        for (const { name, entity, measure } of measuresFor(manifest, permissions)) {
+            const encoded = wireEntities.get(entity.name)?.measures;
+            measures.set(`measure:${name}`, {
+                ...encoded.find((candidate) => candidate.name === measure.name),
+                name,
+                entity: { ref: `entity:${entity.name}` },
+                explanation: measureDescription(entity, measure),
+            });
+        }
+        const model = wire.measures;
+        for (const measure of modelMeasuresFor(manifest, permissions)) {
+            measures.set(`measure:${measure.name}`, {
+                ...model?.find((candidate) => candidate.name === measure.name),
+                explanation: modelMeasureDescription(measure),
+                input_refs: measure.inputs.map((name) => `measure:${name}`),
+                computation: "Computed on the combined results of its input entity measures; " +
+                    "division by zero and missing inputs remain null.",
+            });
+        }
+        const actionOwners = new Set([...actions.keys()].map((ref) => ref.slice("action:".length).split(".")[0]));
+        const measureOwners = new Set([...measures.keys()].flatMap((ref) => ref.includes(".") ? [ref.slice("measure:".length).split(".")[0]] : []));
+        function capabilities(entity) {
+            return {
+                read_records: entity.source === undefined &&
+                    isAllowed(entity.permissions?.read ?? `${entity.name}:read`, holder),
+                run_actions: actionOwners.has(entity.name),
+                aggregate: measureOwners.has(entity.name),
+            };
+        }
+        function relationships(entity) {
+            const declared = entity.relationships.map((relationship, index) => ({
+                ...(wireEntities.get(entity.name)?.relationships)[index],
+                direction: "declared",
+                target: {
+                    ref: `entity:${relationship.to}`,
+                    inspectable: visibleEntities.has(relationship.to),
+                },
+            }));
+            const inverse = (incoming.get(entity.name) ?? []).flatMap(({ source, relationship, index }) => {
+                const encoded = (wireEntities.get(source.name)?.relationships)[index];
+                return [
+                    {
+                        name: relationship.inverse,
+                        inverse: relationship.name,
+                        to: source.name,
+                        cardinality: "many",
+                        optional: true,
+                        direction: "inverse",
+                        description: relationship.description,
+                        phrase: [relationship.phrase[1], relationship.phrase[0]],
+                        declaration: { entity: { ref: `entity:${source.name}` }, relationship: encoded },
+                        ...(relationship.on === undefined
+                            ? {}
+                            : {
+                                on: {
+                                    property: relationship.on.targetProperty,
+                                    target_property: relationship.on.property,
+                                },
+                            }),
+                        target: {
+                            ref: `entity:${source.name}`,
+                            inspectable: visibleEntities.has(source.name),
+                        },
+                    },
+                ];
+            });
+            return [...declared, ...inverse];
+        }
+        function entityDefinition(entity) {
+            return {
+                ...wireEntities.get(entity.name),
+                storage: entity.source === undefined ? "stored" : "warehouse",
+                capabilities: capabilities(entity),
+                relationships: relationships(entity),
+                actions: [...actions]
+                    .filter(([ref]) => ref.startsWith(`action:${entity.name}.`))
+                    .map(([ref, action]) => ({ ref, ...action })),
+                measures: [...measures]
+                    .filter(([ref]) => ref.startsWith(`measure:${entity.name}.`))
+                    .map(([ref, measure]) => ({ ref, ...measure })),
+                ...(measureOwners.has(entity.name)
+                    ? { aggregate_routes: reachesOf(manifest, entity.name, permissions) }
+                    : {}),
+            };
+        }
+        function measureDefinition(measure) {
+            if (!object(measure.entity)) {
+                return measure;
+            }
+            const owner = measure.entity.ref.slice("entity:".length);
+            return { ...measure, routes: reachesOf(manifest, owner, permissions) };
+        }
+        function documents() {
+            const documents = [];
+            for (const entity of visibleEntities.values()) {
+                const fields = textFields(entity, "", 50);
+                entity.properties.forEach((property) => {
+                    fields.push(...textFields(property, `properties.${property.name}.`));
+                    property.options?.forEach((option, index) => {
+                        fields.push(...textFields(option, `properties.${property.name}.options.${index}.`));
+                        fields.push({
+                            path: `properties.${property.name}.options.${index}.value`,
+                            text: option.value,
+                            weight: 20,
+                        });
+                    });
+                });
+                for (const relationship of relationships(entity)) {
+                    const prefix = `relationships.${relationship.name}.`;
+                    fields.push(...textFields(relationship, prefix));
+                    relationship.phrase.forEach((text, index) => {
+                        fields.push({ path: `${prefix}phrase.${index}`, text, weight: 10 });
+                    });
+                    const target = visibleEntities.get(relationship.to);
+                    if (target !== undefined) {
+                        fields.push({ path: `${prefix}target.label`, text: target.label, weight: 10 });
+                    }
+                }
+                documents.push({
+                    summary: {
+                        ...summary(`entity:${entity.name}`, entity.name, entity.label, entity.description),
+                        kind: "entity",
+                        entity: entity.name,
+                    },
+                    fields,
+                });
+            }
+            for (const [ref, action] of actions) {
+                const owner = action.entity.ref.slice("entity:".length);
+                const name = `${owner}.${action.name}`;
+                documents.push({
+                    summary: {
+                        ...summary(ref, name, name, action.description),
+                        kind: "action",
+                        entity: owner,
+                    },
+                    fields: [
+                        ...textFields({ ...action, name }, "", 50),
+                        ...inputFields(action.input_schema),
+                    ],
+                });
+            }
+            for (const [ref, measure] of measures) {
+                const owner = object(measure.entity)
+                    ? measure.entity.ref.slice("entity:".length)
+                    : undefined;
+                documents.push({
+                    summary: {
+                        ...summary(ref, measure.name, measure.label, measure.description),
+                        kind: "measure",
+                        ...(owner === undefined ? {} : { entity: owner }),
+                    },
+                    fields: textFields(measure, "", 50),
+                });
+            }
+            return documents;
+        }
+        return {
+            permissions,
+            visibleEntities,
+            actions,
+            measures,
+            capabilities,
+            entityDefinition,
+            measureDefinition,
+            documents,
+        };
+    }
+    return {
+        describe(input, principal) {
+            checkHash(manifest.hash, input.expected_hash);
+            const view = projection(principal);
+            if (input.ref !== undefined) {
+                if (input.after !== undefined || input.limit !== undefined) {
+                    throw new DiscoveryError({
+                        error: "invalid_request",
+                        detail: "Inspection is complete; omit after and limit when selecting a ref.",
+                    });
+                }
+                if (!REFERENCE_PATTERN.test(input.ref)) {
+                    throw new DiscoveryError({
+                        error: "invalid_request",
+                        detail: "Use an entity:, action:, or measure: reference with canonical wire names.",
+                    });
+                }
+                const [kind, name] = input.ref.split(":");
+                const entity = view.visibleEntities.get(name);
+                const definition = kind === "entity"
+                    ? entity === undefined
+                        ? undefined
+                        : view.entityDefinition(entity)
+                    : kind === "action"
+                        ? view.actions.get(input.ref)
+                        : view.measures.get(input.ref);
+                if (definition === undefined) {
+                    throw new DiscoveryError({
+                        error: "not_found",
+                        detail: "The ontology definition was not found.",
+                    });
+                }
+                return {
+                    hash: manifest.hash,
+                    kind,
+                    ref: input.ref,
+                    [kind]: kind === "measure" ? view.measureDefinition(definition) : definition,
+                };
+            }
+            const entries = [...view.visibleEntities.values()]
+                .map((entity) => ({
+                ...summary(`entity:${entity.name}`, entity.name, entity.label, entity.description),
+                storage: entity.source === undefined ? "stored" : "warehouse",
+                capabilities: view.capabilities(entity),
+            }))
+                .sort((a, b) => compareRefs(a.name, b.name));
+            const limit = input.limit ?? 100;
+            return page({
+                hash: manifest.hash,
+                permissions: view.permissions,
+                request: { kind: "index", limit },
+                after: input.after,
+                limit,
+                items: entries,
+                result: (entities, next_cursor) => ({
+                    hash: manifest.hash,
+                    kind: "index",
+                    total: entries.length,
+                    entities,
+                    next_cursor,
+                }),
+            });
+        },
+        discover(input, principal) {
+            checkHash(manifest.hash, input.expected_hash);
+            const view = projection(principal);
+            const matches = searchDocuments(view.documents(), input);
+            const total = matches.length;
+            const limit = input.limit ?? 10;
+            return page({
+                hash: manifest.hash,
+                permissions: view.permissions,
+                request: {
+                    kind: "search",
+                    query: normalizeSearch(input.query),
+                    filter: input.kind,
+                    entity: input.entity,
+                    mode: input.mode ?? "auto",
+                    limit,
+                },
+                after: input.after,
+                limit,
+                items: matches,
+                result: (matches, next_cursor) => ({
+                    hash: manifest.hash,
+                    kind: "search",
+                    query: input.query,
+                    total,
+                    matches,
+                    next_cursor,
+                }),
+            });
+        },
+    };
+}

package/dist/service/mcp/server.js

@@ -3,12 +3,13 @@ import { Cause, Data, Effect, Layer, Option, Schema, SchemaTransformation } from
 import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
 import { HttpApiBuilder, HttpApiSecurity } from "effect/unstable/httpapi";
 import { encodeManifest } from "../../manifest.js";
-import { isAllowed, permissionOf, READ_VERB } from "../../permissions.js";
 import { SCOPE_MISMATCH } from "../aggregate-platform.js";
 import { CurrentPrincipal, withPrincipal } from "../authentication.js";
 import { catalogFor } from "../catalog.js";
+import { createDiscovery, DiscoveryError } from "../discovery.js";
+import { DescribeInput, DiscoverInput } from "../discovery-schemas.js";
 import { ConversationSearch } from "../agent/conversations.js";
-import { describeCatalog, measureDescription, measuresFor, modelMeasureDescription, modelMeasuresFor, RECORDS_OR_AGGREGATES, } from "../../render.js";
+import { RECORDS_OR_AGGREGATES } from "../../render.js";
 import { RequestId, errorBodyForWire, expectedFailure, internalError, schemaIssues, } from "../errors.js";
 import { publicOrigin } from "../oauth/protocol.js";
 import { mcpChallenge, mcpResource } from "../oauth/server.js";
@@ -110,7 +111,7 @@ function errorText(body) {
 const VERSION_MISMATCH = "ontology_version_mismatch";
 /** What the agent reads instead of SegmentStream's detail, for refusals it must act on itself. */
 const AGENT_DETAILS = {
-    [VERSION_MISMATCH]: "The ontology changed; reload and try again: call describe for the current measures and " +
+    [VERSION_MISMATCH]: "The ontology changed; repeat the relevant discovery and inspection for current measure " +
         "names, then call aggregate with them.",
     [SCOPE_MISMATCH]: "SegmentStream would read entities this app's ontology service did not check, so it refused. " +
         "Retrying will not help: ask the app's operator to update @segmentstream-cloud/ontology and " +
@@ -151,16 +152,23 @@ function toolFailure(cause, requestId) {
         return Effect.failCause(cause);
     }
     const error = Option.getOrUndefined(Cause.findErrorOption(cause));
-    const expected = error instanceof InvalidArguments
+    const expected = error instanceof DiscoveryError
         ? {
-            error: "invalid_request",
-            detail: "The tool's arguments are invalid.",
+            error: error.error,
+            detail: error.detail,
             requestId,
-            issues: error.issues,
+            ...(error.hash === undefined ? {} : { hash: error.hash }),
         }
-        : error === undefined
-            ? undefined
-            : expectedFailure(error, requestId)?.body;
+        : error instanceof InvalidArguments
+            ? {
+                error: "invalid_request",
+                detail: "The tool's arguments are invalid.",
+                requestId,
+                issues: error.issues,
+            }
+            : error === undefined
+                ? undefined
+                : expectedFailure(error, requestId)?.body;
     const failure = expected === undefined
         ? Effect.logError("ontology.mcp.tool_failed", cause).pipe(Effect.annotateLogs({ requestId }), Effect.as(internalError(requestId).body))
         : Effect.succeed(expected);
@@ -170,15 +178,27 @@ function toolFailure(cause, requestId) {
         isError: true,
     }));
 }
-function runTool({ built, operations, aggregate, conversations, memberFiles }, tool, args, request) {
+function runTool({ built, operations, aggregate, conversations, discovery, memberFiles }, tool, args, request) {
     return Effect.gen(function* () {
         const { target } = tool;
         switch (target.kind) {
             case "describe": {
                 const principal = yield* CurrentPrincipal;
-                return {
-                    text: describeCatalog(built.plan.ontology.manifest, effectivePermissions(principal)),
-                };
+                const input = yield* decodeArguments(DescribeInput, args);
+                const result = yield* Effect.try({
+                    try: () => discovery.describe(input, principal),
+                    catch: (error) => error,
+                });
+                return structured(result);
+            }
+            case "discover": {
+                const principal = yield* CurrentPrincipal;
+                const input = yield* decodeArguments(DiscoverInput, args);
+                const result = yield* Effect.try({
+                    try: () => discovery.discover(input, principal),
+                    catch: (error) => error,
+                });
+                return structured(result);
             }
             case "aggregate": {
                 // The route's facade, as the caller: the arguments are the request body.
@@ -267,19 +287,20 @@ const RESOURCES = [
         uri: CATALOG_URI,
         name: "catalog",
         title: "The ontology's catalog",
-        description: "The manifest: entities, properties, relationships, actions and roles with their " +
-            "permissions, with only the actions you may run.",
+        description: "Explicit full manifest export, with current permission filtering. Can be large; " +
+            "use describe and discover for progressive metadata inspection.",
         mimeType: "application/json",
     },
     {
         uri: DESCRIBE_URI,
         name: "describe",
-        title: "The ontology as prose",
-        description: "What the describe tool returns: the entities you may read and the actions you may run.",
-        mimeType: "text/plain",
+        title: "The ontology entity index",
+        description: "The first compact entity-index page from describe. Continue with the describe tool using " +
+            "next_cursor as after, or discover relevant definitions.",
+        mimeType: "application/json",
     },
 ];
-function readResource({ built }, uri) {
+function readResource({ built, discovery }, uri) {
     return Effect.gen(function* () {
         const principal = yield* CurrentPrincipal;
         const { manifest } = built.plan.ontology;
@@ -296,8 +317,8 @@ function readResource({ built }, uri) {
                 return [
                     {
                         uri,
-                        mimeType: "text/plain",
-                        text: describeCatalog(manifest, effectivePermissions(principal)),
+                        mimeType: "application/json",
+                        text: JSON.stringify(discovery.describe({}, principal)),
                     },
                 ];
             default:
@@ -305,37 +326,22 @@ function readResource({ built }, uri) {
         }
     });
 }
-/**
- * What an agent learns when it connects: what the server is, the entities the caller may read, the
- * measures of every entity they may read, stored or warehouse-backed, and where to find the rest.
- */
-function instructions({ built }, permissions) {
-    const { manifest } = built.plan.ontology;
-    const readable = built.plan.entities
-        .filter(({ name, resolved }) => {
-        const definition = resolved.entity.definition;
-        return (definition.source === undefined && isAllowed(permissionOf(name, READ_VERB), { permissions }));
-    })
-        .map(({ name, resolved }) => `- ${name}: ${resolved.entity.definition.description}`);
-    const measures = [
-        ...measuresFor(manifest, permissions).map(({ name, entity, measure }) => `- ${name}: ${measureDescription(entity, measure)}`),
-        ...modelMeasuresFor(manifest, permissions).map((measure) => `- ${measure.name}: ${modelMeasureDescription(measure)}`),
-    ];
+/** Fixed guidance keeps initialization independent of ontology size. */
+function instructions() {
     return [
-        "This server is the app's ontology: the records the company works with and the actions " +
-            "that change them. Every change goes through an action, is checked against your " +
-            "permissions and is kept in history; nothing else writes.",
-        readable.length > 0
-            ? `Entities you may read, each with <entity>_find, <entity>_get and <entity>_history:\n${readable.join("\n")}`
-            : "You may read no entities.",
-        ...(measures.length > 0
-            ? [
-                `Measures you may aggregate with the aggregate tool; ${RECORDS_OR_AGGREGATES}:\n` +
-                    measures.join("\n"),
-            ]
-            : []),
-        "Call describe for the full catalog: properties, relationships, measures and the actions " +
-            "you may run.",
+        "This server is the app's ontology. Every change goes through an action, is checked " +
+            "against your current permissions, and is kept in history.",
+        "Call describe without ref for a compact entity index, or discover to search definitions. " +
+            "Inspect relevant entity:, action:, or measure: refs with describe for their complete definitions. " +
+            "Follow related refs only when needed; do not exhaust pages unrelated to the task.",
+        "Call me for the caller and permissions. Metadata visibility does not grant record access. " +
+            "Stored entities use <entity>_find, <entity>_get, <entity>_history and permitted action tools.",
+        `For analytics, ${RECORDS_OR_AGGREGATES}. Warehouse entities are read through aggregates.`,
+        "Use the authenticated tool annotations for confirmation: permitted actions classified as " +
+            "non-destructive and reversible need no extra approval. Destructive, irreversible or " +
+            "external actions (openWorldHint) require confirmation before preparation; idempotence " +
+            "alone does not waive it. Present confirmations in the conversation's language using " +
+            "action, entity, field and option labels and readable record titles, never tool names, ids or JSON.",
     ].join("\n\n");
 }
 function negotiate(requested) {
@@ -358,7 +364,7 @@ function dispatch(server, message, request) {
                         title: "Ontology",
                         version: server.built.plan.ontology.manifest.hash,
                     },
-                    instructions: instructions(server, effectivePermissions(principal)),
+                    instructions: instructions(),
                 });
             case "ping":
                 return rpcResult(id, {});
@@ -477,6 +483,7 @@ export function mcpLayer(options) {
         const server = {
             built: options.built,
             tools,
+            discovery: createDiscovery(options.built, tools),
             operations,
             memberFiles: memberFileOperations(backend, options.built.plan, operations),
             aggregate: options.aggregates.model,

package/dist/service/mcp/tools.d.ts

@@ -23,6 +23,8 @@ export type McpToolTarget = {
     readonly action: PlannedAction;
 } | {
     readonly kind: "describe";
+} | {
+    readonly kind: "discover";
 } | {
     readonly kind: "me";
 } | {
@@ -58,7 +60,7 @@ export interface McpTool {
  */
 export declare const ACTION_OPTIONS_ARGUMENT = "_options";
 /**
- * The MCP tools of an ontology: `describe` and `me`, `aggregate` when the ontology has measures,
+ * The MCP tools of an ontology: `describe`, `discover` and `me`, `aggregate` when the ontology has measures,
  * then for every stored entity `find`, `get`,
  * `history` and a tool per generated and authored action. Entities with a warehouse source have none,
  * as they have no record routes. Throws {@link InvalidOntology} when two tools share a name, which

package/dist/service/mcp/tools.js

@@ -1,15 +1,16 @@
 import { Schema } from "effect";
 import { AGGREGATE_NAME_PATTERN } from "../../aggregate-routes.js";
 import { InvalidOntology } from "../../diagnostics.js";
-import { isValueMatched, } from "../../manifest.js";
+import { isValueMatched } from "../../manifest.js";
 import { GENERATED_UPSERT_PREFIX, humanize, mcpToolName } from "../../names.js";
 import { isAllowed, permissionOf, READ_VERB } from "../../permissions.js";
 import { queryJsonSchema } from "../../query.js";
-import { measureDescription, measuresFor, modelMeasureDescription, modelMeasuresFor, RECORDS_OR_AGGREGATES, } from "../../render.js";
+import { measuresFor, modelMeasuresFor, RECORDS_OR_AGGREGATES } from "../../render.js";
 import { actionInputJsonSchema } from "../../runtime/generated-actions.js";
 import { uploadFields } from "../../storage/attachments.js";
 import { MEMBER_FILE_SCHEMAS } from "../member-files.js";
 import { actionDescription, requires } from "../descriptions.js";
+import { DescribeInput, DescribeToolOutput, DiscoverInput, DiscoverToolOutput, } from "../discovery-schemas.js";
 import { AGGREGATE_FILTER_OPERATORS, AGGREGATE_GRANULARITIES, AGGREGATE_LIMITS, AGGREGATE_PERIOD_UNITS, AGGREGATE_PERIODS, HistoryPage, MAXIMUM_TIMEZONE_LENGTH, Me, } from "../schemas.js";
 const DEFS = "#/$defs/";
 /**
@@ -226,15 +227,31 @@ function actionTool(planned, plannedAction) {
 const GLOBAL_TOOLS = [
     {
         name: "describe",
-        title: "Describe the ontology",
-        description: "The ontology as prose: the entities you may read, their properties and relationships, " +
-            "and the actions you may run, each with what it requires. Read it before working with " +
-            "records.",
-        inputSchema: NO_INPUT,
+        title: "Index or inspect the ontology",
+        description: "Without ref, a compact entity index; use next_cursor as after for more. With an entity:, " +
+            "action:, or measure: ref, its complete definition, including permitted operations. " +
+            "Inspect relevant entities before using unfamiliar fields; related entities remain references. " +
+            "Omit after and limit when inspecting a ref. Definitions do not grant record access.",
+        inputSchema: encodedJsonSchema(DescribeInput),
+        outputSchema: { type: "object", ...encodedJsonSchema(DescribeToolOutput) },
         annotations: READ,
         permissions: [],
         target: { kind: "describe" },
     },
+    {
+        name: "discover",
+        title: "Search ontology definitions",
+        description: "Find entities, permitted actions, and computable measures by their names and descriptions. " +
+            "Entity matches also search properties, options, and relationships. Auto ranks literal and " +
+            "token matches before spelling approximations; literal is a substring search with no regex. " +
+            "Results are summaries: inspect their refs with describe. Search reads metadata, not records. " +
+            "Use next_cursor as after only when more matches are relevant to the task.",
+        inputSchema: encodedJsonSchema(DiscoverInput),
+        outputSchema: { type: "object", ...encodedJsonSchema(DiscoverToolOutput) },
+        annotations: READ,
+        permissions: [],
+        target: { kind: "discover" },
+    },
     {
         name: "me",
         title: "Who am I",
@@ -274,23 +291,8 @@ const FILTER_VALUE_DESCRIPTION = "equals, notEquals: the value. gt, gte, lt, lte
     "dimension; a date covers whole days on a timestamp. contains, startsWith, endsWith: a " +
     "non-empty string, matched case-sensitively, without wildcards. inPeriod: a date or timestamp " +
     `dimension's period, today being the date in the request's timezone: ${PERIODS}`;
-/** One `anyOf` branch per measure: a JSON Schema `enum` cannot describe its values. */
-function measureChoice({ name, entity, measure }) {
-    return {
-        const: name,
-        description: `${entity.label} · ${measure.label} (${measure.unit}): ` +
-            measureDescription(entity, measure),
-    };
-}
-/** A measure of the model, by its bare name, read only by a caller who may read every input. */
-function modelMeasureChoice(measure) {
-    return {
-        const: measure.name,
-        description: `Model · ${measure.label} (${measure.unit}): ` + modelMeasureDescription(measure),
-    };
-}
 /** The aggregate tool's input for a caller: the request of `POST /api/ontology/aggregate`. */
-function aggregateInput({ measures, model }) {
+function aggregateInput() {
     return {
         type: "object",
         properties: {
@@ -299,7 +301,7 @@ function aggregateInput({ measures, model }) {
                 minItems: 1,
                 maxItems: AGGREGATE_LIMITS.measures,
                 uniqueItems: true,
-                items: { anyOf: [...measures.map(measureChoice), ...model.map(modelMeasureChoice)] },
+                items: { type: "string" },
                 description: "What to compute, as <entity>.<measure>, or a measure of the model by its name. " +
                     "Measures of several entities are each computed over their own entity's rows, then " +
                     "combined on the dimensions; a measure of the model is computed on the combined rows " +
@@ -398,20 +400,17 @@ const AGGREGATE_DESCRIPTION = "Numbers about the model: measures from one or sev
     "Requires reading every entity the request reads, path intermediates included, and every " +
     "entity a measure of the model reads. A measure of the model is named without an entity; a " +
     "filter must reach every entity it reads or none of them, unless its alignment gives an entity " +
-    "no counterpart. Call describe for the model's measures and relationships.";
+    "no counterpart. Use discover to find measures, then describe their refs or entity owners.";
 function aggregateTool(manifest) {
     return {
         name: "aggregate",
         title: "Aggregate measures",
         description: AGGREGATE_DESCRIPTION,
-        inputSchema: aggregateInput({
-            measures: measuresFor(manifest),
-            model: modelMeasuresFor(manifest),
-        }),
+        inputSchema: aggregateInput(),
         inputSchemaFor: (caller) => {
             const measures = measuresFor(manifest, caller.permissions);
             const model = modelMeasuresFor(manifest, caller.permissions);
-            return measures.length === 0 ? undefined : aggregateInput({ measures, model });
+            return measures.length === 0 && model.length === 0 ? undefined : aggregateInput();
         },
         annotations: READ,
         permissions: [],
@@ -419,7 +418,7 @@ function aggregateTool(manifest) {
     };
 }
 /**
- * The MCP tools of an ontology: `describe` and `me`, `aggregate` when the ontology has measures,
+ * The MCP tools of an ontology: `describe`, `discover` and `me`, `aggregate` when the ontology has measures,
  * then for every stored entity `find`, `get`,
  * `history` and a tool per generated and authored action. Entities with a warehouse source have none,
  * as they have no record routes. Throws {@link InvalidOntology} when two tools share a name, which

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/ontology",
-  "version": "0.26.1",
+  "version": "0.27.0",
   "description": "Define a SegmentStream workspace app's ontology: entities, relationships, roles and actions, written with Effect.",
   "license": "Apache-2.0",
   "author": "SegmentStream",