@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/service/mcp/tools.js

@@ -0,0 +1,938 @@
+import { Schema } from "effect";
+import { METRIC_QUERY_NAME_PATTERN, isBuiltInUser } from "../../metric-routes.js";
+import { InvalidOntology } from "../../diagnostics.js";
+import { GENERATED_UPSERT_PREFIX, humanize, mcpToolName } from "../../names.js";
+import { effectivePermissions, isAllowed, permissionOf, READ_VERB, } from "../../permissions.js";
+import { FIND_CONDITIONS, findToolInput } from "./find-input.js";
+import { metricDescription, metricsFor, modelMetricDescription, modelMetricsFor, reachesOf, RECORDS_OR_METRIC_QUERIES, } 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 { ConversationSearch } from "../agent/conversations.js";
+import { runtimeAllows } from "./runtime-policy.js";
+import { confirmationFacts, needsConfirmation, withConfirmation, } from "./confirmation.js";
+import { ChatList, ChatListResult, ChatHistory, ChatPostWire, RuntimeChatPostWire, } from "../chat/schemas.js";
+import { ChatPostResult } from "../../chat.js";
+import { actionDescription, requires } from "../descriptions.js";
+import { DiscoverInput, DiscoverToolOutput } from "../discovery-schemas.js";
+import { DIMENSIONS_LIMIT, hasMetrics, VALUES_DEFAULT, VALUES_LIMIT } from "./metric-tools.js";
+import { NavigationInput, NavigationToolOutput } from "../navigation-schemas.js";
+import { METRIC_QUERY_FILTER_OPERATORS, METRIC_QUERY_GRANULARITIES, METRIC_QUERY_LIMITS, METRIC_QUERY_PERIOD_UNITS, METRIC_QUERY_PERIODS, HistoryPage, MAXIMUM_TIMEZONE_LENGTH, 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
+ * `$ref` into `$defs` is replaced by the definition it names.
+ */
+function rootObject(schema) {
+    const reference = schema.$ref;
+    const definitions = schema.$defs;
+    if (typeof reference !== "string" || !reference.startsWith(DEFS) || definitions === undefined) {
+        return schema;
+    }
+    const referenced = definitions[reference.slice(DEFS.length)];
+    if (referenced === undefined) {
+        return schema;
+    }
+    const rest = Object.fromEntries(Object.entries(schema).filter(([key]) => key !== "$ref"));
+    return { ...rest, ...referenced };
+}
+/** The JSON Schema of what a schema encodes to: the shape the service sends. */
+export function encodedJsonSchema(schema) {
+    const document = Schema.toJsonSchemaDocument(schema);
+    const root = document.schema;
+    return rootObject(Object.keys(document.definitions).length === 0
+        ? root
+        : { ...root, $defs: document.definitions });
+}
+const NO_INPUT = { type: "object", properties: {}, additionalProperties: false };
+function idInput(label, warehouse = false) {
+    return {
+        type: "object",
+        properties: {
+            id: {
+                type: "string",
+                ...(warehouse ? {} : { format: "uuid" }),
+                description: `The ${label}'s id returned by find.`,
+            },
+        },
+        required: ["id"],
+        additionalProperties: false,
+    };
+}
+function historyInput(label) {
+    return {
+        type: "object",
+        properties: {
+            id: { type: "string", format: "uuid", description: `The ${label}'s id.` },
+            after: { type: "string", description: "The next_cursor of the previous page." },
+            limit: {
+                type: "integer",
+                minimum: 1,
+                maximum: 200,
+                description: "The page size, at most 200.",
+            },
+        },
+        required: ["id"],
+        additionalProperties: false,
+    };
+}
+const READ = { readOnlyHint: true, openWorldHint: false };
+/**
+ * Upload sessions change no business record; the action that stores the ticket does. Beginning
+ * one without an idempotency key opens another session, so only completion is idempotent.
+ */
+const UPLOAD = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    irreversibleHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+};
+const GENERATED_HINTS = {
+    create: { destructive: false, irreversible: false, idempotent: false },
+    update: { destructive: false, irreversible: false, idempotent: true },
+    delete: { destructive: true, irreversible: false, idempotent: true },
+    link: { destructive: false, irreversible: false, idempotent: true },
+    unlink: { destructive: false, irreversible: false, idempotent: true },
+};
+/** MCP's defaults for a tool that writes: it may destroy, and repeating it may change more. */
+const AUTHORED_DEFAULT = {
+    destructive: true,
+    irreversible: false,
+    idempotent: false,
+};
+function hintsOf(planned, { name, generated, action }) {
+    // The built-in user's generated actions declare their own.
+    if (generated && action.hints !== undefined) {
+        return { ...AUTHORED_DEFAULT, ...action.hints };
+    }
+    if (generated) {
+        return name.startsWith(GENERATED_UPSERT_PREFIX)
+            ? { destructive: false, irreversible: false, idempotent: true }
+            : (GENERATED_HINTS[name] ?? AUTHORED_DEFAULT);
+    }
+    const declared = planned.resolved.actions.find((candidate) => candidate.name === name)?.hints;
+    // A safety label classifies the action; idempotence alone does not opt out of confirmation.
+    const classified = declared?.readOnly === true ||
+        declared?.destructive !== undefined ||
+        declared?.irreversible !== undefined;
+    return { ...AUTHORED_DEFAULT, ...(classified ? { destructive: false } : {}), ...declared };
+}
+/** How an agent reaches the records a relationship leads to, with the tools it has. */
+function relatedHint(planned, traversal) {
+    if (traversal.match !== undefined) {
+        return (`${traversal.name}: include ["${traversal.name}"], or ${mcpToolName(traversal.target, "find")} ` +
+            `with where {"${traversal.match.target}": {"eq": "<${traversal.match.source}>"}}.`);
+    }
+    const id = `<${planned.resolved.entity.definition.label.toLowerCase()} id>`;
+    const find = mcpToolName(traversal.target, "find");
+    switch (traversal.kind) {
+        case "one":
+            return (`${traversal.name}: include ["${traversal.name}"], or ` +
+                `${mcpToolName(traversal.target, "get")} with ${traversal.name}_id.`);
+        case "inverseOfOne":
+            return `${traversal.name}: ${find} with where {"${traversal.opposite}": {"id": {"eq": "${id}"}}}.`;
+        case "many":
+        case "inverseOfMany":
+            return (`${traversal.name}: ${find} with where ` +
+                `{"${traversal.opposite}": {"some": {"id": {"eq": "${id}"}}}}.`);
+    }
+}
+/**
+ * An entity's metrics and what can group them, for its `find` description: an agent that finds
+ * the entity learns the metrics it can ask `query_metrics` for without another lookup. It names
+ * only the entities, and routes through them, that the reader may read.
+ */
+function metricsHint(manifest, entity, permissions) {
+    const metrics = entity.metrics ?? [];
+    if (metrics.length === 0) {
+        return undefined;
+    }
+    const named = metrics.map((metric) => `${entity.name}.${metric.name} (${metricDescription(entity, metric).replace(/\.$/, "")}` +
+        `${metric.unit === "number" ? "" : `; ${metric.unit}`})`);
+    const reaches = reachesOf(manifest, entity.name, permissions).map(({ target, routes, ambiguous }) => `${target} (${routes.join(" or ")}${ambiguous ? "; write the route" : ""})`);
+    const users = entity.relationships.some((relationship) => isBuiltInUser(relationship.to));
+    return (`Metrics, counted, summed or compared with query_metrics rather than by paging find: ` +
+        `${named.join("; ")}. Group and filter them by ${entity.name} properties` +
+        (reaches.length === 0 ? "" : `, or by properties of ${reaches.join(", ")}`) +
+        "." +
+        (users
+            ? " Users are not reachable: query_metrics cannot split them by a user relationship."
+            : ""));
+}
+/** At most `maximum` code points of `text`, ending with an ellipsis when it was cut. */
+function clip(text, maximum) {
+    const points = Array.from(text.trim());
+    return points.length <= maximum ? points.join("") : `${points.slice(0, maximum - 1).join("")}…`;
+}
+/**
+ * What the entity's fields and their values mean, as the ontology describes them: the find
+ * input names each field's type only, so that clients do not cut it short. Only fields the
+ * author described are listed.
+ */
+function fieldsHint(entity) {
+    const lines = entity.properties.flatMap((property) => {
+        const description = property.description?.trim() ?? "";
+        const values = (property.options ?? []).filter((option) => option.description.trim() !== "");
+        if (description === "" && values.length === 0) {
+            return [];
+        }
+        const meaning = description === "" ? "" : ` ${clip(description, 200)}`;
+        const options = values.length === 0
+            ? ""
+            : ` Values: ${values
+                .map((option) => `${option.value} (${clip(option.description, 100).replace(/\.$/, "")})`)
+                .join(", ")}.`;
+        return [`- ${property.name}:${meaning}${options}`];
+    });
+    return lines.length === 0 ? undefined : `Fields:\n${lines.join("\n")}`;
+}
+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))].map((hint) => `- ${hint}`);
+    const includable = planned.traversals.slice(0, 2).map((traversal) => `"${traversal.name}"`);
+    const entity = manifest.entities.find((candidate) => candidate.name === planned.name);
+    const including = includable.length === 0
+        ? ""
+        : ` Pass include as a list of relationship names, as in [${includable.join(", ")}].`;
+    const findDescription = (permissions) => {
+        const metrics = metricsHint(manifest, entity, permissions);
+        const fields = fieldsHint(entity);
+        return (`Filter, sort and page through ${definition.plural.toLowerCase()}, at most 200 at a ` +
+            `time; pass next_cursor as after to read the next page.${including} ` +
+            `${definition.description}\n\n` +
+            `${FIND_CONDITIONS}\n\n` +
+            `${requires([read])} Including a relationship, or filtering through one, requires ` +
+            "reading its entity too." +
+            (fields === undefined ? "" : `\n\n${fields}`) +
+            (related.length > 0 ? `\n\nRelated records:\n${related.join("\n")}` : "") +
+            (metrics === undefined ? "" : `\n\n${metrics}`));
+    };
+    return [
+        {
+            name: mcpToolName(planned.name, "find"),
+            title: `Find ${definition.plural.toLowerCase()}`,
+            description: findDescription([read]),
+            ...((entity.metrics ?? []).length === 0
+                ? {}
+                : {
+                    descriptionFor: (caller) => findDescription(effectivePermissions(caller)),
+                }),
+            // The query of POST /<entity>/query, published compactly. The server decodes it with the
+            // closed schema: an unknown field or operator is an error.
+            inputSchema: findToolInput(manifest, planned.name),
+            outputSchema: { type: "object", ...encodedJsonSchema(schemas.findResult) },
+            annotations: READ,
+            permissions: [read],
+            target: { kind: "find", planned },
+        },
+        {
+            name: mcpToolName(planned.name, "get"),
+            title: `Get a ${label}`,
+            description: `One ${label} by its id. ${definition.description}\n\n${requires([read])}`,
+            inputSchema: idInput(label, definition.source !== undefined),
+            outputSchema: encodedJsonSchema(schemas.record),
+            annotations: READ,
+            permissions: [read],
+            target: { kind: "get", planned },
+        },
+        ...(definition.source === undefined
+            ? [
+                {
+                    name: mcpToolName(planned.name, "history"),
+                    title: `History of a ${label}`,
+                    description: `What each action changed on a ${label}, newest first, with who ran it and the values ` +
+                        `before and after. ${requires([read])}`,
+                    inputSchema: historyInput(label),
+                    outputSchema: encodedJsonSchema(HistoryPage),
+                    annotations: READ,
+                    permissions: [read],
+                    target: { kind: "history", planned },
+                },
+            ]
+            : []),
+    ];
+}
+/**
+ * The argument an action that consumes or stages an upload takes beside its input: the idempotency key the
+ * runtime requires of it, and the create intent the upload was begun with. The service removes it
+ * before the input is validated.
+ */
+export const ACTION_OPTIONS_ARGUMENT = "_options";
+/** The `me` tool's marker: tool calls accept the runtime envelope's chat source. */
+export const RUNTIME_SOURCE_META = "segmentstream/runtime-source";
+/** The `chat_post_message` tool's marker: the deployment posts exact messages to its chat. */
+export const CHAT_POST_META = "segmentstream/chat-post";
+const ACTION_OPTIONS_SCHEMA = {
+    type: "object",
+    description: "Options of an action that stores or stages a file: idempotency_key, required for file writes, " +
+        "and create_intent, the one the upload was begun with when it creates a record.",
+    properties: {
+        idempotency_key: { type: "string", minLength: 1, maxLength: 128 },
+        create_intent: { type: "string", format: "uuid" },
+    },
+    additionalProperties: false,
+};
+/** File-writing action tools expose their options even when preparation creates the upload. */
+function actionToolInput(action) {
+    // Empty Effect structs omit the root type, but MCP requires an explicit object input schema.
+    const schema = {
+        type: "object",
+        ...rootObject(actionInputJsonSchema(action.input)),
+    };
+    const properties = schema.properties;
+    if ((uploadFields(action.input).length === 0 && (action.files?.length ?? 0) === 0) ||
+        (schema.type !== undefined && schema.type !== "object") ||
+        (properties !== undefined && ACTION_OPTIONS_ARGUMENT in properties)) {
+        return schema;
+    }
+    return {
+        ...schema,
+        type: "object",
+        properties: { ...(properties ?? {}), [ACTION_OPTIONS_ARGUMENT]: ACTION_OPTIONS_SCHEMA },
+    };
+}
+function actionTool(planned, plannedAction) {
+    const { name, action, permissions } = plannedAction;
+    const hints = hintsOf(planned, plannedAction);
+    return {
+        name: mcpToolName(planned.name, name),
+        title: `${planned.resolved.entity.definition.label}: ${humanize(name).toLowerCase()}`,
+        description: actionDescription(plannedAction),
+        inputSchema: actionToolInput(action),
+        annotations: {
+            readOnlyHint: hints.readOnly === true && action.prepare !== undefined && !action.transactional,
+            destructiveHint: hints.destructive,
+            irreversibleHint: hints.irreversible,
+            idempotentHint: hints.idempotent,
+            openWorldHint: action.connections.length > 0 && hints.connectionsReadOnly !== true,
+        },
+        permissions,
+        target: { kind: "action", planned, action: plannedAction },
+    };
+}
+/** `discover` of an ontology that ranks entities by meaning with its decision model. */
+const DISCOVER_BY_MEANING = "Find which entities a request concerns, ranked by meaning: pass as query the member's request " +
+    "in their words, and what you understand they want. Each match is an entity with its " +
+    "relevance, the tools you may call for it and its metrics; call one by its exact name. With " +
+    "kind action or metric, or after, it matches words in names and descriptions instead. Search " +
+    "reads metadata, not records.";
+const GLOBAL_TOOLS = [
+    {
+        name: "discover",
+        title: "Search ontology definitions",
+        description: "Find entities, permitted actions, and computable metrics 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. 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",
+        _meta: { [RUNTIME_SOURCE_META]: 1 },
+        title: "Who am I",
+        description: "Who you are in this app: your user, your roles and the permissions they grant. History " +
+            "names you by the user id.",
+        inputSchema: NO_INPUT,
+        outputSchema: encodedJsonSchema(Me),
+        annotations: READ,
+        permissions: [],
+        target: { kind: "me" },
+    },
+];
+const METRIC_QUERY_NAME = {
+    type: "string",
+    pattern: METRIC_QUERY_NAME_PATTERN,
+    description: "<entity>.<property>, or a route from a metric's entity when it reaches the property's " +
+        "entity in several ways: <entity>.<relationship>.<property>, at most two relationships.",
+};
+const METRIC_QUERY_VALUE = {
+    anyOf: [{ type: "string" }, { type: "number" }, { type: "boolean" }],
+};
+/** `a, b or c`. */
+function alternatives(values) {
+    return values.length < 2
+        ? values.join("")
+        : `${values.slice(0, -1).join(", ")} or ${values[values.length - 1]}`;
+}
+const PERIODS = `${alternatives(METRIC_QUERY_PERIODS)}; or last N ${alternatives(METRIC_QUERY_PERIOD_UNITS)}, N at ` +
+    "least 1. Write a period exactly so: lowercase, single spaces, plural units even for 1 (last 1 " +
+    "days). last N days ends yesterday; last N weeks, months, quarters or years are whole units " +
+    "before the current one. Weeks start on Monday.";
+const FILTER_OPERATOR_DESCRIPTION = "equals, notEquals, gt, gte, lt, lte, contains, startsWith, endsWith and inPeriod take value; " +
+    "in, notIn and between take values; isNull and isNotNull take neither. notEquals and notIn also " +
+    "match null values and rows a route finds nothing for, so equals and notEquals together cover " +
+    "every row.";
+const FILTER_VALUE_DESCRIPTION = "equals, notEquals: the value. gt, gte, lt, lte: the bound, of a date, timestamp or number " +
+    "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}`;
+/** The query_metrics tool's input: the request of `POST /api/ontology/query_metrics`, as it is. */
+function metricQueryInput() {
+    return {
+        type: "object",
+        properties: {
+            metrics: {
+                type: "array",
+                minItems: 1,
+                maxItems: METRIC_QUERY_LIMITS.metrics,
+                uniqueItems: true,
+                items: { type: "string" },
+                description: "What to compute, as <entity>.<metric>, or a model metric by its name. " +
+                    "Metrics of several entities are each computed over their own entity's rows, then " +
+                    "combined on the dimensions; a model metric is computed on the combined rows " +
+                    "from the entity metrics it reads.",
+            },
+            dimensions: {
+                type: "array",
+                maxItems: METRIC_QUERY_LIMITS.dimensions,
+                uniqueItems: true,
+                items: METRIC_QUERY_NAME,
+                description: "What to group by. Every dimension must be reachable from every metric's entity.",
+            },
+            filters: {
+                type: "array",
+                maxItems: METRIC_QUERY_LIMITS.filters,
+                description: "All must hold. A filter applies to each metric's entity that reaches it; the answer " +
+                    "warns about the others.",
+                items: {
+                    type: "object",
+                    properties: {
+                        dimension: METRIC_QUERY_NAME,
+                        operator: {
+                            enum: [...METRIC_QUERY_FILTER_OPERATORS],
+                            description: FILTER_OPERATOR_DESCRIPTION,
+                        },
+                        value: { ...METRIC_QUERY_VALUE, description: FILTER_VALUE_DESCRIPTION },
+                        values: {
+                            type: "array",
+                            minItems: 1,
+                            maxItems: METRIC_QUERY_LIMITS.values,
+                            items: METRIC_QUERY_VALUE,
+                            description: "The values of in and notIn, or the two inclusive bounds of between, for example " +
+                                '["2026-09-01", "2026-09-30"]; dates cover whole days on a timestamp.',
+                        },
+                    },
+                    required: ["dimension", "operator"],
+                    additionalProperties: false,
+                },
+            },
+            granularity: {
+                enum: [...METRIC_QUERY_GRANULARITIES],
+                description: "Buckets the date or timestamp dimension granularityOf names; hour applies to " +
+                    "timestamps only. Weeks start on Monday.",
+            },
+            granularityOf: {
+                ...METRIC_QUERY_NAME,
+                description: "A requested date or timestamp dimension.",
+            },
+            timezone: {
+                type: "string",
+                maxLength: MAXIMUM_TIMEZONE_LENGTH,
+                description: "An IANA timezone, such as Europe/Moscow, or UTC. Buckets of timestamps, date bounds on " +
+                    "timestamps and inPeriod's today follow it; without it, the timezone of the entity that " +
+                    "owns the dimension.",
+            },
+            orderBy: {
+                type: "array",
+                maxItems: METRIC_QUERY_LIMITS.orderBy,
+                items: {
+                    type: "object",
+                    properties: {
+                        metric: { type: "string", description: "A requested metric." },
+                        dimension: { type: "string", description: "A requested dimension." },
+                        direction: { enum: ["asc", "desc"] },
+                    },
+                    required: ["direction"],
+                    additionalProperties: false,
+                },
+            },
+            limit: {
+                type: "integer",
+                minimum: 1,
+                maximum: METRIC_QUERY_LIMITS.rows,
+                description: "At most 1000 rows; 100 by default.",
+            },
+        },
+        required: ["metrics"],
+        additionalProperties: false,
+    };
+}
+const QUERY_METRICS_DESCRIPTION = "Compute metrics of one or several entities, grouped and filtered by properties " +
+    `of related entities. The rule: ${RECORDS_OR_METRIC_QUERIES}.\n\n` +
+    "list_metrics lists every metric you may compute, and each entity's <entity>_find names its " +
+    "own; get_dimensions says what metrics can be grouped and filtered by, and " +
+    "get_dimension_values the values a dimension takes. The shapes, with placeholders:\n" +
+    '- A total by a property: {"metrics": ["<entity>.<metric>"], "dimensions": ' +
+    '["<entity>.<property>"]}\n' +
+    '- A period, by week: {"metrics": ["<entity>.<metric>"], "dimensions": ["<entity>.<date>"], ' +
+    '"granularity": "week", "granularityOf": "<entity>.<date>", "filters": [{"dimension": ' +
+    '"<entity>.<date>", "operator": "inPeriod", "value": "last 4 weeks"}]}\n' +
+    '- By a property of a related entity: {"metrics": ["<entity>.<metric>"], "dimensions": ' +
+    '["<related entity>.<property>"], "filters": [{"dimension": "<entity>.<date>", "operator": ' +
+    '"between", "values": ["2026-09-01", "2026-09-30"]}]}\n\n' +
+    "Partitioned warehouse entities require a between or inPeriod filter on their date property; " +
+    "the error names it. Currency metrics need a single-currency filter, unless the metric is " +
+    "pinned to one currency. Use inPeriod for relative dates; the answer's execution.periods says " +
+    "which dates were used. " +
+    "Answers come from the warehouse, and stored records from its eventually consistent replica. " +
+    "There is no destination freshness watermark. execution.warnings says when a filter did not apply to a metric. " +
+    "Requires reading every entity the request reads, path intermediates included, and every " +
+    "entity a model metric reads. A model metric 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. A route never passes through or ends at User.";
+const SEARCH = {
+    type: "string",
+    minLength: 1,
+    maxLength: 200,
+    description: "Words that must all occur in the name, label or description, ignoring case.",
+};
+const METRIC_NAMES = {
+    type: "array",
+    minItems: 1,
+    maxItems: METRIC_QUERY_LIMITS.metrics,
+    uniqueItems: true,
+    items: { type: "string" },
+    description: "Metric names as list_metrics gives them: <entity>.<metric>, or a model metric's.",
+};
+const METRIC = {
+    type: "object",
+    properties: {
+        name: { type: "string" },
+        label: { type: "string" },
+        unit: { enum: ["number", "currency", "ratio", "percent"] },
+        description: { type: "string" },
+        entity: { type: "string" },
+        reads: { type: "array", items: { type: "string" } },
+    },
+    required: ["name", "label", "unit", "description"],
+};
+const DIMENSION = {
+    type: "object",
+    properties: {
+        name: { type: "string" },
+        label: { type: "string" },
+        type: { enum: ["string", "decimal", "boolean", "date", "timestamp"] },
+        description: { type: "string" },
+        values: { type: "array", items: { type: "string" } },
+    },
+    required: ["name", "label", "type"],
+};
+/** The metric tools, named as dbt names its MCP tools: see `./metric-tools.ts`. */
+function metricTools(manifest) {
+    const query = metricQueryInput();
+    const listed = (schema) => (caller) => hasMetrics(manifest, caller.permissions) ? schema : undefined;
+    const lookup = { ...READ, idempotentHint: true };
+    const listInput = {
+        type: "object",
+        properties: { search: SEARCH },
+        additionalProperties: false,
+    };
+    const dimensionsInput = {
+        type: "object",
+        properties: { metrics: METRIC_NAMES, search: SEARCH },
+        required: ["metrics"],
+        additionalProperties: false,
+    };
+    const valuesInput = {
+        type: "object",
+        properties: {
+            dimension: {
+                ...METRIC_QUERY_NAME,
+                description: "A dimension name, as get_dimensions gives it.",
+            },
+            metrics: {
+                ...METRIC_NAMES,
+                description: "The metrics whose rows the values come from; by default one of the dimension's own " +
+                    "entity, else one that reaches it.",
+            },
+            search: {
+                type: "string",
+                minLength: 1,
+                maxLength: 200,
+                description: "Only values containing this text, matched case-sensitively.",
+            },
+            filters: {
+                ...query.properties.filters,
+                description: "As in query_metrics. A partitioned warehouse entity needs a date filter; the error names it.",
+            },
+            limit: {
+                type: "integer",
+                minimum: 1,
+                maximum: VALUES_LIMIT,
+                description: `At most ${VALUES_LIMIT} values; ${VALUES_DEFAULT} by default.`,
+            },
+        },
+        required: ["dimension"],
+        additionalProperties: false,
+    };
+    return [
+        {
+            name: "list_metrics",
+            title: "List metrics",
+            description: "List the metrics you may compute: each entity's metrics, and model metrics, which " +
+                "combine several entities' metrics. Each has its name, label, unit and meaning, with its " +
+                "conditions, balance rule or the metrics it reads; the ontology's code declares them as " +
+                "metrics. search narrows them. Then get_dimensions says what they can be grouped by, " +
+                "and query_metrics computes them.",
+            inputSchema: listInput,
+            inputSchemaFor: listed(listInput),
+            outputSchema: {
+                type: "object",
+                properties: { metrics: { type: "array", items: METRIC } },
+                required: ["metrics"],
+            },
+            annotations: lookup,
+            permissions: [],
+            target: { kind: "list-metrics" },
+        },
+        {
+            name: "get_dimensions",
+            title: "Get dimensions of metrics",
+            description: "What the given metrics can be grouped and filtered by in query_metrics: the properties " +
+                "of their entities and of the entities those reach, each reachable from every given " +
+                "metric, with its type, meaning and, for a choice field, its values. A property reached " +
+                "in several ways is named by its route. A route never passes through or ends at User. " +
+                `At most ${DIMENSIONS_LIMIT}; search narrows them.`,
+            inputSchema: dimensionsInput,
+            inputSchemaFor: listed(dimensionsInput),
+            outputSchema: {
+                type: "object",
+                properties: {
+                    dimensions: { type: "array", items: DIMENSION },
+                    truncated: { type: "boolean" },
+                },
+                required: ["dimensions", "truncated"],
+            },
+            annotations: lookup,
+            permissions: [],
+            target: { kind: "get-dimensions" },
+        },
+        {
+            name: "get_dimension_values",
+            title: "Get dimension values",
+            description: "The values a dimension takes, to write a filter that matches the data: a choice " +
+                "field's options and a boolean's true and false at once; any other dimension's distinct " +
+                "values among a metric's rows, sorted. Requires reading what that metric reads.",
+            inputSchema: valuesInput,
+            inputSchemaFor: listed(valuesInput),
+            outputSchema: {
+                type: "object",
+                properties: {
+                    dimension: { type: "string" },
+                    values: { type: "array", items: { type: ["string", "number", "boolean", "null"] } },
+                    options: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: {
+                                value: { type: "string" },
+                                label: { type: "string" },
+                                description: { type: "string" },
+                            },
+                            required: ["value", "label"],
+                        },
+                    },
+                    metrics: { type: "array", items: { type: "string" } },
+                    truncated: { type: "boolean" },
+                    warnings: { type: "array", items: { type: "string" } },
+                },
+                required: ["dimension", "values", "truncated"],
+            },
+            annotations: lookup,
+            permissions: [],
+            target: { kind: "get-dimension-values" },
+        },
+        {
+            name: "query_metrics",
+            title: "Query metrics",
+            description: QUERY_METRICS_DESCRIPTION,
+            // The model metrics this caller may compute, which belong to no entity's find.
+            descriptionFor: (caller) => {
+                const model = modelMetricsFor(manifest, effectivePermissions(caller));
+                return model.length === 0
+                    ? QUERY_METRICS_DESCRIPTION
+                    : `${QUERY_METRICS_DESCRIPTION}\n\nModel metrics:\n${model
+                        .map((metric) => `- ${metric.name} (${metric.label}` +
+                        `${metric.unit === "number" ? "" : `; ${metric.unit}`}): ` +
+                        modelMetricDescription(metric))
+                        .join("\n")}`;
+            },
+            inputSchema: query,
+            inputSchemaFor: listed(query),
+            annotations: READ,
+            permissions: [],
+            target: { kind: "query-metrics" },
+        },
+    ];
+}
+/**
+ * The MCP tools of an ontology: `me`, `discover` when it ranks by meaning, opt-in `navigation`,
+ * and the metric tools when the ontology has metrics,
+ * 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, conversations = false, storage = {}, navigation = false) {
+    const { manifest } = built.plan.ontology;
+    const tools = [
+        ...GLOBAL_TOOLS,
+        ...(navigation
+            ? [
+                {
+                    name: "navigation",
+                    title: "Discover application pages",
+                    description: "List published application pages, optionally filtered by entity and title/description keywords. " +
+                        "Read descriptions to choose a page. Static pages have url; parameterized pages have url_pattern and " +
+                        "parameter hints. Patterns require established values, encoded by path segment. " +
+                        "This reads metadata only; " +
+                        "it does not open pages, select records, or grant access. " +
+                        "Use next_cursor as after to continue.",
+                    inputSchema: encodedJsonSchema(NavigationInput),
+                    outputSchema: { type: "object", ...encodedJsonSchema(NavigationToolOutput) },
+                    annotations: { ...READ, destructiveHint: false, idempotentHint: true },
+                    permissions: [],
+                    target: { kind: "navigation" },
+                },
+            ]
+            : []),
+        ...(metricsFor(manifest).length > 0 ? metricTools(manifest) : []),
+    ];
+    for (const planned of built.plan.entities) {
+        const schemas = built.schemas.get(planned.name);
+        const reads = readTools(planned, schemas, built);
+        const actions = planned.actions.map((action) => actionTool(planned, action));
+        tools.push(...(planned.name === "agent_chat"
+            ? [...reads.filter((tool) => tool.target.kind === "get"), ...actions].map((tool) => ({
+                ...tool,
+                name: tool.name.replace(/^agent_chat_/, "chat_"),
+            }))
+            : [...reads, ...actions]));
+    }
+    const discover = tools.findIndex((tool) => tool.name === "discover");
+    // Word search duplicates the client's own tool search; ranking by meaning does not.
+    if (discover >= 0) {
+        if (built.plan.ontology.config.discovery === undefined) {
+            tools.splice(discover, 1);
+        }
+        else {
+            tools[discover] = { ...tools[discover], description: DISCOVER_BY_MEANING };
+        }
+    }
+    const post = tools.findIndex((tool) => tool.name === "chat_post_message");
+    if (post >= 0) {
+        const original = tools[post];
+        const replacement = {
+            ...original,
+            inputSchema: encodedJsonSchema(ChatPostWire),
+            outputSchema: encodedJsonSchema(ChatPostResult),
+            ...(manifest.chat?.telegram === undefined ? {} : { _meta: { [CHAT_POST_META]: 1 } }),
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: false,
+                irreversibleHint: true,
+                idempotentHint: true,
+                openWorldHint: true,
+            },
+        };
+        tools[post] = replacement;
+    }
+    tools.push({
+        name: "chat_list",
+        title: "List eligible chats",
+        description: "List eligible chat destinations and server attribution. query filters titles by a case-insensitive " +
+            "substring before pagination; chat selects an exact ID/title. Posting does not grant history access.",
+        inputSchema: encodedJsonSchema(ChatList),
+        outputSchema: encodedJsonSchema(ChatListResult),
+        annotations: READ,
+        permissions: [],
+        target: { kind: "chat-list" },
+        inputSchemaFor: (caller) => isAllowed("agent_chat:read", caller) ||
+            isAllowed("agent_chat:post_message", caller) ||
+            ("kind" in caller && caller.kind === "member")
+            ? encodedJsonSchema(ChatList)
+            : undefined,
+    });
+    tools.push({
+        name: "chat_history",
+        title: "Read chat conversation",
+        description: "Read messages for an exact chat ID/title, with independent conversation pagination. " +
+            "Reads a group chat you are in (every group with agent_chat:read) or your own private chat.",
+        inputSchema: encodedJsonSchema(ChatHistory),
+        annotations: READ,
+        permissions: [],
+        target: { kind: "chat-history" },
+        inputSchemaFor: (caller) => "kind" in caller && caller.kind === "member" ? encodedJsonSchema(ChatHistory) : undefined,
+    });
+    tools.push({
+        name: "chat_search",
+        title: "Search stored conversations",
+        description: conversations
+            ? "Search retained conversation messages, decisions and tool calls by text, provider chat ID, " +
+                "sender ID, topic and date range. Returns the group chats you are in (every group with " +
+                "agent_chat:read) and DMs in which you participated. Dates are ISO 8601; before is the " +
+                "nextCursor of the previous page. " +
+                "Workspace administrators can read all DMs through the platform API."
+            : "Search retained conversations. Requires an available archive and independent conversation read access.",
+        inputSchema: encodedJsonSchema(ConversationSearch),
+        annotations: READ,
+        permissions: [],
+        target: { kind: "conversation-search" },
+        inputSchemaFor: (caller) => "kind" in caller && caller.kind === "member"
+            ? encodedJsonSchema(ConversationSearch)
+            : undefined,
+    });
+    const descriptions = {
+        "attachments-list": "List chat attachments by conversation (provider:chat ID), sender member UUID and ISO time range. " +
+            "Returns a bounded page and nextCursor; use before to resume. Includes expired metadata. " +
+            "Administrators with agent_chat:update may access any workspace chat; active group participants " +
+            "and DM senders may access their files.",
+        "attachments-get": "Read metadata of an accessible chat attachment. Expired or purged attachments return a clear error.",
+        "attachments-download": "Download an accessible chat attachment. Returns filename, content type, size, SHA-256 and a " +
+            "short-lived GET grant. Stream the URL's bytes with its supplied headers before expiry; do not " +
+            "forward your app bearer token.",
+        "attachments-promote": "Keep a chat attachment through an ontology action such as document.upload. Supply the action " +
+            "input without the file; the platform adopts the stored revision, fills SHA-256 when declared, " +
+            "and enforces your current action permissions. Retries reuse the promotion result.",
+        "files-download": "Download a stored blob property of a record you may read. property defaults to content. Returns " +
+            "immutable revision metadata, filename, content type, size, SHA-256 and a short-lived GET grant. " +
+            "Stream bytes from the URL with its supplied headers before expiry; do not forward your app " +
+            "bearer token.",
+        "files-upload-list": "List your open upload sessions and the pending/max slot counts. Includes IDs, filenames, " +
+            "target actions, expiry and awaiting_action. A ready upload has transferred its bytes but " +
+            "has not saved a record: call its action with the ticket, or cancel it if abandoned. " +
+            "Expired sessions and sessions from earlier deployments do not occupy current slots.",
+        "files-upload-get": "Inspect one of your uploads by ID. A ready session returns a ticket for its target action. " +
+            "Completing the transfer alone does not save a record. Keep the original action input and " +
+            "options for retries, and cancel an upload after a permanent rejection if you will not retry.",
+        "files-upload": "Begin storing a file through the action that takes it, such as an upload action. Give " +
+            "entity, action, filename, content_type and the exact size in bytes; property when the action " +
+            "takes several uploads of the entity, and record_id when the action changes an existing " +
+            "record. Returns upload.id, a short-lived transfer grant and options. Send the file's bytes " +
+            "as the request body to transfer.url with transfer.method and exactly transfer.headers before " +
+            "expiry; do not forward your app bearer token. Then call files_upload_complete with " +
+            "upload.id, and call the action with its file field set to the returned ticket and _options " +
+            "set to options. Give your own idempotency_key, a new UUID for each file, so any failure can " +
+            "be retried: after a lost response or an error with retryable: true, repeat the same call " +
+            "with the same key, waiting retry_after seconds when the error gives them, and it resumes " +
+            "the upload. Begin again with a new key only after a conflict without retryable, which means " +
+            "the upload can no longer resume. Open uploads per caller are limited: store each file " +
+            "with its action before beginning many, and cancel with files_upload_cancel an upload you " +
+            "will not use. Recover IDs with files_upload_list, and inspect a session with files_upload_get. " +
+            "A rejected action keeps its upload for a retry; cancel it after a permanent rejection " +
+            "when you will not retry. An action that succeeds without keeping its file, for example because the " +
+            "same file is already stored, releases the upload itself.",
+        "files-upload-complete": "Finish an upload once its bytes are transferred. The service checks the stored size and " +
+            "content type, then returns upload.ticket, {upload_id}, for the action's file field. " +
+            "An action that succeeds releases the ticket whether or not it keeps the file; a ticket no " +
+            "action takes expires after 24 hours unless you cancel it. Repeat the call after an error " +
+            "with retryable: true, waiting retry_after seconds when given; completing twice is safe.",
+        "files-upload-cancel": "Cancel one of your open uploads that no action will take, such as a file you found already " +
+            "stored, so it stops counting towards your open-upload limit and its bytes are removed. " +
+            "Give the upload.id from files_upload. An upload an action already stored cannot be " +
+            "canceled; canceling twice is safe.",
+    };
+    for (const operation of Object.keys(MEMBER_FILE_SCHEMAS)) {
+        if (operation.startsWith("files-") ? !storage.files : !storage.attachments) {
+            continue;
+        }
+        tools.push({
+            name: operation.replaceAll("-", "_"),
+            title: operation.replaceAll("-", " "),
+            description: descriptions[operation],
+            inputSchema: encodedJsonSchema(MEMBER_FILE_SCHEMAS[operation]),
+            annotations: operation === "attachments-promote"
+                ? { readOnlyHint: false, idempotentHint: true, openWorldHint: true }
+                : operation === "files-upload"
+                    ? UPLOAD
+                    : operation === "files-upload-complete" || operation === "files-upload-cancel"
+                        ? { ...UPLOAD, idempotentHint: true }
+                        : READ,
+            ...(operation === "attachments-promote"
+                ? {
+                    _meta: {
+                        "segmentstream/nested-action": {
+                            version: 1,
+                            entityArgument: "entity",
+                            actionArgument: "action",
+                            inputArgument: "input",
+                            recordArgument: "record_id",
+                        },
+                    },
+                }
+                : {}),
+            permissions: [],
+            target: { kind: "member-file", operation },
+        });
+    }
+    const seen = new Set();
+    const duplicates = tools.filter(({ name }) => seen.size === seen.add(name).size);
+    if (duplicates.length > 0) {
+        throw new InvalidOntology({
+            message: `The ontology's MCP tools collide: ${duplicates.map(({ name }) => name).join(", ")}.`,
+            diagnostics: duplicates.map(({ name }) => ({
+                severity: "error",
+                code: "invalid-tool-name",
+                path: name,
+                message: `${name} is the name of two MCP tools.`,
+            })),
+        });
+    }
+    return tools.map((tool) => ({
+        ...tool,
+        inputSchema: withConfirmation(tool.inputSchema, tool.annotations),
+        // Exact chat posting confirms its own preview of the destination and the posted text.
+        ...(tool.target.kind === "action" &&
+            tool.name !== "chat_post_message" &&
+            needsConfirmation(tool.annotations)
+            ? {
+                confirmation: confirmationFacts({
+                    title: tool.title,
+                    description: tool.description,
+                    inputSchema: tool.inputSchema,
+                    manifest,
+                    entity: tool.target.planned.name,
+                    omit: [ACTION_OPTIONS_ARGUMENT],
+                    preview: tool.target.action.action.confirm !== undefined,
+                }),
+            }
+            : {}),
+    }));
+}
+/**
+ * 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, provenance = { kind: "unverified" }) {
+    return tools.flatMap((tool) => {
+        if (!runtimeAllows(provenance, tool) ||
+            !tool.permissions.every((required) => isAllowed(required, caller))) {
+            return [];
+        }
+        const description = tool.descriptionFor?.(caller) ?? tool.description;
+        if (tool.inputSchemaFor === undefined) {
+            return [
+                {
+                    ...tool,
+                    description,
+                    ...(tool.name === "chat_post_message" && provenance.kind === "runtime"
+                        ? {
+                            inputSchema: withConfirmation(encodedJsonSchema(RuntimeChatPostWire), tool.annotations),
+                        }
+                        : {}),
+                },
+            ];
+        }
+        const inputSchema = tool.inputSchemaFor(caller);
+        return inputSchema === undefined ? [] : [{ ...tool, description, inputSchema }];
+    });
+}