@segmentstream-cloud/ontology 0.12.0 → 0.13.0

package/dist/service/handlers.js

@@ -3,11 +3,12 @@ import { Effect, Layer, Schema } from "effect";
 import { HttpApiBuilder, OpenApi } from "effect/unstable/httpapi";
 import { STORAGE_GROUP } from "../storage/api.js";
 import { Conflict } from "../errors.js";
+import { isValueMatched } from "../manifest.js";
 import { EMAIL_PATTERN } from "../property.js";
-import { renderCatalog } from "../render.js";
-import { SERVICE_GROUP } from "./api.js";
+import { SERVICE_GROUP, hasMeasures } from "./api.js";
 import { CurrentPrincipal } from "./authentication.js";
 import { catalogFor, graphOf } from "./catalog.js";
+import { describeCatalog } from "../render.js";
 import { InvalidRequestBody, SignInCheckLimited, schemaIssues } from "./errors.js";
 import { identityToken, makeOperations, requireRead, toQuery, } from "./operations.js";
 import { clientAddress, fixedWindowLimiter, } from "./rate-limit.js";
@@ -24,34 +25,43 @@ function isJsonMediaType(contentType) {
     const mediaType = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
     return mediaType === "application/json" || mediaType.endsWith("+json");
 }
-/** Reads `{ input, options? }`. The input itself is validated by `runAction`. */
-function readEnvelope(request) {
+/** Reads a JSON body: `application/json` or a `+json` type, or no content type at all. */
+function readJson(request) {
     return Effect.gen(function* () {
         if (!isJsonMediaType(request.headers["content-type"])) {
             return yield* new InvalidRequestBody({ reason: "unsupported_media_type", issues: [] });
         }
         const text = yield* Effect.orDie(request.text);
-        let body;
         try {
-            body = JSON.parse(text);
+            return JSON.parse(text);
         }
         catch {
             return yield* new InvalidRequestBody({ reason: "invalid_json", issues: [] });
         }
-        return yield* Schema.decodeUnknownEffect(ActionEnvelope)(body, { errors: "all" }).pipe(Effect.mapError((error) => new InvalidRequestBody({ reason: "invalid_request", issues: schemaIssues(error.issue) })));
     });
 }
-function entityHandlers(built, planned, operationsOf) {
+/** Reads `{ input, options? }`. The input itself is validated by `runAction`. */
+function readEnvelope(request) {
+    return readJson(request).pipe(Effect.flatMap((body) => Schema.decodeUnknownEffect(ActionEnvelope)(body, { errors: "all" }).pipe(Effect.mapError((error) => new InvalidRequestBody({
+        reason: "invalid_request",
+        issues: schemaIssues(error.issue),
+    })))));
+}
+function entityHandlers(built, planned, operationsOf, aggregates) {
+    // Registered beside the record routes; `aggregate` is a static segment, record ids are UUIDs.
+    const withAggregate = (handlers) => hasMeasures(planned)
+        ? handlers.handleRaw("aggregate", aggregateHandler(aggregates.entity(planned.name)))
+        : handlers;
     return dynamicGroup(built.api, planned.name, (handlers) => Effect.gen(function* () {
         if (planned.resolved.entity.definition.source !== undefined) {
-            return handlers.handleRaw("sourceCollection", () => requireRead([planned.name]).pipe(Effect.andThen(() => HttpServerResponse.json({
+            return withAggregate(handlers).handleRaw("sourceCollection", () => requireRead([planned.name]).pipe(Effect.andThen(() => HttpServerResponse.json({
                 error: "not_found",
                 detail: `${planned.name} uses a warehouse source; query it through the workspace API.`,
             }, { status: 404 }))));
         }
         const backend = yield* OntologyBackend;
         const operations = operationsOf(backend);
-        let registered = handlers
+        let registered = withAggregate(handlers)
             .handle("find", (request) => operations.find(planned, toQuery(request.query)))
             .handle("query", (request) => operations.find(planned, toQuery(request.payload)))
             .handle("get", (request) => operations.get(planned, request.params.id))
@@ -108,7 +118,21 @@ function checkSignIn(backend, limiter) {
         return yield* backend.checkSignIn(email);
     });
 }
-function serviceHandlers(built, operationsOf) {
+/**
+ * `POST /api/ontology/aggregate` and `POST /api/ontology/<entity>/aggregate`: the facade's answer is
+ * SegmentStream's, so its status and JSON body pass through as they came, with its `Retry-After` on
+ * a 429 or a 503.
+ */
+function aggregateHandler(aggregate) {
+    return ({ request }) => readJson(request).pipe(Effect.flatMap(aggregate), Effect.map((answer) => HttpServerResponse.text(answer.text, {
+        status: answer.status,
+        contentType: "application/json",
+        ...(answer.retryAfter === undefined
+            ? {}
+            : { headers: { "retry-after": answer.retryAfter } }),
+    })));
+}
+function serviceHandlers(built, operationsOf, aggregate) {
     const { manifest } = built.plan.ontology;
     const graph = graphOf(manifest);
     const signInLimiter = fixedWindowLimiter(SIGN_IN_CHECK_LIMIT);
@@ -130,29 +154,43 @@ function serviceHandlers(built, operationsOf) {
             .handle("openapi", () => Effect.sync(() => {
             if (openApi === undefined) {
                 openApi = OpenApi.fromApi(built.api);
-                for (const entity of manifest.entities.filter((entity) => entity.source !== undefined)) {
-                    const document = Schema.toJsonSchemaDocument(built.schemas.get(entity.name).record);
-                    openApi.components.schemas ??= {};
-                    openApi.components.schemas[entity.name] = {
-                        ...(document.definitions[`${entity.name
-                            .split("_")
-                            .map((part) => part[0].toUpperCase() + part.slice(1))
-                            .join("")}Record`] ?? document.schema),
-                        "x-ontology-source": entity.source,
-                        "x-ontology-measures": entity.measures,
-                        "x-ontology-relationships": entity.relationships,
-                    };
+                openApi.components.schemas ??= {};
+                for (const entity of manifest.entities) {
+                    const recordName = `${entity.name
+                        .split("_")
+                        .map((part) => part[0].toUpperCase() + part.slice(1))
+                        .join("")}Record`;
+                    if (entity.source !== undefined) {
+                        const document = Schema.toJsonSchemaDocument(built.schemas.get(entity.name).record);
+                        openApi.components.schemas[entity.name] = {
+                            ...(document.definitions[recordName] ?? document.schema),
+                            "x-ontology-source": entity.source,
+                            "x-ontology-measures": entity.measures,
+                            "x-ontology-relationships": entity.relationships,
+                        };
+                        continue;
+                    }
+                    // A value-matched relationship has no key field or route; only this names it.
+                    const matched = entity.relationships.filter(isValueMatched);
+                    const record = openApi.components.schemas[recordName];
+                    if (matched.length > 0 && record !== undefined) {
+                        openApi.components.schemas[recordName] = {
+                            ...record,
+                            "x-ontology-relationships": matched,
+                        };
+                    }
                 }
             }
             return openApi;
         }))
-            .handle("describe", (request) => Effect.map(permissionsFor(request.query.as), (permissions) => renderCatalog(manifest, permissions === undefined ? {} : { as: permissions })))
+            .handle("describe", (request) => Effect.map(permissionsFor(request.query.as), (permissions) => describeCatalog(manifest, permissions)))
             .handle("status", () => Effect.map(backend.appliedHash, (appliedHash) => ({
             hash: manifest.hash,
             appliedHash: appliedHash ?? null,
             upToDate: appliedHash === manifest.hash,
         })))
-            .handle("signInCheck", checkSignIn(backend, signInLimiter));
+            .handle("signInCheck", checkSignIn(backend, signInLimiter))
+            .handleRaw("aggregate", aggregateHandler(aggregate));
     }));
 }
 function storageHandlers(built) {
@@ -178,14 +216,14 @@ function storageHandlers(built) {
     }));
 }
 /** The handlers of every group of the API; they require {@link OntologyBackend}. */
-export function handlersLayer(built, hooks, connections, replicate) {
+export function handlersLayer(built, hooks, connections, replicate, aggregates) {
     const operationsOf = (backend) => makeOperations(backend, built.plan, hooks, connections, replicate);
     const layers = [
-        serviceHandlers(built, operationsOf),
+        serviceHandlers(built, operationsOf, aggregates.model),
         ...(built.plan.ontology.manifest.entities.some((entity) => entity.properties.some((property) => property.type === "blob"))
             ? [storageHandlers(built)]
             : []),
-        ...built.plan.entities.map((planned) => entityHandlers(built, planned, operationsOf)),
+        ...built.plan.entities.map((planned) => entityHandlers(built, planned, operationsOf, aggregates)),
     ];
     const [first, ...rest] = layers;
     return Layer.mergeAll(first, ...rest);

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

@@ -1,5 +1,6 @@
 import { Layer } from "effect";
 import { HttpRouter } from "effect/unstable/http";
+import type { Aggregates } from "../aggregate.js";
 import type { BuiltApi } from "../api.js";
 import { type TokenVerifier } from "../authentication.js";
 import type { AfterCommitHook } from "../config.js";
@@ -17,6 +18,8 @@ export interface McpServerOptions {
     readonly connections: ConnectionTransportFactory;
     readonly replicate: ReplicationKick;
     readonly verifyToken: TokenVerifier;
+    /** The facade the aggregate routes run; the aggregate tool runs its model-level aggregate. */
+    readonly aggregates: Aggregates;
 }
 /**
  * The ontology's MCP server at `POST /mcp`: Streamable HTTP without sessions, so any instance can

package/dist/service/mcp/server.js

@@ -3,9 +3,10 @@ import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstab
 import { HttpApiBuilder, HttpApiSecurity } from "effect/unstable/httpapi";
 import { encodeManifest } from "../../manifest.js";
 import { isAllowed, permissionOf, READ_VERB } from "../../permissions.js";
-import { renderCatalog } from "../../render.js";
+import { SCOPE_MISMATCH } from "../aggregate-platform.js";
 import { CurrentPrincipal, withPrincipal } from "../authentication.js";
 import { catalogFor } from "../catalog.js";
+import { describeCatalog, measuresFor, 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";
@@ -79,6 +80,41 @@ function errorText(body) {
         : [];
     return `${body.detail} (${body.error}, request ${body.requestId})${issues.join("")}`;
 }
+/** SegmentStream's refusal when its deployed manifest is not the one the service checked against. */
+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 " +
+        "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 " +
+        "redeploy.",
+};
+/**
+ * SegmentStream's answer to an aggregate as the model reads it: the body as structured content, its
+ * warnings first in the text so they are not missed, and an error status as a tool error.
+ */
+function aggregateOutput(answer) {
+    const { body } = answer;
+    if (answer.status >= 400) {
+        const code = typeof body.error === "string" ? body.error : `HTTP ${answer.status}`;
+        const reference = typeof body.requestId === "string" ? `, request ${body.requestId}` : "";
+        const detail = AGENT_DETAILS[code] ??
+            (typeof body.detail === "string" ? body.detail : "The aggregate failed.");
+        return { text: `${detail} (${code}${reference})`, structured: body, isError: true };
+    }
+    const execution = body.execution;
+    const warnings = Array.isArray(execution?.warnings)
+        ? execution.warnings.filter((warning) => typeof warning === "string")
+        : [];
+    const json = JSON.stringify(body);
+    return {
+        text: warnings.length === 0
+            ? json
+            : `Warnings:\n${warnings.map((warning) => `- ${warning}`).join("\n")}\n\n${json}`,
+        structured: body,
+    };
+}
 /**
  * A failed tool call as the model reads it: `isError`, the REST route's error body as structured
  * content, and the same in a sentence. Unexpected failures are logged with their cause and answered
@@ -108,16 +144,21 @@ function toolFailure(cause, requestId) {
         isError: true,
     }));
 }
-function runTool({ built, operations }, tool, args, request) {
+function runTool({ built, operations, aggregate }, tool, args, request) {
     return Effect.gen(function* () {
         const { target } = tool;
         switch (target.kind) {
             case "describe": {
                 const principal = yield* CurrentPrincipal;
                 return {
-                    text: renderCatalog(built.plan.ontology.manifest, { as: principal.permissions }),
+                    text: describeCatalog(built.plan.ontology.manifest, principal.permissions),
                 };
             }
+            case "aggregate": {
+                // The route's facade, as the caller: the arguments are the request body.
+                const answer = yield* aggregate(args).pipe(Effect.catchTag("InvalidRequestBody", (error) => Effect.fail(new InvalidArguments({ issues: error.issues }))));
+                return aggregateOutput(answer);
+            }
             case "me":
                 return structured(yield* encoded(Me, yield* operations.caller));
             case "find": {
@@ -157,9 +198,10 @@ function callTool(server, params, request) {
         if (!isObject(args)) {
             return { kind: "invalid", message: "The tool's arguments must be an object." };
         }
-        const result = yield* runTool(server, tool, args, request).pipe(Effect.map(({ text, structured: content }) => ({
+        const result = yield* runTool(server, tool, args, request).pipe(Effect.map(({ text, structured: content, isError }) => ({
             content: [{ type: "text", text }],
             ...(content === undefined ? {} : { structuredContent: content }),
+            ...(isError === true ? { isError } : {}),
         })), Effect.catchCause((cause) => toolFailure(cause, requestId)));
         return { kind: "called", result };
     });
@@ -201,7 +243,7 @@ function readResource({ built }, uri) {
                     {
                         uri,
                         mimeType: "text/plain",
-                        text: renderCatalog(manifest, { as: principal.permissions }),
+                        text: describeCatalog(manifest, principal.permissions),
                     },
                 ];
             default:
@@ -210,16 +252,18 @@ function readResource({ built }, uri) {
     });
 }
 /**
- * What an agent learns when it connects: what the server is, the entities the caller may read and
- * where to find the rest.
+ * 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, measure }) => `- ${name}: ${measure.description}`);
     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 " +
@@ -227,7 +271,14 @@ function instructions({ built }, permissions) {
         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.",
-        "Call describe for the full catalog: properties, relationships and the actions you may run.",
+        ...(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.",
     ].join("\n\n");
 }
 function negotiate(requested) {
@@ -362,6 +413,7 @@ export function mcpLayer(options) {
             built: options.built,
             tools,
             operations: makeOperations(backend, options.built.plan, options.hooks, options.connections, options.replicate),
+            aggregate: options.aggregates.model,
         };
         yield* router.add("POST", MCP_PATH, handlePost(server, options.verifyToken, backend));
         yield* router.add("GET", MCP_PATH, METHOD_NOT_ALLOWED);

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

@@ -22,6 +22,8 @@ export type McpToolTarget = {
     readonly kind: "describe";
 } | {
     readonly kind: "me";
+} | {
+    readonly kind: "aggregate";
 };
 /** A tool of the ontology's MCP server, derived from the same plan as the HTTP routes. */
 export interface McpTool {
@@ -34,14 +36,23 @@ export interface McpTool {
     readonly annotations: McpToolAnnotations;
     /** Every permission a caller needs to see and run the tool; none for the global tools. */
     readonly permissions: ReadonlyArray<string>;
+    /**
+     * For a tool whose input depends on what the caller may read: the caller's input schema, or
+     * `undefined` when the tool can do nothing for them and is not listed. Calls are checked anyway.
+     */
+    readonly inputSchemaFor?: (caller: PermissionHolder) => JsonSchemaObject | undefined;
     readonly target: McpToolTarget;
 }
 /**
- * The MCP tools of an ontology: `describe` and `me`, then for every stored entity `find`, `get`,
+ * The MCP tools of an ontology: `describe` 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
  * `check` already refuses.
  */
 export declare function mcpTools(built: BuiltApi): ReadonlyArray<McpTool>;
-/** The tools a caller may see: those whose every permission the caller's roles grant. */
+/**
+ * The tools a caller may see: those whose every permission the caller's roles grant, each with the
+ * caller's input schema.
+ */
 export declare function visibleTools(tools: ReadonlyArray<McpTool>, caller: PermissionHolder): ReadonlyArray<McpTool>;

package/dist/service/mcp/tools.js

@@ -1,11 +1,14 @@
 import { Schema } from "effect";
+import { AGGREGATE_NAME_PATTERN } from "../../aggregate-routes.js";
 import { InvalidOntology } from "../../diagnostics.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 { measuresFor, RECORDS_OR_AGGREGATES } from "../../render.js";
 import { actionInputJsonSchema } from "../../runtime/generated-actions.js";
 import { actionDescription, requires } from "../descriptions.js";
-import { HistoryPage, Me } from "../schemas.js";
+import { AGGREGATE_FILTER_OPERATORS, AGGREGATE_GRANULARITIES, AGGREGATE_LIMITS, HistoryPage, Me, } from "../schemas.js";
 const DEFS = "#/$defs/";
 /**
  * A JSON Schema whose root is an object schema, as MCP requires of tool inputs and outputs: a root
@@ -94,12 +97,30 @@ function relatedHint(planned, traversal) {
                 `{"${traversal.opposite}": {"some": {"id": {"eq": "${id}"}}}}.`);
     }
 }
+/**
+ * How an agent reads the target of a value-matched relationship, which the service cannot traverse:
+ * the reference is an ordinary property, and the target lives in the warehouse.
+ */
+function matchedHints(planned) {
+    return planned.resolved.relationships.flatMap(({ name, relationship, target }) => {
+        if (relationship.cardinality !== "one" || !isValueMatched(relationship)) {
+            return [];
+        }
+        const property = Object.keys(relationship.on ?? {})[0] ?? "";
+        return [
+            `${name} is matched on ${property}; read ${target ?? "it"} through the workspace aggregates.`,
+        ];
+    });
+}
 function readTools(planned, schemas, built) {
     const { manifest } = built.plan.ontology;
     const { definition } = planned.resolved.entity;
     const label = definition.label.toLowerCase();
     const read = permissionOf(planned.name, READ_VERB);
-    const related = planned.traversals.map((traversal) => `- ${relatedHint(planned, traversal)}`);
+    const related = [
+        ...planned.traversals.map((traversal) => relatedHint(planned, traversal)),
+        ...matchedHints(planned),
+    ].map((hint) => `- ${hint}`);
     return [
         {
             name: mcpToolName(planned.name, "find"),
@@ -181,14 +202,140 @@ const GLOBAL_TOOLS = [
         target: { kind: "me" },
     },
 ];
+const AGGREGATE_NAME = {
+    type: "string",
+    pattern: AGGREGATE_NAME_PATTERN,
+    description: "<entity>.<property>, or a route from a measure's entity when it reaches the property's " +
+        "entity in several ways: <entity>.<relationship>.<property>, at most two relationships.",
+};
+const AGGREGATE_VALUE = {
+    anyOf: [{ type: "string" }, { type: "number" }, { type: "boolean" }],
+};
+/** 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}): ${measure.description}`,
+    };
+}
+/** The aggregate tool's input for a caller: the request of `POST /api/ontology/aggregate`. */
+function aggregateInput(measures) {
+    return {
+        type: "object",
+        properties: {
+            measures: {
+                type: "array",
+                minItems: 1,
+                maxItems: AGGREGATE_LIMITS.measures,
+                uniqueItems: true,
+                items: { anyOf: measures.map(measureChoice) },
+                description: "What to compute, as <entity>.<measure>. Measures of several entities are each " +
+                    "computed over their own entity's rows, then combined on the dimensions.",
+            },
+            dimensions: {
+                type: "array",
+                maxItems: AGGREGATE_LIMITS.dimensions,
+                uniqueItems: true,
+                items: AGGREGATE_NAME,
+                description: "What to group by. Every dimension must be reachable from every measure's entity.",
+            },
+            filters: {
+                type: "array",
+                maxItems: AGGREGATE_LIMITS.filters,
+                description: "All must hold. A filter applies to each measure's entity that reaches it; the answer " +
+                    "warns about the others.",
+                items: {
+                    type: "object",
+                    properties: {
+                        dimension: AGGREGATE_NAME,
+                        operator: { enum: [...AGGREGATE_FILTER_OPERATORS] },
+                        value: { ...AGGREGATE_VALUE, description: "The value of equals." },
+                        values: {
+                            type: "array",
+                            minItems: 1,
+                            maxItems: AGGREGATE_LIMITS.values,
+                            items: AGGREGATE_VALUE,
+                            description: "The values of in, or the two inclusive bounds of between, for example " +
+                                '["2026-09-01", "2026-09-30"].',
+                        },
+                    },
+                    required: ["dimension", "operator"],
+                    additionalProperties: false,
+                },
+            },
+            granularity: {
+                enum: [...AGGREGATE_GRANULARITIES],
+                description: "Buckets the date or timestamp dimension granularityOf names.",
+            },
+            granularityOf: { ...AGGREGATE_NAME, description: "A requested date or timestamp dimension." },
+            orderBy: {
+                type: "array",
+                maxItems: AGGREGATE_LIMITS.orderBy,
+                items: {
+                    type: "object",
+                    properties: {
+                        measure: { type: "string", description: "A requested measure." },
+                        dimension: { type: "string", description: "A requested dimension." },
+                        direction: { enum: ["asc", "desc"] },
+                    },
+                    required: ["direction"],
+                    additionalProperties: false,
+                },
+            },
+            limit: {
+                type: "integer",
+                minimum: 1,
+                maximum: AGGREGATE_LIMITS.rows,
+                description: "At most 1000 rows; 100 by default.",
+            },
+        },
+        required: ["measures"],
+        additionalProperties: false,
+    };
+}
+const AGGREGATE_DESCRIPTION = "Numbers about the model: measures from one or several entities, grouped and filtered by " +
+    `properties of related entities. The rule: ${RECORDS_OR_AGGREGATES}.\n\n` +
+    "Examples, with entities sales, stock and product:\n" +
+    '- September revenue by brand: {"measures": ["sales.revenue"], "dimensions": ["product.brand"], ' +
+    '"filters": [{"dimension": "sales.order_date", "operator": "between", ' +
+    '"values": ["2026-09-01", "2026-09-30"]}]}\n' +
+    '- September units sold beside units in stock, by status: {"measures": ["sales.units", ' +
+    '"stock.on_hand"], "dimensions": ["product.status"], "filters": [{"dimension": ' +
+    '"sales.order_date", "operator": "between", "values": ["2026-09-01", "2026-09-30"]}]}\n\n' +
+    "Partitioned warehouse entities require a between filter on their date property; the error " +
+    "names it. Currency measures need a single-currency filter. " +
+    "Answers come from the warehouse, and stored records from its replica: execution.sources says " +
+    "how fresh each is, and execution.warnings says when a filter did not apply to a measure. " +
+    "Requires reading every entity the request reads, path intermediates included. Call describe " +
+    "for the model's measures and relationships.";
+function aggregateTool(manifest) {
+    return {
+        name: "aggregate",
+        title: "Aggregate measures",
+        description: AGGREGATE_DESCRIPTION,
+        inputSchema: aggregateInput(measuresFor(manifest)),
+        inputSchemaFor: (caller) => {
+            const measures = measuresFor(manifest, caller.permissions);
+            return measures.length === 0 ? undefined : aggregateInput(measures);
+        },
+        annotations: READ,
+        permissions: [],
+        target: { kind: "aggregate" },
+    };
+}
 /**
- * The MCP tools of an ontology: `describe` and `me`, then for every stored entity `find`, `get`,
+ * The MCP tools of an ontology: `describe` 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
  * `check` already refuses.
  */
 export function mcpTools(built) {
-    const tools = [...GLOBAL_TOOLS];
+    const { manifest } = built.plan.ontology;
+    const tools = [
+        ...GLOBAL_TOOLS,
+        ...(measuresFor(manifest).length > 0 ? [aggregateTool(manifest)] : []),
+    ];
     for (const planned of built.plan.entities) {
         if (planned.resolved.entity.definition.source !== undefined) {
             continue;
@@ -212,7 +359,19 @@ export function mcpTools(built) {
     }
     return tools;
 }
-/** The tools a caller may see: those whose every permission the caller's roles grant. */
+/**
+ * The tools a caller may see: those whose every permission the caller's roles grant, each with the
+ * caller's input schema.
+ */
 export function visibleTools(tools, caller) {
-    return tools.filter((tool) => tool.permissions.every((required) => isAllowed(required, caller)));
+    return tools.flatMap((tool) => {
+        if (!tool.permissions.every((required) => isAllowed(required, caller))) {
+            return [];
+        }
+        if (tool.inputSchemaFor === undefined) {
+            return [tool];
+        }
+        const inputSchema = tool.inputSchemaFor(caller);
+        return inputSchema === undefined ? [] : [{ ...tool, inputSchema }];
+    });
 }

package/dist/service/plan.js

@@ -63,13 +63,19 @@ export function planApi(ontology, generatedActions) {
     const report = (path, message) => {
         diagnostics.push({ severity: "error", code: "reserved-name", path, message });
     };
+    // The service cannot read warehouse records, so a relationship to one has no route.
+    const warehouseBacked = new Set(ontology.entities
+        .filter((candidate) => candidate.entity.definition.source !== undefined)
+        .map((candidate) => candidate.name));
     const entities = ontology.entities.map((resolved) => ({
         name: resolved.name,
         resolved,
         traversals: resolved.entity.definition.source !== undefined
             ? []
             : [
-                ...resolved.relationships.map(declaredTraversal),
+                ...resolved.relationships
+                    .filter(({ target }) => target === undefined || !warehouseBacked.has(target))
+                    .map(declaredTraversal),
                 ...inverseTraversals(resolved.name, ontology.entities),
             ],
         actions: plannedActions(resolved, (entity) => generatedActions(entity, ontology), report),