@fluentcommerce/fluent-mcp-extn 0.1.0

package/dist/tools.js

@@ -0,0 +1,3254 @@
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { FluentConnectionTester, GraphQLIntrospectionService, buildAliasedMutationQuery, parseAliasedMutationResponse, formatErrorSummary, WebhookValidationService, SignatureAlgorithm, } from "@fluentcommerce/fc-connect-sdk";
+import { z } from "zod";
+import { toSafeConfigSummary, validateConfig, } from "./config.js";
+import { buildEventPayload } from "./event-payload.js";
+import { ToolError, toToolFailure } from "./errors.js";
+// New tool modules
+import { ENTITY_TOOL_DEFINITIONS, handleEntityCreate, handleEntityUpdate, handleEntityGet, } from "./entity-tools.js";
+import { WORKFLOW_TOOL_DEFINITIONS, handleWorkflowUpload, handleWorkflowDiff, handleWorkflowSimulate, } from "./workflow-tools.js";
+import { SETTING_TOOL_DEFINITIONS, handleSettingUpsert, handleSettingBulkUpsert, } from "./settings-tools.js";
+import { ENVIRONMENT_TOOL_DEFINITIONS, handleEnvironmentDiscover, handleEnvironmentValidate, } from "./environment-tools.js";
+import { TEST_TOOL_DEFINITIONS, handleTestAssert, } from "./test-tools.js";
+import { shapeResponse, summarizeConnection, analyzeEvents, } from "./response-shaper.js";
+/**
+ * MCP tool registration and request handling.
+ *
+ * Design principles:
+ * - strict input validation (zod)
+ * - deterministic payload shaping
+ * - standardized success/failure response envelopes
+ */
+// ---------------------------------------------------------------------------
+// Input schemas
+// ---------------------------------------------------------------------------
+const EventBuildInputSchema = z.object({
+    name: z.string().min(1),
+    entityRef: z.string().min(1),
+    entityId: z.string().optional(),
+    entityType: z.string().min(1),
+    retailerId: z.string().optional(),
+    entitySubtype: z.string().optional(),
+    rootEntityRef: z.string().optional(),
+    rootEntityType: z.string().optional(),
+    rootEntityId: z.string().optional(),
+    accountId: z.string().optional(),
+    source: z.string().default("fluent-mcp-extn"),
+    type: z.string().default("NORMAL"),
+    attributes: z.record(z.string(), z.unknown()).default({}),
+});
+const EventPublishInputSchema = z.object({
+    name: z.string().min(1),
+    entityRef: z.string().min(1),
+    entityId: z.string().optional(),
+    entityType: z.string().min(1),
+    retailerId: z.string().optional(),
+    entitySubtype: z.string().optional(),
+    rootEntityRef: z.string().optional(),
+    rootEntityType: z.string().optional(),
+    rootEntityId: z.string().optional(),
+    accountId: z.string().optional(),
+    source: z.string().default("fluent-mcp-extn"),
+    type: z.string().default("NORMAL"),
+    attributes: z.record(z.string(), z.unknown()).default({}),
+    mode: z.enum(["async", "sync"]).default("async"),
+    dryRun: z.boolean().default(false),
+});
+const EventGetInputSchema = z.object({
+    eventId: z.string().min(1),
+});
+/** Tool input for event.list. Supports canonical keys and backward-compatible aliases. */
+const EventListInputSchema = z
+    .object({
+    // Canonical keys (SDK FluentEventQueryParams)
+    eventId: z.string().optional(),
+    name: z.string().optional(),
+    category: z.string().optional(),
+    retailerId: z.union([z.string(), z.number()]).optional(),
+    eventType: z.string().optional(),
+    eventStatus: z.string().optional(),
+    from: z.string().optional(),
+    to: z.string().optional(),
+    start: z.number().int().min(1).optional(),
+    count: z.number().int().min(1).max(500).optional(),
+    // Response shaping
+    fields: z
+        .array(z.string())
+        .optional()
+        .describe("Project response to only these fields per event. Reduces token usage."),
+    analyze: z
+        .boolean()
+        .default(false)
+        .describe("If true, return grouped analysis (by name/entityType/status with counts) instead of raw events."),
+    // context.* (canonical)
+    "context.rootEntityType": z.string().optional(),
+    "context.rootEntityId": z.union([z.string(), z.number()]).optional(),
+    "context.rootEntityRef": z.string().optional(),
+    "context.entityType": z.string().optional(),
+    "context.entityId": z.union([z.string(), z.number()]).optional(),
+    "context.entityRef": z.string().optional(),
+    "context.sourceEvents": z.array(z.string()).optional(),
+    // Backward-compatible aliases
+    id: z.string().optional(),
+    entityRef: z.string().optional(),
+    entityType: z.string().optional(),
+    type: z.string().optional(),
+})
+    .passthrough();
+const EventFlowInspectInputSchema = z.object({
+    rootEntityRef: z.string().min(1),
+    rootEntityType: z.string().min(1).optional(),
+    rootEntityId: z.union([z.string(), z.number()]).optional(),
+    from: z.string().optional(),
+    to: z.string().optional(),
+    compact: z.boolean().default(true),
+    maxPages: z.number().int().min(1).max(50).default(10),
+    includeAudit: z.boolean().default(true),
+    includeEventDetails: z.boolean().default(true),
+    includeAuditDetails: z.boolean().default(false),
+    includeScheduled: z.boolean().default(true),
+    includeRuleDetails: z.boolean().default(false),
+    includeNoMatchDetails: z.boolean().default(true),
+    includeCustomLogs: z.boolean().default(false),
+    includeSnapshots: z.boolean().default(false),
+    includeCrossEntity: z.boolean().default(false),
+    includeExceptions: z.boolean().default(true),
+    inspectStatuses: z
+        .array(z.string())
+        .default(["NO_MATCH", "PENDING", "FAILED"]),
+    maxDrilldowns: z.number().int().min(0).max(100).default(50),
+    actionSampleLimit: z.number().int().min(1).max(200).default(100),
+});
+const TransitionTriggerInputSchema = z.object({
+    name: z.string().min(1).optional(),
+    type: z.string().min(1).optional(),
+    subtype: z.string().min(1).optional(),
+    status: z.string().min(1).optional(),
+    retailerId: z.string().min(1).optional(),
+    module: z.string().min(1).optional(),
+    flexType: z.string().min(1).optional(),
+    flexVersion: z.union([z.string().min(1), z.number().int()]).optional(),
+});
+const TransitionActionsInputSchema = z.object({
+    triggers: z.array(TransitionTriggerInputSchema).min(1),
+});
+const PluginListInputSchema = z.object({
+    name: z.string().optional(),
+    compact: z
+        .boolean()
+        .default(false)
+        .describe("If true, return only ruleInfo (name, description, entityTypes) per rule, stripping parameters and eventAttributes."),
+});
+const GraphQLQueryInputSchema = z.object({
+    query: z.string().min(1),
+    variables: z.record(z.string(), z.unknown()).optional(),
+    summarize: z
+        .boolean()
+        .default(false)
+        .describe("If true and result contains a Relay connection (edges/nodes), return record count, field names, and 3 sample records instead of full data."),
+});
+const BatchCreateInputSchema = z.object({
+    name: z.string().min(1),
+    retailerId: z.string().optional(),
+    entityType: z.string().optional(),
+    action: z.string().optional(),
+});
+const BatchSendInputSchema = z.object({
+    jobId: z.string().min(1),
+    payload: z.object({
+        action: z.string().min(1),
+        entityType: z.string().min(1),
+        entities: z.array(z.record(z.string(), z.unknown())).min(1),
+        source: z.string().optional(),
+        event: z.string().optional(),
+        catalogueRef: z.string().optional(),
+        conditions: z.record(z.string(), z.unknown()).optional(),
+    }),
+});
+const BatchStatusInputSchema = z.object({
+    jobId: z.string().min(1),
+});
+const BatchGetBatchStatusInputSchema = z.object({
+    jobId: z.string().min(1),
+    batchId: z.string().min(1),
+});
+const BatchResultsInputSchema = z.object({
+    jobId: z.string().min(1),
+});
+const GraphQLQueryAllInputSchema = z.object({
+    query: z.string().min(1),
+    variables: z.record(z.string(), z.unknown()).optional(),
+    maxPages: z.number().int().min(1).max(500).default(100),
+    maxRecords: z.number().int().min(1).max(50000).default(10000),
+    timeoutMs: z.number().int().min(1000).max(600000).default(300000),
+    direction: z.enum(["forward", "backward"]).default("forward"),
+    errorHandling: z.enum(["throw", "partial"]).default("throw"),
+    summarize: z
+        .boolean()
+        .default(false)
+        .describe("If true, return record count, field names, and 3 sample records instead of full paginated data."),
+});
+const GraphQLBatchMutateInputSchema = z.object({
+    mutation: z.string().min(1),
+    inputs: z.array(z.record(z.string(), z.unknown())).min(1).max(50),
+    returnFields: z.array(z.string()).optional(),
+    operationName: z.string().optional(),
+});
+const GraphQLIntrospectInputSchema = z.object({
+    type: z.string().optional(),
+    mutation: z.string().optional(),
+    listMutations: z.boolean().default(false),
+    listQueries: z.boolean().default(false),
+});
+const WebhookValidateInputSchema = z.object({
+    payload: z.record(z.string(), z.unknown()),
+    rawBody: z.string().optional(),
+    signature: z.string().optional(),
+    publicKey: z.string().optional(),
+    algorithm: z
+        .enum(["SHA512withRSA", "MD5withRSA"])
+        .default("SHA512withRSA"),
+});
+const MetricsQueryInputSchema = z.object({
+    query: z.string().min(1),
+    type: z.enum(["instant", "range"]).default("instant"),
+    time: z.string().optional(),
+    start: z.string().optional(),
+    end: z.string().optional(),
+    step: z.string().optional(),
+});
+const MetricsTopEventsInputSchema = z.object({
+    from: z.string().min(1),
+    to: z.string().optional(),
+    entityType: z.string().optional(),
+    eventStatus: z.string().optional(),
+    eventType: z.string().default("ORCHESTRATION"),
+    topN: z.number().int().min(1).max(100).default(20),
+    maxPages: z.number().int().min(1).max(50).default(10),
+});
+const MetricsHealthCheckInputSchema = z.object({
+    window: z.string().default("1h"),
+    includeTopEvents: z.boolean().default(true),
+    topN: z.number().int().min(1).max(100).default(10),
+    thresholds: z.object({
+        failureRate: z.number().min(0).max(100).default(5),
+        pendingRate: z.number().min(0).max(100).default(10),
+        dominanceRate: z.number().min(0).max(100).default(50),
+    }).default({ failureRate: 5, pendingRate: 10, dominanceRate: 50 }),
+});
+const MetricsSloReportInputSchema = z.object({
+    window: z.string().default("1h"),
+    includeTopFailingEvents: z.boolean().default(true),
+    topN: z.number().int().min(1).max(100).default(10),
+    maxPages: z.number().int().min(1).max(50).default(10),
+    thresholds: z
+        .object({
+        failureRate: z.number().min(0).max(100).default(5),
+        noMatchRate: z.number().min(0).max(100).default(0),
+        pendingRate: z.number().min(0).max(100).default(10),
+        runtimeP95Seconds: z.number().min(0).default(5),
+        inflightP95Seconds: z.number().min(0).default(60),
+    })
+        .default({
+        failureRate: 5,
+        noMatchRate: 0,
+        pendingRate: 10,
+        runtimeP95Seconds: 5,
+        inflightP95Seconds: 60,
+    }),
+});
+const MetricsLabelCatalogInputSchema = z.object({
+    metric: z.string().min(1),
+    window: z.string().default("24h"),
+    includeKnownLabels: z.boolean().default(true),
+    maxValuesPerLabel: z.number().int().min(1).max(50).default(10),
+});
+// ---------------------------------------------------------------------------
+// Tool definitions (JSON Schema for MCP)
+// ---------------------------------------------------------------------------
+const TOOL_DEFINITIONS = [
+    {
+        name: "config.validate",
+        description: "Run first: validates auth/base URL/retailer configuration and reports readiness for API tools.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "health.ping",
+        description: "Quick diagnostics: confirms SDK adapter connection and config readiness when calls fail.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "event.build",
+        description: "Payload-only builder for Event API input. Use before event.send to verify defaults and required context (no API call).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "Event name" },
+                entityRef: { type: "string", description: "Entity reference" },
+                entityId: { type: "string", description: "Entity ID (preferred when available)" },
+                entityType: {
+                    type: "string",
+                    description: "Entity type (for example ORDER or FULFILMENT)",
+                },
+                retailerId: { type: "string" },
+                entitySubtype: { type: "string" },
+                rootEntityRef: { type: "string" },
+                rootEntityType: { type: "string" },
+                rootEntityId: { type: "string" },
+                accountId: { type: "string" },
+                source: { type: "string" },
+                type: { type: "string" },
+                attributes: { type: "object", additionalProperties: true },
+            },
+            required: ["name", "entityRef", "entityType"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "event.send",
+        description: "Builds and sends a Fluent event (supports dryRun). Recommended flow: config.validate -> event.build -> event.send dryRun=true -> event.send dryRun=false -> event.list/event.get.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "Event name" },
+                entityRef: { type: "string", description: "Entity reference" },
+                entityId: { type: "string", description: "Entity ID (preferred when available)" },
+                entityType: { type: "string", description: "Entity type" },
+                retailerId: { type: "string" },
+                entitySubtype: { type: "string" },
+                rootEntityRef: { type: "string" },
+                rootEntityType: { type: "string" },
+                rootEntityId: { type: "string" },
+                accountId: { type: "string" },
+                source: { type: "string" },
+                type: { type: "string" },
+                attributes: { type: "object", additionalProperties: true },
+                mode: {
+                    type: "string",
+                    enum: ["async", "sync"],
+                    description: "Event dispatch mode (default: async)",
+                },
+                dryRun: {
+                    type: "boolean",
+                    description: "If true, build payload without sending",
+                },
+            },
+            required: ["name", "entityRef", "entityType"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "event.get",
+        description: "Fetch one event by ID. Use after event.send if response contains eventId, or after event.list resolves eventId.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                eventId: { type: "string", description: "Event ID to fetch" },
+            },
+            required: ["eventId"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "event.list",
+        description: "List/filter events via SDK getEvents with filters and pagination. Use to verify sends, discover eventId, then call event.get for full details.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                eventId: { type: "string", description: "Filter by event ID (canonical)" },
+                name: { type: "string", description: "Event name filter" },
+                category: { type: "string", description: "Event category" },
+                retailerId: { type: "string", description: "Retailer ID" },
+                eventType: { type: "string", description: "Event type (ORCHESTRATION, API, etc.)" },
+                eventStatus: { type: "string", description: "Event status (PENDING, SUCCESS, FAILED, etc.)" },
+                from: { type: "string", description: "Time window start (ISO)" },
+                to: { type: "string", description: "Time window end (ISO)" },
+                start: { type: "integer", minimum: 1, description: "Pagination offset" },
+                count: { type: "integer", minimum: 1, maximum: 500, description: "Page size" },
+                "context.rootEntityType": { type: "string", description: "Root entity type filter" },
+                "context.rootEntityId": { type: "string", description: "Root entity ID filter" },
+                "context.rootEntityRef": { type: "string", description: "Root entity ref filter" },
+                "context.entityType": { type: "string", description: "Entity type filter" },
+                "context.entityId": { type: "string", description: "Entity ID filter" },
+                "context.entityRef": { type: "string", description: "Entity ref filter" },
+                id: { type: "string", description: "Alias for eventId" },
+                entityRef: { type: "string", description: "Alias for context.entityRef" },
+                entityType: { type: "string", description: "Alias for context.entityType" },
+                type: { type: "string", description: "Alias for eventType" },
+                fields: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Project response: only include these fields per event. Example: [\"id\",\"name\",\"eventStatus\",\"category\",\"context.entityRef\",\"context.entityType\",\"generatedOn\"]. Omit for full events.",
+                },
+                analyze: {
+                    type: "boolean",
+                    description: "If true, return grouped analysis (by name/entityType/status with counts and time range) instead of raw events. Much smaller payload.",
+                },
+            },
+            additionalProperties: true,
+        },
+    },
+    {
+        name: "event.flowInspect",
+        description: [
+            "One-call event forensics for any root entity.",
+            "",
+            "Collects ORCHESTRATION events (and ORCHESTRATION_AUDIT when includeAudit=true), then extracts:",
+            "- status/entity timelines",
+            "- mutation request payloads from ACTION audit events",
+            "- webhook request/response diagnostics",
+            "- SendEvent payloads and future-dated scheduling evidence",
+            "- entity snapshots at each orchestration step (full state at transition)",
+            "- custom rule logs (LogCollection from extension rules)",
+            "- rule execution props (parameters used at runtime)",
+            "- enhanced NO_MATCH diagnostics with closeMatches and mismatch reasons",
+            "- NO_MATCH/PENDING/FAILED/SCHEDULED drill-down via event.get",
+            "",
+            "TOGGLEABLE SECTIONS (all default true except includeCrossEntity):",
+            "- includeRuleDetails: per-rule execution trace with class name, props, timing",
+            "- includeCustomLogs: custom plugin log messages (LogCollection)",
+            "- includeSnapshots: entity state at each processing point",
+            "- includeCrossEntity: child entity events (default: false)",
+            "",
+            "USE CASES:",
+            "- Debug stuck/failed entities: find which events NO_MATCHed or FAILed",
+            "- E2E post-mortem: see the full orchestration spread across entity types",
+            "- Webhook debugging: extract HTTP diagnostics from AUDIT actions",
+            "- Cross-entity flow analysis: ORDER → FULFILMENT_CHOICE → FULFILMENT → ORDER",
+        ].join("\n") +
+            "\n\nCOMPACT MODE (default):\n" +
+            "Returns a pre-analyzed summary (~2-3k tokens) with anomaly findings, status flow,\n" +
+            "failed webhook endpoints, and slowest rulesets instead of raw arrays (~24k tokens).\n" +
+            "Set compact=false for full raw data when drilling into specific issues.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                rootEntityRef: {
+                    type: "string",
+                    description: "Root entity reference, for example an order ref.",
+                },
+                rootEntityType: {
+                    type: "string",
+                    description: "Optional root entity type (for example ORDER, FULFILMENT, LOCATION, WAVE, PRODUCT).",
+                },
+                rootEntityId: {
+                    oneOf: [{ type: "string" }, { type: "number" }],
+                    description: "Optional root entity ID for disambiguation when refs are reused.",
+                },
+                from: {
+                    type: "string",
+                    description: "Optional ISO start time for event window.",
+                },
+                to: {
+                    type: "string",
+                    description: "Optional ISO end time for event window.",
+                },
+                compact: {
+                    type: "boolean",
+                    description: "Return a pre-analyzed summary instead of raw arrays (default: true). " +
+                        "Compact mode returns an analysis section with statusFlow, findings, " +
+                        "and stripped audit arrays (~2-3k tokens vs ~24k full). " +
+                        "Set to false for full raw data.",
+                },
+                maxPages: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: 50,
+                    description: "Max 500-event pages to fetch per event type (default: 10).",
+                },
+                includeEventDetails: {
+                    type: "boolean",
+                    description: "Include compact orchestration events in response (default: true).",
+                },
+                includeAudit: {
+                    type: "boolean",
+                    description: "Fetch and parse ORCHESTRATION_AUDIT events (default: true).",
+                },
+                includeAuditDetails: {
+                    type: "boolean",
+                    description: "Include compact action audit samples in response (default: false).",
+                },
+                includeScheduled: {
+                    type: "boolean",
+                    description: "Fetch SCHEDULED events separately (default: true). Adds scheduled section to response.",
+                },
+                includeRuleDetails: {
+                    type: "boolean",
+                    description: "Include per-rule execution trace with class name, props, and timing (default: false).",
+                },
+                includeNoMatchDetails: {
+                    type: "boolean",
+                    description: "Include enhanced NO_MATCH diagnostics with closeMatches from ruleSet audit events (default: true).",
+                },
+                includeCustomLogs: {
+                    type: "boolean",
+                    description: "Include custom plugin log messages from CUSTOM category audit events (default: false).",
+                },
+                includeSnapshots: {
+                    type: "boolean",
+                    description: "Include entity state snapshots at each processing point (default: false).",
+                },
+                includeCrossEntity: {
+                    type: "boolean",
+                    description: "Fetch events for child entity types (FULFILMENT_CHOICE, FULFILMENT) using rootEntityRef (default: false).",
+                },
+                includeExceptions: {
+                    type: "boolean",
+                    description: "Include rule exceptions with class, message, and ruleset context (default: true).",
+                },
+                inspectStatuses: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Orchestration statuses to drill with event.get (default: [NO_MATCH, PENDING, FAILED]).",
+                },
+                maxDrilldowns: {
+                    type: "integer",
+                    minimum: 0,
+                    maximum: 100,
+                    description: "Max events to drill into with event.get (default: 50). Set to 0 to skip drilldowns.",
+                },
+                actionSampleLimit: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: 200,
+                    description: "Max rows returned per action extraction section (default: 100).",
+                },
+            },
+            required: ["rootEntityRef"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "metrics.query",
+        description: [
+            "Query Prometheus metrics via the Fluent GraphQL metricInstant/metricRange queries.",
+            "",
+            "INSTANT: evaluates a PromQL expression at one point in time.",
+            "RANGE: requires start, end, and step to evaluate over a time window.",
+            "",
+            "Routes PromQL through the GraphQL proxy (metricInstant/metricRange).",
+            "Requires METRICS_VIEW permission on the authenticated user.",
+            "",
+            "AVAILABLE METRICS:",
+            "- core_event_received_total (counter) — events received by Fluent APIs",
+            "- rubix_event_runtime_seconds (histogram) — event processing time in Rubix",
+            "- rubix_event_inflight_latency_seconds (histogram) — queue wait time",
+            "- bpp_records_processed_total (counter) — batch pre-processing records",
+            "- feed_sent_total (counter) — inventory feed records exported",
+            "",
+            "COMMON LABELS: account_id, retailer_id, event_name, entity_type, source, status (Rubix only)",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "PromQL expression" },
+                type: {
+                    type: "string",
+                    enum: ["instant", "range"],
+                    description: "Query mode (default: instant)",
+                },
+                time: {
+                    type: "string",
+                    description: "Evaluation timestamp for instant queries (ISO-8601 or Unix timestamp)",
+                },
+                start: {
+                    type: "string",
+                    description: "Range start timestamp (required for range queries)",
+                },
+                end: {
+                    type: "string",
+                    description: "Range end timestamp (required for range queries)",
+                },
+                step: {
+                    type: "string",
+                    description: "Range step duration, for example 15s or 1m (required for range queries)",
+                },
+            },
+            required: ["query"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "workflow.transitions",
+        description: [
+            "Query available user actions (transitions) for entities at a given state.",
+            "",
+            "Calls POST /api/v4.1/transition to discover what events can be fired,",
+            "what attributes they require, and how they appear in the UI.",
+            "",
+            "USE CASES:",
+            "- Discover available actions at any workflow status without reading workflow JSON",
+            "- Build dynamic E2E test sequences that adapt to workflow changes",
+            "- Validate that expected user actions are available after deployment",
+            "- Get required event attributes for each action (avoids missing-attribute errors)",
+            "",
+            "RESPONSE includes per-trigger:",
+            "- trigger: the matched trigger condition",
+            "- userActions[]: available actions with eventName, context (button config), attributes (required form fields)",
+            "- transitions[]: same as userActions (legacy compatibility)",
+            "",
+            "INTEGRATION: The eventName from each userAction maps directly to event.send's \"name\" parameter.",
+            "The attributes[] tell you what to include in event.send's \"attributes\" parameter.",
+            "",
+            "EXAMPLE: Find available actions for an ORDER in CREATED status:",
+            "{ triggers: [{ type: \"ORDER\", subtype: \"HD\", status: \"CREATED\", retailerId: \"5\", flexType: \"ORDER::HD\" }] }",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                triggers: {
+                    type: "array",
+                    minItems: 1,
+                    items: {
+                        type: "object",
+                        properties: {
+                            type: { type: "string", description: "Entity type (e.g. ORDER, FULFILMENT, MANIFEST)" },
+                            subtype: { type: "string", description: "Entity subtype (e.g. HD, CC, DEFAULT)" },
+                            status: {
+                                type: "string",
+                                description: "Current entity status. Omit to get all actions for any status.",
+                            },
+                            retailerId: {
+                                type: "string",
+                                description: "Retailer ID (required). Falls back to FLUENT_RETAILER_ID when omitted.",
+                            },
+                            module: {
+                                type: "string",
+                                description: "Filter by module (e.g. servicepoint, adminconsole). Case-sensitive.",
+                            },
+                            flexType: {
+                                type: "string",
+                                description: "Workflow type (e.g. ORDER::HD, FULFILMENT::HD_WH).",
+                            },
+                            flexVersion: {
+                                oneOf: [{ type: "integer" }, { type: "string" }],
+                                description: "Workflow version. Omit for latest.",
+                            },
+                            name: { type: "string", description: "Event name filter" },
+                        },
+                        required: ["retailerId"],
+                        additionalProperties: false,
+                    },
+                    description: "List of trigger conditions to query available user actions for.",
+                },
+            },
+            required: ["triggers"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "plugin.list",
+        description: [
+            "List all registered orchestration rules (standard + custom) with metadata.",
+            "Returns a map keyed by ACCOUNT.context.RuleName with each entry containing:",
+            "- ruleInfo: name, description, accepted entity types, produced events",
+            "- eventAttributes: attributes the rule reads from events",
+            "- parameters: configurable rule parameters",
+            "",
+            "Use to understand what rules do when analyzing workflows.",
+            "Optional name filter performs case-insensitive substring match on rule keys.",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Optional filter: only return rules whose key contains this string (case-insensitive).",
+                },
+                compact: {
+                    type: "boolean",
+                    description: "If true, return only ruleInfo per rule (name, description, entityTypes), stripping parameters and eventAttributes to reduce token usage.",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "graphql.query",
+        description: [
+            "Execute a Fluent Commerce GraphQL query or mutation via SDK.",
+            "",
+            "PAGINATION: Fluent uses Relay-style connections. Cursors live on each edge, NOT on pageInfo.",
+            "Pattern: { orders(first: 50, after: $cursor) { edges { cursor node { id ref } } pageInfo { hasNextPage } } }",
+            "To paginate: take the cursor from the LAST edge in the response, pass it as the 'after' variable in the next call. Repeat while hasNextPage is true.",
+            "Pagination args: first/after (forward), last/before (backward). No endCursor or startCursor exists.",
+            "",
+            "MUTATIONS: Pass input via variables.",
+            "Pattern: mutation($input: UpdateOrderInput!) { updateOrder(input: $input) { id ref status } }",
+            "Variables: { \"input\": { \"id\": \"36\", \"status\": \"RECEIVED\" } }",
+            "",
+            "CONNECTION SHAPE: All list queries return connections: { edges { cursor node { ...fields } } pageInfo { hasNextPage } }.",
+            "Common roots: orders, fulfilments, fulfilmentChoices, locations, inventoryPositions, products, categories, settings, waves, articles.",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "GraphQL query or mutation string" },
+                variables: { type: "object", additionalProperties: true },
+                summarize: {
+                    type: "boolean",
+                    description: "If true and result contains a Relay connection (edges/nodes), return record count, field names, and 3 sample records instead of full data.",
+                },
+            },
+            required: ["query"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "batch.create",
+        description: "Create a batch ingestion job. Requires ready config and retailerId (input or env). Next steps: batch.send -> batch.status -> batch.results.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "Job name" },
+                retailerId: { type: "string" },
+                entityType: { type: "string" },
+                action: { type: "string" },
+            },
+            required: ["name"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "batch.send",
+        description: "Send records to an existing batch job. Requires jobId from batch.create and integration-specific payload shape.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                jobId: { type: "string", description: "Job ID from batch.create" },
+                payload: { type: "object", additionalProperties: true },
+            },
+            required: ["jobId", "payload"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "batch.status",
+        description: "Check overall job status for polling loops. Repeat until terminal status before fetching results.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                jobId: { type: "string", description: "Job ID to check" },
+            },
+            required: ["jobId"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "batch.batchStatus",
+        description: "Check a specific batch inside a job (jobId + batchId). Use for troubleshooting partial failures within multi-batch jobs.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                jobId: { type: "string", description: "Job ID" },
+                batchId: { type: "string", description: "Batch ID within the job" },
+            },
+            required: ["jobId", "batchId"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "batch.results",
+        description: "Get per-record batch outcomes for a completed job. Use after batch.status reaches terminal state to inspect success/failure details.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                jobId: { type: "string", description: "Job ID to get results for" },
+            },
+            required: ["jobId"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "graphql.queryAll",
+        description: [
+            "Execute a Fluent Commerce GraphQL query with SDK auto-pagination.",
+            "Automatically follows cursors, merges edges across pages, and deduplicates by node ID.",
+            "",
+            "USE INSTEAD OF graphql.query WHEN: you need ALL records from a connection (not just the first page).",
+            "The SDK detects pagination variables (first/after or last/before) in your query and auto-follows cursors.",
+            "",
+            "CONTROLS:",
+            "- maxPages: stop after N pages (default 100)",
+            "- maxRecords: stop after N total records (default 10000)",
+            "- timeoutMs: hard timeout for entire pagination run (default 300000ms = 5 min)",
+            "- direction: 'forward' (first/after) or 'backward' (last/before)",
+            "- errorHandling: 'throw' (default, fail on GraphQL errors) or 'partial' (return partial data with errors)",
+            "",
+            "RESPONSE includes extensions.autoPagination with: totalPages, totalRecords, truncated, truncationReason, direction.",
+            "",
+            "EXAMPLE: Fetch all orders with status ACTIVE:",
+            "query: { orders(first: 100, after: $cursor) { edges { cursor node { id ref status } } pageInfo { hasNextPage } } }",
+            "variables: { cursor: null }",
+            "maxRecords: 5000",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "GraphQL query with pagination variables (first/after or last/before). Must include edges { cursor node { ... } } and pageInfo { hasNextPage }.",
+                },
+                variables: {
+                    type: "object",
+                    additionalProperties: true,
+                    description: "Query variables. Include cursor variable (usually null for first page).",
+                },
+                maxPages: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: 500,
+                    description: "Maximum number of pages to fetch (default: 100)",
+                },
+                maxRecords: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: 50000,
+                    description: "Maximum total records to accumulate (default: 10000)",
+                },
+                timeoutMs: {
+                    type: "integer",
+                    minimum: 1000,
+                    maximum: 600000,
+                    description: "Hard timeout in ms for entire pagination run (default: 300000)",
+                },
+                direction: {
+                    type: "string",
+                    enum: ["forward", "backward"],
+                    description: "Pagination direction: forward (first/after) or backward (last/before). Default: forward.",
+                },
+                errorHandling: {
+                    type: "string",
+                    enum: ["throw", "partial"],
+                    description: "Error mode: 'throw' fails on GraphQL errors, 'partial' returns partial data with errors. Default: throw.",
+                },
+                summarize: {
+                    type: "boolean",
+                    description: "If true, return record count, field names, and 3 sample records instead of full paginated data.",
+                },
+            },
+            required: ["query"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "graphql.batchMutate",
+        description: [
+            "Execute multiple GraphQL mutations in a single request using aliased mutations.",
+            "Sends up to 50 mutations at once, each with its own input, in one GraphQL request.",
+            "",
+            "HOW IT WORKS:",
+            "1. Builds an aliased mutation query: mutation Batch($input1: UpdateOrderInput!, $input2: UpdateOrderInput!) {",
+            "     updateOrder1: updateOrder(input: $input1) { id ref }",
+            "     updateOrder2: updateOrder(input: $input2) { id ref }",
+            "   }",
+            "2. Sends as a single GraphQL request",
+            "3. Parses per-mutation results (success/failure for each input)",
+            "",
+            "USE CASES:",
+            "- Bulk update order statuses",
+            "- Batch create/update inventory positions",
+            "- Mass-update attributes on multiple entities",
+            "",
+            "RESPONSE includes: executed (count), failed (count), allSucceeded, allFailed, results (per-mutation), errors (per-mutation).",
+            "",
+            "EXAMPLE: Update 3 orders to SHIPPED:",
+            "mutation: 'updateOrder'",
+            "inputs: [{id: '1', status: 'SHIPPED'}, {id: '2', status: 'SHIPPED'}, {id: '3', status: 'SHIPPED'}]",
+            "returnFields: ['id', 'ref', 'status']",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                mutation: {
+                    type: "string",
+                    description: "Mutation name (e.g., 'updateOrder', 'createFulfilment', 'updateInventoryPosition'). The input type is inferred as <MutationName>Input (e.g., UpdateOrderInput).",
+                },
+                inputs: {
+                    type: "array",
+                    items: { type: "object", additionalProperties: true },
+                    minItems: 1,
+                    maxItems: 50,
+                    description: "Array of mutation inputs. Each object is passed as the $input variable for one aliased mutation.",
+                },
+                returnFields: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Fields to return from each mutation result (default: ['id', 'ref']). Use dot notation for nested: ['id', 'ref', 'status'].",
+                },
+                operationName: {
+                    type: "string",
+                    description: "Custom GraphQL operation name (default: Batch<MutationName>s).",
+                },
+            },
+            required: ["mutation", "inputs"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "graphql.introspect",
+        description: [
+            "Inspect the Fluent Commerce GraphQL schema via introspection.",
+            "Fetches the full schema and caches it for 1 hour. Use to discover mutations, input types, and field requirements.",
+            "",
+            "MODES (specify one):",
+            "- type: Get details of an INPUT_OBJECT type (fields, types, required flags). E.g., type='UpdateOrderInput'.",
+            "- mutation: Get details of a specific mutation (args, return type). E.g., mutation='updateOrder'.",
+            "- listMutations: true to get all available mutation names.",
+            "- listQueries: true to get all available query root field names.",
+            "",
+            "EXAMPLE USAGE:",
+            "1. List all mutations: { listMutations: true }",
+            "2. Inspect updateOrder: { mutation: 'updateOrder' }",
+            "3. See UpdateOrderInput fields: { type: 'UpdateOrderInput' }",
+            "4. Chain: listMutations -> find mutation -> inspect type -> build query",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                type: {
+                    type: "string",
+                    description: "Name of an INPUT_OBJECT type to inspect (e.g., 'UpdateOrderInput', 'CreateFulfilmentInput').",
+                },
+                mutation: {
+                    type: "string",
+                    description: "Name of a mutation to inspect (e.g., 'updateOrder', 'createFulfilment').",
+                },
+                listMutations: {
+                    type: "boolean",
+                    description: "If true, return all available mutation names.",
+                },
+                listQueries: {
+                    type: "boolean",
+                    description: "If true, return all available query root field names.",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "connection.test",
+        description: [
+            "Comprehensive Fluent Commerce connectivity test.",
+            "Authenticates, executes a 'me' query, and returns the authenticated user's details including:",
+            "- User: id, username, email, type, status, roles, permissions",
+            "- Retailer: id, ref, tradingName, primaryEmail",
+            "- Location: id, ref, name, type",
+            "",
+            "More thorough than health.ping — actually verifies the GraphQL endpoint works end-to-end.",
+            "Use when: first connecting, debugging auth issues, verifying retailer/location context.",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "webhook.validate",
+        description: [
+            "Validate a Fluent Commerce webhook payload and optionally verify its signature.",
+            "",
+            "TWO MODES:",
+            "1. Basic validation (no signature): Checks required fields (name, id, retailerId) are present.",
+            "   Input: { payload: { name: 'OrderCreated', id: '123', retailerId: '1' } }",
+            "",
+            "2. Signature validation: Verifies the X-Fluent-Signature header against the webhook body using the public key.",
+            "   Input: { payload: {...}, signature: '<base64-sig>', publicKey: '<PEM-key>', algorithm: 'SHA512withRSA' }",
+            "",
+            "Supported algorithms: SHA512withRSA (default), MD5withRSA.",
+            "",
+            "USE CASES:",
+            "- Testing webhook integrations during development",
+            "- Verifying webhook payloads in debug scenarios",
+            "- Validating webhook signature configuration",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                payload: {
+                    type: "object",
+                    additionalProperties: true,
+                    description: "The webhook payload object. Must include name, id, and retailerId for basic validation.",
+                },
+                rawBody: {
+                    type: "string",
+                    description: "The exact raw HTTP request body string for signature verification. " +
+                        "Signatures are computed over raw bytes, so providing the original " +
+                        "body avoids false negatives from JSON re-serialization. " +
+                        "Falls back to JSON.stringify(payload) if omitted.",
+                },
+                signature: {
+                    type: "string",
+                    description: "The X-Fluent-Signature header value (base64-encoded). Required for signature validation.",
+                },
+                publicKey: {
+                    type: "string",
+                    description: "The Fluent public key (PEM format) for signature verification. Required when signature is provided.",
+                },
+                algorithm: {
+                    type: "string",
+                    enum: ["SHA512withRSA", "MD5withRSA"],
+                    description: "Signature algorithm (default: SHA512withRSA).",
+                },
+            },
+            required: ["payload"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "metrics.topEvents",
+        description: [
+            "Aggregate event analytics within a time window.",
+            "Fetches events via the Event API, groups by (name + entityType + status),",
+            "and returns top-N rankings by volume with summary statistics.",
+            "",
+            "USE CASES:",
+            "- Monitor event volume patterns and identify high-frequency events",
+            "- Detect failure rate anomalies across entity types",
+            "- Identify NO_MATCH events indicating workflow gaps",
+            "- Compare event distribution before and after deployments",
+            "- Get top failing events: { from: '...', eventStatus: 'FAILED' }",
+            "",
+            "IMPLEMENTATION: Paginates through event.list results (up to maxPages x 500 events),",
+            "aggregates client-side, and returns ranked results with failure rate and status breakdown.",
+            "",
+            "EXAMPLE: Top 20 events in the last hour:",
+            '{ from: "2026-02-22T07:00:00Z", topN: 20 }',
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                from: { type: "string", description: "Time window start (ISO-8601, required)" },
+                to: { type: "string", description: "Time window end (ISO-8601, defaults to now)" },
+                entityType: { type: "string", description: "Filter by entity type (e.g., ORDER, FULFILMENT)" },
+                eventStatus: { type: "string", description: "Filter by event status (e.g., FAILED, NO_MATCH, COMPLETE, SUCCESS, PENDING)" },
+                eventType: { type: "string", description: "Filter by event type (default: ORCHESTRATION)" },
+                topN: { type: "integer", minimum: 1, maximum: 100, description: "Top N results (default: 20)" },
+                maxPages: { type: "integer", minimum: 1, maximum: 50, description: "Max pages to fetch (default: 10, each page = 500 events)" },
+            },
+            required: ["from"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "metrics.healthCheck",
+        description: [
+            "Single-call health assessment using Prometheus metrics via GraphQL,",
+            "applies anomaly detection heuristics, and returns a compact findings report.",
+            "",
+            "Runs locally in the MCP server — minimal tokens returned to the AI.",
+            "Falls back to Event API aggregation if Prometheus/GraphQL metrics are unavailable.",
+            "",
+            "CHECKS PERFORMED:",
+            "- Failure rate (>5% = HIGH severity)",
+            "- NO_MATCH events present (any = CRITICAL)",
+            "- PENDING queue ratio (>10% = MEDIUM)",
+            "- Single event dominance (>50% = MEDIUM, possible runaway loop)",
+            "",
+            "USE INSTEAD OF calling metrics.query multiple times manually.",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                window: {
+                    type: "string",
+                    description: "Prometheus time window (default: 1h). Examples: 1h, 6h, 24h, 7d",
+                },
+                includeTopEvents: {
+                    type: "boolean",
+                    description: "Include top-N event breakdown (default: true)",
+                },
+                topN: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: 100,
+                    description: "Number of top events to include (default: 10)",
+                },
+                thresholds: {
+                    type: "object",
+                    description: "Custom thresholds (defaults: failureRate=5, pendingRate=10, dominanceRate=50)",
+                    properties: {
+                        failureRate: { type: "number", description: "Failure rate threshold % (default: 5)" },
+                        pendingRate: { type: "number", description: "Pending rate threshold % (default: 10)" },
+                        dominanceRate: { type: "number", description: "Single-event dominance threshold % (default: 50)" },
+                    },
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "metrics.sloReport",
+        description: [
+            "Managed-services SLO snapshot in one call.",
+            "Computes event volume, failure/no-match/pending rates, and p95 runtime/inflight latency.",
+            "",
+            "PRIMARY DATA SOURCE: Prometheus metrics via metrics.query endpoints.",
+            "FALLBACK: Event API aggregation when Prometheus is unavailable (latency fields become null).",
+            "",
+            "USE CASES:",
+            "- Daily/shift operational health checks",
+            "- Release validation guardrails",
+            "- Fast incident triage with threshold-based findings",
+            "",
+            "Optionally includes top failing events for targeted remediation.",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                window: {
+                    type: "string",
+                    description: "Window for KPI aggregation (default: 1h). Examples: 30m, 1h, 24h, 7d",
+                },
+                includeTopFailingEvents: {
+                    type: "boolean",
+                    description: "Include top failing events from Event API (default: true)",
+                },
+                topN: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: 100,
+                    description: "Top N failing events to include (default: 10)",
+                },
+                maxPages: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: 50,
+                    description: "Event API pagination cap for fallback/top failing events (default: 10)",
+                },
+                thresholds: {
+                    type: "object",
+                    description: "Custom thresholds. Defaults: failureRate=5, noMatchRate=0, pendingRate=10, runtimeP95Seconds=5, inflightP95Seconds=60",
+                    properties: {
+                        failureRate: { type: "number", description: "Failure rate threshold in percent" },
+                        noMatchRate: { type: "number", description: "NO_MATCH rate threshold in percent" },
+                        pendingRate: { type: "number", description: "Pending rate threshold in percent" },
+                        runtimeP95Seconds: { type: "number", description: "Runtime p95 threshold in seconds" },
+                        inflightP95Seconds: {
+                            type: "number",
+                            description: "Inflight latency p95 threshold in seconds",
+                        },
+                    },
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "metrics.labelCatalog",
+        description: [
+            "Discover supported labels for a metric with live sampling + known Fluent hints.",
+            "",
+            "Runs an instant PromQL sample query: last_over_time(<metric>[window])",
+            "then extracts label keys from returned time series and summarizes cardinality.",
+            "",
+            "Useful to prevent invalid sum by(...) usage (for example using status on metrics that don't expose it).",
+            "If no live series are returned, can still provide known Fluent label hints for common platform metrics.",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                metric: { type: "string", description: "Metric selector name, for example core_event_received_total" },
+                window: {
+                    type: "string",
+                    description: "Sampling window (default: 24h). Examples: 30m, 1h, 24h, 7d",
+                },
+                includeKnownLabels: {
+                    type: "boolean",
+                    description: "Include known Fluent metric label hints (default: true)",
+                },
+                maxValuesPerLabel: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: 50,
+                    description: "Max sample values per label in response (default: 10)",
+                },
+            },
+            required: ["metric"],
+            additionalProperties: false,
+        },
+    },
+    // New agentic tools (appended from modules)
+    ...ENTITY_TOOL_DEFINITIONS,
+    ...WORKFLOW_TOOL_DEFINITIONS,
+    ...SETTING_TOOL_DEFINITIONS,
+    ...ENVIRONMENT_TOOL_DEFINITIONS,
+    ...TEST_TOOL_DEFINITIONS,
+];
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Maps tool input (with aliases) to SDK FluentEventQueryParams.
+ * Resolves aliases: id->eventId, entityRef->context.entityRef, entityType->context.entityType, type->eventType.
+ * Preserves only primitive values for passthrough.
+ */
+export function toEventQueryParams(input) {
+    const params = {};
+    const set = (key, value) => {
+        if (value === undefined || value === null)
+            return;
+        if (typeof value === "string" && value.trim() === "")
+            return;
+        if (Array.isArray(value)) {
+            params[key] = value.filter((v) => typeof v === "string");
+            return;
+        }
+        if (typeof value === "string" || typeof value === "number") {
+            params[key] = value;
+        }
+    };
+    set("eventId", input.eventId ?? input.id);
+    set("name", input.name);
+    set("category", input.category);
+    set("retailerId", input.retailerId);
+    set("eventType", input.eventType ?? input.type);
+    set("eventStatus", input.eventStatus);
+    set("from", input.from);
+    set("to", input.to);
+    set("start", input.start);
+    set("count", input.count);
+    set("context.rootEntityType", input["context.rootEntityType"]);
+    set("context.rootEntityId", input["context.rootEntityId"]);
+    set("context.rootEntityRef", input["context.rootEntityRef"]);
+    set("context.entityType", input["context.entityType"] ?? input.entityType);
+    set("context.entityId", input["context.entityId"]);
+    set("context.entityRef", input["context.entityRef"] ?? input.entityRef);
+    set("context.sourceEvents", input["context.sourceEvents"]);
+    for (const [key, value] of Object.entries(input)) {
+        if (key.startsWith("context.") ||
+            [
+                "eventId",
+                "id",
+                "name",
+                "category",
+                "retailerId",
+                "eventType",
+                "type",
+                "eventStatus",
+                "from",
+                "to",
+                "start",
+                "count",
+                "entityRef",
+                "entityType",
+            ].includes(key)) {
+            continue;
+        }
+        if (typeof value === "string" ||
+            typeof value === "number" ||
+            (Array.isArray(value) && value.every((v) => typeof v === "string"))) {
+            params[key] = value;
+        }
+    }
+    return params;
+}
+/**
+ * Fill missing trigger.retailerId from runtime config and validate readiness.
+ */
+export function resolveTransitionRequest(input, fallbackRetailerId) {
+    const triggers = input.triggers.map((trigger, index) => {
+        const retailerId = trigger.retailerId ?? fallbackRetailerId;
+        if (!retailerId) {
+            throw new ToolError("VALIDATION_ERROR", `triggers[${index}].retailerId is required. Set FLUENT_RETAILER_ID or pass retailerId per trigger.`);
+        }
+        return {
+            ...trigger,
+            retailerId,
+        };
+    });
+    return { triggers };
+}
+/**
+ * GraphQL mutations are non-idempotent; retries can duplicate side effects.
+ * Detect mutation operations so tools can disable automatic retries.
+ */
+export function isMutationOperation(query) {
+    const strippedComments = query.replace(/#[^\r\n]*/g, "").trimStart();
+    return /^mutation\b/i.test(strippedComments);
+}
+/** Derive tool name list from definitions for use by index.ts logging. */
+export const TOOL_NAMES = TOOL_DEFINITIONS.map((t) => t.name);
+/**
+ * Narrow cast for GraphQL variables at the Zod→SDK boundary.
+ * Tool inputs are validated as JSON-compatible objects by Zod; the SDK type
+ * expects Record<string, never> which is overly restrictive. This single
+ * helper centralizes the boundary cast.
+ */
+function toSdkVariables(vars) {
+    return vars;
+}
+function asRecord(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    return value;
+}
+function asAttributeMap(attributes) {
+    if (Array.isArray(attributes)) {
+        const out = {};
+        for (const item of attributes) {
+            const rec = asRecord(item);
+            if (!rec)
+                continue;
+            const name = rec.name;
+            if (typeof name === "string")
+                out[name] = rec.value;
+        }
+        return out;
+    }
+    return asRecord(attributes) ?? {};
+}
+function toNumber(value) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function countByKey(items, keyFn) {
+    const out = {};
+    for (const item of items) {
+        const key = keyFn(item);
+        out[key] = (out[key] ?? 0) + 1;
+    }
+    return out;
+}
+function topCounts(counts, limit) {
+    return Object.entries(counts)
+        .map(([key, count]) => ({ key, count }))
+        .sort((a, b) => b.count - a.count)
+        .slice(0, limit)
+        .map((entry, idx) => ({ rank: idx + 1, ...entry }));
+}
+function json(payload, isError = false, budget) {
+    let finalPayload = payload;
+    if (budget && budget.maxChars > 0 && !isError) {
+        const raw = JSON.stringify(payload);
+        if (raw.length > budget.maxChars) {
+            const result = shapeResponse(payload, budget);
+            finalPayload = {
+                ...result.shaped,
+                _responseMeta: result.meta,
+            };
+        }
+    }
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(finalPayload, null, 2) },
+        ],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+function requireClient(ctx) {
+    if (!ctx.client) {
+        throw new ToolError("CONFIG_ERROR", "SDK client is not available. Run config.validate and fix auth/base URL.");
+    }
+    return ctx.client;
+}
+function round1(value) {
+    return Math.round(value * 10) / 10;
+}
+function round3(value) {
+    return Math.round(value * 1000) / 1000;
+}
+function percentage(part, total) {
+    if (total <= 0)
+        return 0;
+    return round1((part / total) * 100);
+}
+/**
+ * Parse numeric output from Prometheus query responses.
+ *
+ * Supported result shapes:
+ * - scalar: [timestamp, value]
+ * - vector: [{ metric: {...}, value: [timestamp, value] }, ...]
+ */
+function extractPrometheusNumber(response, fallback) {
+    if (response.status !== "success")
+        return fallback;
+    const data = response.data && typeof response.data === "object"
+        ? response.data
+        : null;
+    if (!data)
+        return fallback;
+    const resultType = typeof data.resultType === "string" ? data.resultType : undefined;
+    const result = data.result;
+    if (resultType === "scalar" && Array.isArray(result) && result.length >= 2) {
+        const scalar = Number.parseFloat(String(result[1]));
+        return Number.isFinite(scalar) ? scalar : fallback;
+    }
+    if (Array.isArray(result) && result.length > 0) {
+        const first = result[0] && typeof result[0] === "object"
+            ? result[0]
+            : null;
+        const value = first?.value;
+        if (Array.isArray(value) && value.length >= 2) {
+            const parsed = Number.parseFloat(String(value[1]));
+            return Number.isFinite(parsed) ? parsed : fallback;
+        }
+    }
+    return fallback;
+}
+const KNOWN_METRIC_LABELS = {
+    core_event_received_total: [
+        "account_id",
+        "retailer_id",
+        "event_name",
+        "entity_type",
+        "source",
+    ],
+    core_event_last_received_seconds: [
+        "account_id",
+        "retailer_id",
+        "event_name",
+        "entity_type",
+        "source",
+    ],
+    rubix_event_received_total: [
+        "account_id",
+        "retailer_id",
+        "event_name",
+        "entity_type",
+        "source",
+    ],
+    rubix_event_inflight_latency_seconds: [
+        "account_id",
+        "retailer_id",
+        "event_name",
+        "entity_type",
+        "source",
+    ],
+    rubix_event_inflight_latency_seconds_sum: [
+        "account_id",
+        "retailer_id",
+        "event_name",
+        "entity_type",
+        "source",
+    ],
+    rubix_event_inflight_latency_seconds_count: [
+        "account_id",
+        "retailer_id",
+        "event_name",
+        "entity_type",
+        "source",
+    ],
+    rubix_event_inflight_latency_seconds_bucket: [
+        "account_id",
+        "retailer_id",
+        "event_name",
+        "entity_type",
+        "source",
+        "le",
+    ],
+    rubix_event_runtime_seconds: [
+        "account_id",
+        "retailer_id",
+        "event_name",
+        "entity_type",
+        "source",
+        "status",
+    ],
+    rubix_event_runtime_seconds_sum: [
+        "account_id",
+        "retailer_id",
+        "event_name",
+        "entity_type",
+        "source",
+        "status",
+    ],
+    rubix_event_runtime_seconds_count: [
+        "account_id",
+        "retailer_id",
+        "event_name",
+        "entity_type",
+        "source",
+        "status",
+    ],
+    rubix_event_runtime_seconds_bucket: [
+        "account_id",
+        "retailer_id",
+        "event_name",
+        "entity_type",
+        "source",
+        "status",
+        "le",
+    ],
+    bpp_records_processed_total: [
+        "account_id",
+        "run_id",
+        "stage",
+        "first_batch_received",
+        "deduplication_finished",
+    ],
+    bpp_records_unchanged_total: ["account_id", "run_id", "stage"],
+    bpp_records_changed_total: ["account_id", "run_id", "stage"],
+    bpp_last_run_timestamp_seconds: ["account_id", "run_id", "stage", "status"],
+    feed_sent_total: ["account_id", "feed_ref", "run_id", "data_type"],
+    feed_last_run_timestamp_seconds: ["account_id", "feed_ref", "run_id", "status"],
+};
+function extractPrometheusVectors(response) {
+    if (response.status !== "success")
+        return [];
+    const data = response.data && typeof response.data === "object"
+        ? response.data
+        : null;
+    if (!data)
+        return [];
+    const result = data.result;
+    if (!Array.isArray(result))
+        return [];
+    return result.filter((item) => typeof item === "object" && item !== null && "metric" in item);
+}
+/**
+ * Parse a Prometheus-style time window string into milliseconds.
+ * Supports h (hours), m (minutes), d (days). Throws on invalid format.
+ */
+export function parseWindowMs(window) {
+    const match = window.match(/^(\d+)([hmd])$/);
+    if (!match) {
+        throw new ToolError("VALIDATION_ERROR", `Invalid window format "${window}". Use <number><unit> where unit is h (hours), m (minutes), or d (days). Examples: 1h, 30m, 7d`);
+    }
+    const num = parseInt(match[1], 10);
+    const unit = match[2];
+    if (num <= 0) {
+        throw new ToolError("VALIDATION_ERROR", `Window value must be positive, got ${num}`);
+    }
+    if (unit === "h")
+        return num * 3600000;
+    if (unit === "d")
+        return num * 86400000;
+    /* unit === "m" */ return num * 60000;
+}
+/**
+ * Fetch events from the Event API with pagination, then aggregate by
+ * (name|entityType|status). Shared by metrics.topEvents and the
+ * metrics.healthCheck Event API fallback path.
+ */
+async function aggregateEventsFromApi(client, params) {
+    const baseParams = {
+        from: params.from,
+        to: params.to,
+        count: 500,
+    };
+    if (params.entityType)
+        baseParams["context.entityType"] = params.entityType;
+    if (params.eventStatus)
+        baseParams.eventStatus = params.eventStatus;
+    if (params.eventType)
+        baseParams.eventType = params.eventType;
+    const allEvents = [];
+    let page = 1;
+    let hasMore = true;
+    while (hasMore && page <= params.maxPages) {
+        const reqParams = { ...baseParams, start: (page - 1) * 500 + 1 };
+        const result = await client.getEvents(reqParams);
+        const events = result?.results ?? [];
+        if (!Array.isArray(events) || events.length === 0) {
+            hasMore = false;
+            break;
+        }
+        for (const evt of events) {
+            allEvents.push({
+                name: evt.name ?? "unknown",
+                entityType: evt.context?.entityType ?? "unknown",
+                status: evt.eventStatus ?? "unknown",
+            });
+        }
+        hasMore = result.hasMore ?? events.length >= 500;
+        page++;
+    }
+    const groups = new Map();
+    const statusCounts = new Map();
+    for (const evt of allEvents) {
+        const key = `${evt.name}|${evt.entityType}|${evt.status}`;
+        const existing = groups.get(key);
+        if (existing) {
+            existing.count++;
+        }
+        else {
+            groups.set(key, { ...evt, count: 1 });
+        }
+        statusCounts.set(evt.status, (statusCounts.get(evt.status) ?? 0) + 1);
+    }
+    return {
+        totalEvents: allEvents.length,
+        totalPages: page - 1,
+        statusBreakdown: Object.fromEntries(statusCounts),
+        groups,
+        uniqueNames: new Set(allEvents.map((e) => e.name)),
+        uniqueEntityTypes: new Set(allEvents.map((e) => e.entityType)),
+    };
+}
+/**
+ * Rank aggregation groups by count descending and compute percentages.
+ */
+function rankTopEvents(groups, totalEvents, topN) {
+    const sorted = Array.from(groups.values()).sort((a, b) => b.count - a.count);
+    return sorted.slice(0, topN).map((item, idx) => ({
+        rank: idx + 1,
+        name: item.name,
+        entityType: item.entityType,
+        status: item.status,
+        count: item.count,
+        percentage: totalEvents > 0
+            ? Math.round((item.count / totalEvents) * 1000) / 10
+            : 0,
+    }));
+}
+export function registerToolHandlers(server, ctx) {
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: TOOL_DEFINITIONS.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const toolName = request.params.name;
+        const args = request.params.arguments ?? {};
+        try {
+            // ------- config.validate ----------------------------------------------
+            if (toolName === "config.validate") {
+                const validation = validateConfig(ctx.config);
+                return json({
+                    ok: true,
+                    readyForApiCalls: validation.isReadyForApiCalls,
+                    validation,
+                    config: toSafeConfigSummary(ctx.config),
+                });
+            }
+            // ------- health.ping ---------------------------------------------------
+            if (toolName === "health.ping") {
+                const validation = validateConfig(ctx.config);
+                return json({
+                    ok: true,
+                    status: "ok",
+                    sdkClient: ctx.client ? "connected" : "not available",
+                    readyForApiCalls: validation.isReadyForApiCalls,
+                    validation,
+                    config: toSafeConfigSummary(ctx.config),
+                });
+            }
+            // ------- event.build ---------------------------------------------------
+            if (toolName === "event.build") {
+                const parsed = EventBuildInputSchema.parse(args);
+                const event = buildEventPayload(parsed, ctx.config);
+                return json({ ok: true, event });
+            }
+            // ------- event.send ----------------------------------------------------
+            if (toolName === "event.send") {
+                const parsed = EventPublishInputSchema.parse(args);
+                const event = buildEventPayload(parsed, ctx.config);
+                if (parsed.dryRun) {
+                    return json({
+                        ok: true,
+                        dryRun: true,
+                        mode: parsed.mode,
+                        event,
+                        note: "No API call made. Set dryRun=false to send.",
+                    });
+                }
+                const client = requireClient(ctx);
+                const result = await client.sendEvent(event, parsed.mode);
+                return json({
+                    ok: true,
+                    mode: parsed.mode,
+                    response: result,
+                });
+            }
+            // ------- event.get -----------------------------------------------------
+            if (toolName === "event.get") {
+                const parsed = EventGetInputSchema.parse(args);
+                const client = requireClient(ctx);
+                const event = await client.getEventById(parsed.eventId);
+                return json({ ok: true, event }, false, ctx.responseBudget);
+            }
+            // ------- event.list ----------------------------------------------------
+            if (toolName === "event.list") {
+                const parsed = EventListInputSchema.parse(args);
+                const client = requireClient(ctx);
+                const events = await client.getEvents(toEventQueryParams(parsed));
+                // Field projection: strip events down to requested fields only
+                if (parsed.fields && parsed.fields.length > 0 && events?.results) {
+                    const fieldSet = new Set(parsed.fields);
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    events.results = events.results.map((evt) => {
+                        const projected = {};
+                        for (const field of fieldSet) {
+                            if (field.startsWith("context.")) {
+                                const subKey = field.slice("context.".length);
+                                const evtCtx = evt.context;
+                                if (evtCtx && subKey in evtCtx) {
+                                    if (!projected.context)
+                                        projected.context = {};
+                                    projected.context[subKey] =
+                                        evtCtx[subKey];
+                                }
+                            }
+                            else if (field in evt) {
+                                projected[field] = evt[field];
+                            }
+                        }
+                        return projected;
+                    });
+                }
+                // Analyze mode: return grouped analysis instead of raw events
+                if (parsed.analyze && events?.results) {
+                    const analysis = analyzeEvents(events.results, events.hasMore ?? false);
+                    return json({ ok: true, analyze: true, ...analysis }, false, ctx.responseBudget);
+                }
+                return json({ ok: true, events }, false, ctx.responseBudget);
+            }
+            // ------- event.flowInspect ----------------------------------------------
+            if (toolName === "event.flowInspect") {
+                const parsed = EventFlowInspectInputSchema.parse(args);
+                const client = requireClient(ctx);
+                const baseParams = {
+                    "context.rootEntityRef": parsed.rootEntityRef,
+                    count: 500,
+                    ...(parsed.from ? { from: parsed.from } : {}),
+                    ...(parsed.to ? { to: parsed.to } : {}),
+                };
+                if (parsed.rootEntityType) {
+                    baseParams["context.rootEntityType"] = parsed.rootEntityType;
+                }
+                if (parsed.rootEntityId !== undefined) {
+                    baseParams["context.rootEntityId"] = parsed.rootEntityId;
+                }
+                const fetchPaged = async (extraParams) => {
+                    const all = [];
+                    let page = 1;
+                    let hasMore = true;
+                    while (hasMore && page <= parsed.maxPages) {
+                        const reqParams = {
+                            ...baseParams,
+                            ...extraParams,
+                            start: (page - 1) * 500 + 1,
+                        };
+                        const result = await client.getEvents(reqParams);
+                        const rows = Array.isArray(result?.results) ? result.results : [];
+                        if (rows.length === 0)
+                            break;
+                        for (const row of rows) {
+                            const rec = asRecord(row);
+                            if (rec)
+                                all.push(rec);
+                        }
+                        hasMore = result.hasMore ?? rows.length >= 500;
+                        page += 1;
+                    }
+                    return all;
+                };
+                const orchestrationEvents = await fetchPaged({
+                    eventType: "ORCHESTRATION",
+                });
+                let auditEvents = [];
+                if (parsed.includeAudit) {
+                    auditEvents = await fetchPaged({
+                        eventType: "ORCHESTRATION_AUDIT",
+                    });
+                }
+                // Fetch SCHEDULED events separately (if requested)
+                let scheduledEvents = [];
+                if (parsed.includeScheduled) {
+                    scheduledEvents = await fetchPaged({
+                        eventType: "ORCHESTRATION",
+                        eventStatus: "SCHEDULED",
+                    });
+                }
+                const statusCounts = countByKey(orchestrationEvents, (evt) => typeof evt.eventStatus === "string" ? evt.eventStatus : "UNKNOWN");
+                const entityTypeCounts = countByKey(orchestrationEvents, (evt) => {
+                    const ctxRec = asRecord(evt.context);
+                    return typeof ctxRec?.entityType === "string"
+                        ? ctxRec.entityType
+                        : "UNKNOWN";
+                });
+                const orchestrationNameCounts = countByKey(orchestrationEvents, (evt) => typeof evt.name === "string" ? evt.name : "UNKNOWN");
+                const categoryCounts = countByKey(auditEvents, (evt) => typeof evt.category === "string" ? evt.category : "UNKNOWN");
+                const actionEvents = auditEvents.filter((evt) => String(evt.category ?? "").toUpperCase() === "ACTION");
+                const actionNameCounts = countByKey(actionEvents, (evt) => typeof evt.name === "string" ? evt.name : "UNKNOWN");
+                const webhookActions = actionEvents
+                    .map((evt) => {
+                    const attrs = asAttributeMap(evt.attributes);
+                    const endpoint = attrs["Request Endpoint"];
+                    const isWebhook = String(evt.name ?? "")
+                        .toLowerCase()
+                        .includes("webhook") || endpoint !== undefined;
+                    if (!isWebhook)
+                        return null;
+                    const ctxRec = asRecord(evt.context);
+                    return {
+                        id: evt.id ?? null,
+                        name: evt.name ?? null,
+                        source: evt.source ?? null,
+                        generatedOn: evt.generatedOn ?? null,
+                        entityType: ctxRec?.entityType ?? null,
+                        entityRef: ctxRec?.entityRef ?? null,
+                        endpoint: endpoint ?? null,
+                        responseCode: attrs["Response code"] ?? null,
+                        responseReason: attrs["Response reason"] ?? null,
+                        responseBody: attrs["Response Body"] ?? null,
+                        responseHeaders: attrs["Response Headers"] ?? null,
+                        requestHeaders: attrs["Request Headers"] ?? null,
+                    };
+                })
+                    .filter((row) => row !== null)
+                    .slice(0, parsed.actionSampleLimit);
+                const mutationActions = actionEvents
+                    .map((evt) => {
+                    const attrs = asAttributeMap(evt.attributes);
+                    const request = asRecord(attrs.request);
+                    const requestName = asRecord(request?.name);
+                    const queryNameRaw = request?.queryName ?? requestName?.name;
+                    const queryName = typeof queryNameRaw === "string" ? queryNameRaw : null;
+                    const queryType = typeof request?.queryType === "string" ? request.queryType : null;
+                    const isMutation = (queryType &&
+                        queryType.toLowerCase().includes("mutation")) ||
+                        (queryName && /^(update|create|upsert|delete)/i.test(queryName));
+                    if (!isMutation)
+                        return null;
+                    const startTimer = toNumber(attrs.startTimer);
+                    const stopTimer = toNumber(attrs.stopTimer);
+                    const durationMs = startTimer !== null && stopTimer !== null
+                        ? Math.max(0, stopTimer - startTimer)
+                        : null;
+                    const variables = asRecord(request?.variables);
+                    const values = asRecord(variables?.values);
+                    const input = values?.input ?? null;
+                    const ctxRec = asRecord(evt.context);
+                    const response = asRecord(attrs.response);
+                    return {
+                        id: evt.id ?? null,
+                        name: evt.name ?? null,
+                        source: evt.source ?? null,
+                        generatedOn: evt.generatedOn ?? null,
+                        entityType: ctxRec?.entityType ?? null,
+                        entityRef: ctxRec?.entityRef ?? null,
+                        queryName,
+                        queryType,
+                        inputName: typeof request?.inputName === "string"
+                            ? request.inputName
+                            : null,
+                        queryString: typeof request?.queryString === "string"
+                            ? request.queryString
+                            : null,
+                        input,
+                        response: response?.inner ?? response ?? null,
+                        durationMs,
+                    };
+                })
+                    .filter((row) => row !== null)
+                    .slice(0, parsed.actionSampleLimit);
+                const sendEventActions = actionEvents
+                    .map((evt) => {
+                    const attrs = asAttributeMap(evt.attributes);
+                    const eventPayload = asRecord(attrs.Event);
+                    const eventNameRaw = attrs["Event Name"];
+                    const eventName = typeof eventNameRaw === "string" ? eventNameRaw : null;
+                    const isSendEvent = String(evt.name ?? "")
+                        .toLowerCase()
+                        .includes("send event") ||
+                        Boolean(eventPayload) ||
+                        Boolean(eventName);
+                    if (!isSendEvent)
+                        return null;
+                    const meta = asRecord(eventPayload?.meta);
+                    const scheduledOn = eventPayload?.scheduledOn ?? meta?.scheduledOn ?? null;
+                    const futureDated = attrs["Future Dated"] === true || scheduledOn !== null;
+                    return {
+                        id: evt.id ?? null,
+                        name: evt.name ?? null,
+                        source: evt.source ?? null,
+                        generatedOn: evt.generatedOn ?? null,
+                        eventName,
+                        futureDated,
+                        scheduledOn,
+                        event: eventPayload ?? null,
+                    };
+                })
+                    .filter((row) => row !== null)
+                    .slice(0, parsed.actionSampleLimit);
+                const scheduledActions = sendEventActions.filter((row) => row.futureDated === true);
+                const rulesetDurations = auditEvents
+                    .filter((evt) => String(evt.category ?? "") === "ruleSet")
+                    .map((evt) => {
+                    const attrs = asAttributeMap(evt.attributes);
+                    const startTimer = toNumber(attrs.startTimer);
+                    const stopTimer = toNumber(attrs.stopTimer);
+                    const durationMs = startTimer !== null && stopTimer !== null
+                        ? Math.max(0, stopTimer - startTimer)
+                        : null;
+                    return {
+                        id: evt.id ?? null,
+                        name: evt.name ?? null,
+                        generatedOn: evt.generatedOn ?? null,
+                        source: evt.source ?? null,
+                        durationMs,
+                    };
+                })
+                    .sort((a, b) => Number(b.durationMs ?? Number.NEGATIVE_INFINITY) -
+                    Number(a.durationMs ?? Number.NEGATIVE_INFINITY))
+                    .slice(0, parsed.actionSampleLimit);
+                // --- Snapshot extraction (category=snapshot) — gated by includeSnapshots ---
+                const snapshotRawCount = auditEvents.filter((evt) => String(evt.category ?? "") === "snapshot").length;
+                const snapshots = parsed.includeSnapshots
+                    ? auditEvents
+                        .filter((evt) => String(evt.category ?? "") === "snapshot")
+                        .map((evt) => {
+                        const attrs = asAttributeMap(evt.attributes);
+                        const ctxRec = asRecord(evt.context);
+                        return {
+                            id: evt.id ?? null,
+                            generatedOn: evt.generatedOn ?? null,
+                            entityType: ctxRec?.entityType ?? null,
+                            entityRef: ctxRec?.entityRef ?? null,
+                            status: attrs.status ?? null,
+                            items: attrs.items ?? null,
+                            attributes: attrs.attributes ?? null,
+                            customer: attrs.customer ?? null,
+                            toAddress: attrs.toAddress ?? null,
+                            fromAddress: attrs.fromAddress ?? null,
+                            deliveryType: attrs.deliveryType ?? null,
+                        };
+                    })
+                        .slice(0, parsed.actionSampleLimit)
+                    : undefined;
+                // --- Custom log extraction (category=CUSTOM) — gated by includeCustomLogs ---
+                const customLogRawCount = auditEvents.filter((evt) => String(evt.category ?? "").toUpperCase() === "CUSTOM").length;
+                const customLogs = parsed.includeCustomLogs
+                    ? auditEvents
+                        .filter((evt) => String(evt.category ?? "").toUpperCase() === "CUSTOM")
+                        .map((evt) => {
+                        const attrs = asAttributeMap(evt.attributes);
+                        const ctxRec = asRecord(evt.context);
+                        let logs = [];
+                        try {
+                            const raw = attrs.LogCollection;
+                            if (typeof raw === "string")
+                                logs = JSON.parse(raw)?.logs ?? [];
+                            else if (raw && typeof raw === "object")
+                                logs =
+                                    raw.logs ?? [];
+                        }
+                        catch {
+                            /* ignore parse errors */
+                        }
+                        return {
+                            id: evt.id ?? null,
+                            generatedOn: evt.generatedOn ?? null,
+                            entityType: ctxRec?.entityType ?? null,
+                            entityRef: ctxRec?.entityRef ?? null,
+                            source: evt.source ?? null,
+                            logs,
+                        };
+                    })
+                        .filter((row) => row.logs.length > 0)
+                        .slice(0, parsed.actionSampleLimit)
+                    : undefined;
+                // --- Rule props extraction (category=rule) — gated by includeRuleDetails ---
+                const ruleEventRawCount = auditEvents.filter((evt) => String(evt.category ?? "") === "rule").length;
+                const ruleEvents = parsed.includeRuleDetails
+                    ? auditEvents
+                        .filter((evt) => String(evt.category ?? "") === "rule")
+                        .map((evt) => {
+                        const attrs = asAttributeMap(evt.attributes);
+                        const startTimer = toNumber(attrs.startTimer);
+                        const stopTimer = toNumber(attrs.stopTimer);
+                        const durationMs = startTimer !== null && stopTimer !== null
+                            ? Math.max(0, stopTimer - startTimer)
+                            : null;
+                        return {
+                            id: evt.id ?? null,
+                            name: evt.name ?? null,
+                            generatedOn: evt.generatedOn ?? null,
+                            source: evt.source ?? null,
+                            ruleSet: attrs.ruleSet ?? null,
+                            props: attrs.props ?? null,
+                            durationMs,
+                        };
+                    })
+                        .slice(0, parsed.actionSampleLimit)
+                    : undefined;
+                const inspectedStatuses = new Set(parsed.inspectStatuses.map((status) => status.toUpperCase()));
+                const inspectCandidates = orchestrationEvents
+                    .filter((evt) => inspectedStatuses.has(String(evt.eventStatus ?? "").toUpperCase()))
+                    .slice(0, parsed.maxDrilldowns);
+                const inspectedEvents = [];
+                for (const candidate of inspectCandidates) {
+                    const eventId = typeof candidate.id === "string" ? candidate.id : undefined;
+                    if (!eventId)
+                        continue;
+                    const event = await client.getEventById(eventId);
+                    const eventRec = asRecord(event);
+                    const eventAttrs = asAttributeMap(eventRec?.attributes);
+                    inspectedEvents.push({
+                        eventId,
+                        name: candidate.name ?? null,
+                        eventStatus: candidate.eventStatus ?? null,
+                        closeMatches: eventAttrs.closeMatches ?? null,
+                        entityStatus: eventAttrs.entityStatus ?? null,
+                        message: eventAttrs.message ?? null,
+                        event,
+                    });
+                }
+                const compactOrchestrationEvents = parsed.includeEventDetails
+                    ? orchestrationEvents.map((evt) => {
+                        const ctxRec = asRecord(evt.context);
+                        return {
+                            id: evt.id ?? null,
+                            name: evt.name ?? null,
+                            eventStatus: evt.eventStatus ?? null,
+                            generatedOn: evt.generatedOn ?? null,
+                            source: evt.source ?? null,
+                            entityType: ctxRec?.entityType ?? null,
+                            entityRef: ctxRec?.entityRef ?? null,
+                            rootEntityType: ctxRec?.rootEntityType ?? null,
+                            rootEntityRef: ctxRec?.rootEntityRef ?? null,
+                            sourceEvents: ctxRec?.sourceEvents ?? [],
+                            attributes: asAttributeMap(evt.attributes),
+                        };
+                    })
+                    : undefined;
+                const compactAuditActionEvents = parsed.includeAuditDetails
+                    ? actionEvents.slice(0, parsed.actionSampleLimit).map((evt) => {
+                        const ctxRec = asRecord(evt.context);
+                        return {
+                            id: evt.id ?? null,
+                            name: evt.name ?? null,
+                            category: evt.category ?? null,
+                            generatedOn: evt.generatedOn ?? null,
+                            source: evt.source ?? null,
+                            entityType: ctxRec?.entityType ?? null,
+                            entityRef: ctxRec?.entityRef ?? null,
+                            attributes: asAttributeMap(evt.attributes),
+                        };
+                    })
+                    : undefined;
+                // --- Exception extraction — gated by includeExceptions ---
+                const exceptionRawCount = auditEvents.filter((evt) => String(evt.category ?? "").toLowerCase() === "exception" ||
+                    asAttributeMap(evt.attributes).exceptionClass !== undefined).length;
+                const exceptions = parsed.includeExceptions
+                    ? auditEvents
+                        .filter((evt) => String(evt.category ?? "").toLowerCase() === "exception" ||
+                        asAttributeMap(evt.attributes).exceptionClass !== undefined)
+                        .map((evt) => {
+                        const attrs = asAttributeMap(evt.attributes);
+                        const ctxRec = asRecord(evt.context);
+                        return {
+                            id: evt.id ?? null,
+                            generatedOn: evt.generatedOn ?? null,
+                            entityType: ctxRec?.entityType ?? null,
+                            entityRef: ctxRec?.entityRef ?? null,
+                            ruleset: attrs.ruleSetName ?? attrs.ruleSet ?? null,
+                            rule: attrs.ruleName ?? null,
+                            exceptionClass: attrs.exceptionClass ?? null,
+                            message: typeof attrs.exceptionMessage === "string"
+                                ? attrs.exceptionMessage
+                                : typeof attrs.exception === "string"
+                                    ? attrs.exception
+                                    : null,
+                        };
+                    })
+                        .slice(0, parsed.actionSampleLimit)
+                    : undefined;
+                // --- NO_MATCH closeMatches from ruleSet audit events — gated by includeNoMatchDetails ---
+                const noMatchAuditDetails = parsed.includeNoMatchDetails
+                    ? auditEvents
+                        .filter((evt) => String(evt.category ?? "") === "ruleSet" &&
+                        String(evt.eventStatus ?? "").toUpperCase() === "NO_MATCH")
+                        .map((evt) => {
+                        const attrs = asAttributeMap(evt.attributes);
+                        return {
+                            id: evt.id ?? null,
+                            rulesetName: evt.name ?? null,
+                            source: evt.source ?? null,
+                            generatedOn: evt.generatedOn ?? null,
+                            entityStatus: attrs.entityStatus ?? null,
+                            message: attrs.message ?? null,
+                            closeMatches: attrs.closeMatches ?? null,
+                        };
+                    })
+                    : undefined;
+                let crossEntity;
+                if (parsed.includeCrossEntity) {
+                    const crossEntityTypes = ["FULFILMENT_CHOICE", "FULFILMENT"];
+                    const sections = [];
+                    for (const childType of crossEntityTypes) {
+                        const childOrch = await fetchPaged({
+                            eventType: "ORCHESTRATION",
+                            "context.rootEntityRef": parsed.rootEntityRef,
+                            "context.entityType": childType,
+                        });
+                        if (childOrch.length === 0)
+                            continue;
+                        const childStatusCounts = countByKey(childOrch, (evt) => typeof evt.eventStatus === "string" ? evt.eventStatus : "UNKNOWN");
+                        sections.push({
+                            entityType: childType,
+                            orchestrationCount: childOrch.length,
+                            statusCounts: childStatusCounts,
+                            events: childOrch.map((evt) => {
+                                const ctxRec = asRecord(evt.context);
+                                return {
+                                    id: evt.id ?? null,
+                                    name: evt.name ?? null,
+                                    eventStatus: evt.eventStatus ?? null,
+                                    generatedOn: evt.generatedOn ?? null,
+                                    entityRef: ctxRec?.entityRef ?? null,
+                                };
+                            }),
+                        });
+                    }
+                    crossEntity = sections.length > 0 ? sections : undefined;
+                }
+                const noMatchCount = statusCounts.NO_MATCH ?? 0;
+                const pendingCount = statusCounts.PENDING ?? 0;
+                const failedCount = statusCounts.FAILED ?? 0;
+                const scheduledStatusCount = statusCounts.SCHEDULED ?? 0;
+                const recommendations = [];
+                if (noMatchCount > 0) {
+                    recommendations.push("Review NO_MATCH events for missing rulesets or event-name mismatches.");
+                }
+                if (pendingCount > 0) {
+                    recommendations.push("Check whether PENDING events have completed audit chains (status lag vs real blockage).");
+                }
+                if (failedCount > 0) {
+                    recommendations.push("Investigate FAILED events — check audit exceptions for stack traces and rule errors.");
+                }
+                if (webhookActions.some((w) => Number(w.responseCode) >= 400)) {
+                    recommendations.push("Investigate webhook endpoint/auth failures from Response code/Body fields.");
+                }
+                if (exceptionRawCount > 0) {
+                    recommendations.push("Rule exceptions detected — check exceptionClass and message for root cause.");
+                }
+                // --- Shared envelope fields ---
+                const totals = {
+                    orchestrationCount: orchestrationEvents.length,
+                    auditCount: auditEvents.length,
+                    actionCount: actionEvents.length,
+                    mutationActionCount: mutationActions.length,
+                    webhookActionCount: webhookActions.length,
+                    sendEventActionCount: sendEventActions.length,
+                    scheduledCount: scheduledEvents.length,
+                    exceptionCount: exceptionRawCount,
+                    snapshotCount: snapshotRawCount,
+                    customLogCount: customLogRawCount,
+                    ruleEventCount: ruleEventRawCount,
+                };
+                const envelope = {
+                    ok: true,
+                    rootEntityRef: parsed.rootEntityRef,
+                    rootEntityType: parsed.rootEntityType ?? null,
+                    rootEntityId: parsed.rootEntityId ?? null,
+                    window: { from: parsed.from ?? null, to: parsed.to ?? null },
+                    paging: { maxPages: parsed.maxPages, pageSize: 500 },
+                    compact: parsed.compact,
+                };
+                // ========= COMPACT MODE =========
+                if (parsed.compact) {
+                    // --- analysis.statusFlow: ordered unique statuses seen ---
+                    const statusFlow = [];
+                    const seenStatuses = new Set();
+                    for (const evt of orchestrationEvents) {
+                        const s = typeof evt.eventStatus === "string" ? evt.eventStatus : null;
+                        if (s && !seenStatuses.has(s)) {
+                            seenStatuses.add(s);
+                            statusFlow.push(s);
+                        }
+                    }
+                    // --- analysis.entityTypes ---
+                    const entityTypes = Object.keys(entityTypeCounts);
+                    // --- analysis.timespan ---
+                    const timestamps = orchestrationEvents
+                        .map((evt) => {
+                        const g = evt.generatedOn;
+                        return typeof g === "string" ? new Date(g).getTime() : NaN;
+                    })
+                        .filter((t) => !Number.isNaN(t));
+                    const timespan = timestamps.length > 0
+                        ? {
+                            first: new Date(Math.min(...timestamps)).toISOString(),
+                            last: new Date(Math.max(...timestamps)).toISOString(),
+                            durationMs: Math.max(...timestamps) - Math.min(...timestamps),
+                        }
+                        : null;
+                    // --- analysis.failedWebhookEndpoints ---
+                    const failedWebhookEndpoints = webhookActions
+                        .filter((w) => Number(w.responseCode) >= 400)
+                        .map((w) => String(w.endpoint ?? "unknown"))
+                        .filter((v, i, a) => a.indexOf(v) === i);
+                    // --- analysis.slowestRulesets (top 3) ---
+                    const slowestRulesets = rulesetDurations
+                        .filter((r) => r.durationMs !== null)
+                        .slice(0, 3)
+                        .map((r) => ({ name: r.name ?? "unknown", durationMs: r.durationMs }));
+                    const findings = [];
+                    if (noMatchCount > 0) {
+                        findings.push({
+                            code: "NO_MATCH_EVENTS",
+                            severity: "CRITICAL",
+                            message: `${noMatchCount} NO_MATCH event(s) — missing rulesets or event-name mismatches`,
+                        });
+                    }
+                    if (failedCount > 0) {
+                        findings.push({
+                            code: "FAILED_EVENTS",
+                            severity: "HIGH",
+                            message: `${failedCount} FAILED event(s) — check audit exceptions for stack traces`,
+                        });
+                    }
+                    if (failedWebhookEndpoints.length > 0) {
+                        findings.push({
+                            code: "FAILED_WEBHOOKS",
+                            severity: "HIGH",
+                            message: `${failedWebhookEndpoints.length} webhook endpoint(s) returned errors: ${failedWebhookEndpoints.join(", ")}`,
+                        });
+                    }
+                    if (exceptionRawCount > 0) {
+                        findings.push({
+                            code: "EXCEPTIONS_FOUND",
+                            severity: "HIGH",
+                            message: `${exceptionRawCount} rule exception(s) detected`,
+                        });
+                    }
+                    if (pendingCount > 0) {
+                        findings.push({
+                            code: "PENDING_EVENTS",
+                            severity: "MEDIUM",
+                            message: `${pendingCount} PENDING event(s) — may indicate processing lag or real blockage`,
+                        });
+                    }
+                    const slowThreshold = 1000;
+                    const slowCount = rulesetDurations.filter((r) => r.durationMs !== null && r.durationMs > slowThreshold).length;
+                    if (slowCount > 0) {
+                        findings.push({
+                            code: "SLOW_RULESETS",
+                            severity: "MEDIUM",
+                            message: `${slowCount} ruleset(s) exceeded ${slowThreshold}ms`,
+                        });
+                    }
+                    // --- compact audit: only failures for webhooks (stripped), top 5 mutations by name ---
+                    const compactWebhookActions = webhookActions
+                        .filter((w) => Number(w.responseCode) >= 400)
+                        .map((w) => ({
+                        id: w.id,
+                        source: w.source,
+                        endpoint: w.endpoint,
+                        responseCode: w.responseCode,
+                        responseReason: w.responseReason,
+                        entityType: w.entityType,
+                        entityRef: w.entityRef,
+                    }));
+                    const mutationNameGroups = {};
+                    for (const m of mutationActions) {
+                        const key = m.queryName ?? "unknown";
+                        mutationNameGroups[key] = (mutationNameGroups[key] ?? 0) + 1;
+                    }
+                    const compactMutationActions = Object.entries(mutationNameGroups)
+                        .sort(([, a], [, b]) => b - a)
+                        .slice(0, 5)
+                        .map(([queryName, count]) => ({ queryName, count }));
+                    // --- compact diagnostics: summary only for inspected events ---
+                    const compactInspectedEvents = inspectedEvents.map((evt) => ({
+                        eventId: evt.eventId,
+                        name: evt.name,
+                        eventStatus: evt.eventStatus,
+                        closeMatchCount: Array.isArray(evt.closeMatches)
+                            ? evt.closeMatches.length
+                            : 0,
+                    }));
+                    // --- compact crossEntity: summary without events array ---
+                    const compactCrossEntity = crossEntity?.map((section) => ({
+                        entityType: section.entityType,
+                        orchestrationCount: section.orchestrationCount,
+                        statusCounts: section.statusCounts,
+                    }));
+                    return json({
+                        ...envelope,
+                        totals,
+                        orchestration: {
+                            statusCounts,
+                            entityTypeCounts,
+                            topNames: topCounts(orchestrationNameCounts, 10),
+                        },
+                        scheduled: scheduledEvents.length > 0
+                            ? { count: scheduledEvents.length }
+                            : undefined,
+                        audit: parsed.includeAudit
+                            ? {
+                                categoryCounts,
+                                webhookActions: compactWebhookActions.length > 0
+                                    ? compactWebhookActions
+                                    : undefined,
+                                mutationActions: compactMutationActions.length > 0
+                                    ? compactMutationActions
+                                    : undefined,
+                                sendEventActions: {
+                                    count: sendEventActions.length,
+                                    scheduledCount: scheduledActions.length,
+                                },
+                                rulesetDurations: rulesetDurations
+                                    .filter((r) => r.durationMs !== null)
+                                    .slice(0, 5)
+                                    .map((r) => ({
+                                    name: r.name ?? "unknown",
+                                    durationMs: r.durationMs,
+                                })),
+                                exceptions,
+                            }
+                            : undefined,
+                        diagnostics: {
+                            noMatchCount,
+                            pendingCount,
+                            failedCount,
+                            scheduledCount: scheduledStatusCount,
+                            inspectStatuses: parsed.inspectStatuses,
+                            inspectedEvents: compactInspectedEvents,
+                            noMatchAuditDetails,
+                        },
+                        crossEntity: compactCrossEntity,
+                        analysis: {
+                            statusFlow,
+                            entityTypes,
+                            timespan,
+                            failedWebhookEndpoints,
+                            slowestRulesets,
+                            findings,
+                        },
+                        recommendations: recommendations.length > 0 ? recommendations : undefined,
+                    }, false, ctx.responseBudget);
+                }
+                // ========= FULL MODE (compact: false) =========
+                return json({
+                    ...envelope,
+                    totals,
+                    orchestration: {
+                        statusCounts,
+                        entityTypeCounts,
+                        topNames: topCounts(orchestrationNameCounts, 30),
+                        events: compactOrchestrationEvents,
+                    },
+                    scheduled: scheduledEvents.length > 0
+                        ? scheduledEvents.map((evt) => {
+                            const ctxRec = asRecord(evt.context);
+                            return {
+                                id: evt.id ?? null,
+                                name: evt.name ?? null,
+                                eventStatus: evt.eventStatus ?? null,
+                                generatedOn: evt.generatedOn ?? null,
+                                entityType: ctxRec?.entityType ?? null,
+                                entityRef: ctxRec?.entityRef ?? null,
+                            };
+                        })
+                        : undefined,
+                    audit: parsed.includeAudit
+                        ? {
+                            categoryCounts,
+                            topActionNames: topCounts(actionNameCounts, 30),
+                            webhookActions,
+                            mutationActions,
+                            sendEventActions,
+                            scheduledActions,
+                            rulesetDurations,
+                            exceptions,
+                            snapshots,
+                            customLogs,
+                            ruleEvents,
+                            actionEvents: compactAuditActionEvents,
+                        }
+                        : undefined,
+                    diagnostics: {
+                        noMatchCount,
+                        pendingCount,
+                        failedCount,
+                        scheduledCount: scheduledStatusCount,
+                        inspectStatuses: parsed.inspectStatuses,
+                        inspectedEvents,
+                        noMatchAuditDetails,
+                    },
+                    crossEntity,
+                    recommendations: recommendations.length > 0 ? recommendations : undefined,
+                }, false, ctx.responseBudget);
+            }
+            // ------- metrics.query -------------------------------------------------
+            if (toolName === "metrics.query") {
+                const parsed = MetricsQueryInputSchema.parse(args);
+                if (parsed.type === "range" && (!parsed.start || !parsed.end || !parsed.step)) {
+                    throw new ToolError("VALIDATION_ERROR", "Range queries require start, end, and step.");
+                }
+                const client = requireClient(ctx);
+                const response = await client.queryPrometheus(parsed);
+                return json({
+                    ok: response.status === "success",
+                    status: response.status,
+                    data: response.data,
+                    errorType: response.errorType,
+                    error: response.error,
+                    warnings: response.warnings,
+                }, false, ctx.responseBudget);
+            }
+            // ------- workflow.transitions -------------------------------------------
+            if (toolName === "workflow.transitions") {
+                const parsed = TransitionActionsInputSchema.parse(args);
+                const client = requireClient(ctx);
+                const payload = resolveTransitionRequest(parsed, ctx.config.retailerId);
+                const result = await client.getTransitions(payload);
+                return json({ ok: true, response: result }, false, ctx.responseBudget);
+            }
+            // ------- plugin.list ---------------------------------------------------
+            if (toolName === "plugin.list") {
+                const client = requireClient(ctx);
+                const parsed = PluginListInputSchema.parse(args);
+                const allPlugins = await client.getPlugins();
+                let plugins = typeof allPlugins === "object" && allPlugins !== null
+                    ? allPlugins
+                    : {};
+                // Name filter
+                if (parsed.name) {
+                    const filter = parsed.name.toLowerCase();
+                    plugins = Object.fromEntries(Object.entries(plugins).filter(([key]) => key.toLowerCase().includes(filter)));
+                }
+                // Compact mode: strip parameters and eventAttributes, keep only ruleInfo
+                if (parsed.compact) {
+                    plugins = Object.fromEntries(Object.entries(plugins).map(([key, val]) => {
+                        const entry = val;
+                        if (entry && typeof entry === "object") {
+                            return [key, { ruleInfo: entry.ruleInfo }];
+                        }
+                        return [key, val];
+                    }));
+                }
+                return json({
+                    ok: true,
+                    count: Object.keys(plugins).length,
+                    plugins,
+                }, false, ctx.responseBudget);
+            }
+            // ------- graphql.query -------------------------------------------------
+            if (toolName === "graphql.query") {
+                const client = requireClient(ctx);
+                const parsed = GraphQLQueryInputSchema.parse(args);
+                const isMutation = isMutationOperation(parsed.query);
+                const payload = {
+                    query: parsed.query,
+                    variables: toSdkVariables(parsed.variables),
+                };
+                const result = await client.graphql(payload, { retry: !isMutation });
+                if (parsed.summarize) {
+                    const summary = summarizeConnection(result);
+                    if (summary) {
+                        return json({ ok: true, summarized: true, ...summary }, false, ctx.responseBudget);
+                    }
+                }
+                return json({ ok: true, response: result }, false, ctx.responseBudget);
+            }
+            // ------- batch.create --------------------------------------------------
+            if (toolName === "batch.create") {
+                const client = requireClient(ctx);
+                const parsed = BatchCreateInputSchema.parse(args);
+                const retailerId = parsed.retailerId ?? ctx.config.retailerId;
+                if (!retailerId) {
+                    throw new ToolError("VALIDATION_ERROR", "retailerId is required. Set FLUENT_RETAILER_ID or pass retailerId.");
+                }
+                const payload = {
+                    name: parsed.name,
+                    retailerId,
+                    meta: {
+                        source: "fluent-mcp-extn",
+                        ...(parsed.entityType ? { entityType: parsed.entityType } : {}),
+                        ...(parsed.action ? { action: parsed.action } : {}),
+                    },
+                };
+                const result = await client.createJob(payload);
+                return json({ ok: true, job: result });
+            }
+            // ------- batch.send ----------------------------------------------------
+            if (toolName === "batch.send") {
+                const client = requireClient(ctx);
+                const parsed = BatchSendInputSchema.parse(args);
+                // Batch payload shape varies by integration. We validate a baseline
+                // contract here and pass through full payload details to the SDK.
+                const result = await client.sendBatch(parsed.jobId, parsed.payload);
+                return json({ ok: true, batch: result });
+            }
+            // ------- batch.status --------------------------------------------------
+            if (toolName === "batch.status") {
+                const client = requireClient(ctx);
+                const parsed = BatchStatusInputSchema.parse(args);
+                const result = await client.getJobStatus(parsed.jobId);
+                return json({ ok: true, status: result });
+            }
+            // ------- batch.batchStatus ---------------------------------------------
+            if (toolName === "batch.batchStatus") {
+                const client = requireClient(ctx);
+                const parsed = BatchGetBatchStatusInputSchema.parse(args);
+                const result = await client.getBatchStatus(parsed.jobId, parsed.batchId);
+                return json({ ok: true, batchStatus: result });
+            }
+            // ------- batch.results -------------------------------------------------
+            if (toolName === "batch.results") {
+                const client = requireClient(ctx);
+                const parsed = BatchResultsInputSchema.parse(args);
+                const result = await client.getJobResults(parsed.jobId);
+                return json({ ok: true, results: result });
+            }
+            // ------- graphql.queryAll -----------------------------------------------
+            if (toolName === "graphql.queryAll") {
+                const client = requireClient(ctx);
+                const parsed = GraphQLQueryAllInputSchema.parse(args);
+                const payload = {
+                    query: parsed.query,
+                    variables: toSdkVariables(parsed.variables),
+                    pagination: {
+                        enabled: true,
+                        maxPages: parsed.maxPages,
+                        maxRecords: parsed.maxRecords,
+                        timeoutMs: parsed.timeoutMs,
+                        direction: parsed.direction,
+                    },
+                    errorHandling: parsed.errorHandling,
+                };
+                const result = await client.graphqlPaginated(payload);
+                const pagination = result.extensions?.autoPagination ?? null;
+                if (parsed.summarize) {
+                    const summary = summarizeConnection(result);
+                    if (summary) {
+                        return json({ ok: true, summarized: true, ...summary, pagination }, false, ctx.responseBudget);
+                    }
+                }
+                return json({ ok: true, response: result, pagination }, false, ctx.responseBudget);
+            }
+            // ------- graphql.batchMutate --------------------------------------------
+            if (toolName === "graphql.batchMutate") {
+                const client = requireClient(ctx);
+                const parsed = GraphQLBatchMutateInputSchema.parse(args);
+                const batchSize = parsed.inputs.length;
+                const mutationConfig = {
+                    mutation: parsed.mutation,
+                    returnFields: parsed.returnFields ?? ["id", "ref"],
+                    operationName: parsed.operationName,
+                };
+                // Build the aliased mutation query
+                const query = buildAliasedMutationQuery(mutationConfig, batchSize);
+                // Build variables: { input1: inputs[0], input2: inputs[1], ... }
+                const variables = {};
+                for (let i = 0; i < batchSize; i++) {
+                    variables[`input${i + 1}`] = parsed.inputs[i];
+                }
+                const gqlPayload = {
+                    query,
+                    variables: toSdkVariables(variables),
+                    pagination: { enabled: false },
+                };
+                const response = await client.graphql(gqlPayload, { retry: false });
+                const batchResult = parseAliasedMutationResponse(response, batchSize, parsed.mutation, parsed.inputs);
+                return json({
+                    ok: batchResult.allSucceeded,
+                    summary: formatErrorSummary(batchResult),
+                    executed: batchResult.executed,
+                    failed: batchResult.failed,
+                    allSucceeded: batchResult.allSucceeded,
+                    allFailed: batchResult.allFailed,
+                    results: batchResult.results,
+                    errors: batchResult.errors.length > 0 ? batchResult.errors : undefined,
+                    query,
+                });
+            }
+            // ------- graphql.introspect ---------------------------------------------
+            if (toolName === "graphql.introspect") {
+                const client = requireClient(ctx);
+                const parsed = GraphQLIntrospectInputSchema.parse(args);
+                const introspectionService = new GraphQLIntrospectionService(client.asGraphQLCapable());
+                // Mode: list mutations
+                if (parsed.listMutations) {
+                    const mutations = await introspectionService.getMutations();
+                    return json({ ok: true, mutations, count: mutations.length });
+                }
+                // Mode: list queries
+                if (parsed.listQueries) {
+                    const schema = await introspectionService.getSchema();
+                    const queryType = schema.types.find((t) => t.name === schema.queryType?.name);
+                    const queries = queryType?.fields?.map((f) => f.name) ?? [];
+                    return json({ ok: true, queries, count: queries.length });
+                }
+                // Mode: inspect mutation
+                if (parsed.mutation) {
+                    const mutation = await introspectionService.getMutation(parsed.mutation);
+                    if (!mutation) {
+                        throw new ToolError("VALIDATION_ERROR", `Mutation '${parsed.mutation}' not found in schema.`);
+                    }
+                    return json({ ok: true, mutation });
+                }
+                // Mode: inspect type
+                if (parsed.type) {
+                    const inputType = await introspectionService.getInputType(parsed.type);
+                    if (!inputType) {
+                        throw new ToolError("VALIDATION_ERROR", `Input type '${parsed.type}' not found in schema.`);
+                    }
+                    return json({ ok: true, inputType });
+                }
+                throw new ToolError("VALIDATION_ERROR", "Specify one of: type, mutation, listMutations, or listQueries.");
+            }
+            // ------- connection.test ------------------------------------------------
+            if (toolName === "connection.test") {
+                const client = requireClient(ctx);
+                // FluentConnectionTester expects a FluentClient with graphql() method.
+                // Our adapter satisfies this duck-typed contract.
+                const tester = new FluentConnectionTester(client.asGraphQLCapable(), {
+                    retailerId: ctx.config.retailerId ?? "unknown",
+                    logger: console,
+                });
+                const result = await tester.testConnection();
+                return json({
+                    ok: result.success,
+                    duration: result.duration,
+                    ...(result.success
+                        ? { details: result.details }
+                        : { error: result.error }),
+                });
+            }
+            // ------- webhook.validate -----------------------------------------------
+            if (toolName === "webhook.validate") {
+                const parsed = WebhookValidateInputSchema.parse(args);
+                const payload = parsed.payload;
+                // Basic field validation
+                const missingFields = [];
+                if (!payload.name)
+                    missingFields.push("name");
+                if (!payload.id)
+                    missingFields.push("id");
+                if (!payload.retailerId)
+                    missingFields.push("retailerId");
+                const basicValid = missingFields.length === 0;
+                // Signature validation (if signature + publicKey provided)
+                if (parsed.signature && parsed.publicKey) {
+                    const algorithmMap = {
+                        SHA512withRSA: SignatureAlgorithm.SHA512_WITH_RSA,
+                        MD5withRSA: SignatureAlgorithm.MD5_WITH_RSA,
+                    };
+                    const algorithm = algorithmMap[parsed.algorithm] ?? SignatureAlgorithm.SHA512_WITH_RSA;
+                    // Use raw body if provided (preserves exact bytes the signature
+                    // was computed over); fall back to re-serialized JSON otherwise.
+                    const hasRawBody = typeof parsed.rawBody === "string" && parsed.rawBody.length > 0;
+                    const rawPayload = hasRawBody
+                        ? parsed.rawBody
+                        : JSON.stringify(parsed.payload);
+                    try {
+                        const noopLogger = {
+                            debug: () => { },
+                            info: () => { },
+                            warn: () => { },
+                            error: () => { },
+                        };
+                        const validator = new WebhookValidationService({ algorithm, strictValidation: false }, noopLogger);
+                        const sigResult = await validator.validateWebhookSignature(rawPayload, parsed.signature, parsed.publicKey, algorithm);
+                        const isValid = sigResult.isValid && basicValid;
+                        if (isValid) {
+                            return json({
+                                ok: true,
+                                basicValidation: { valid: basicValid, missingFields },
+                                signatureValidation: {
+                                    valid: sigResult.isValid,
+                                    algorithm: sigResult.algorithm,
+                                    payloadSource: hasRawBody ? "rawBody" : "json-stringify",
+                                },
+                            });
+                        }
+                        const failureMessage = !basicValid
+                            ? "Basic validation failed: missing required fields."
+                            : sigResult.error || "Signature validation failed.";
+                        const failure = toToolFailure(new ToolError("VALIDATION_ERROR", failureMessage, {
+                            details: {
+                                basicValidation: { valid: basicValid, missingFields },
+                                signatureValidation: {
+                                    valid: sigResult.isValid,
+                                    algorithm: sigResult.algorithm,
+                                    payloadSource: hasRawBody ? "rawBody" : "json-stringify",
+                                    error: sigResult.error ?? undefined,
+                                },
+                            },
+                        }));
+                        return json({
+                            ...failure,
+                            basicValidation: { valid: basicValid, missingFields },
+                            signatureValidation: {
+                                valid: sigResult.isValid,
+                                algorithm: sigResult.algorithm,
+                                payloadSource: hasRawBody ? "rawBody" : "json-stringify",
+                                error: sigResult.error ?? undefined,
+                            },
+                        });
+                    }
+                    catch (e) {
+                        const message = e instanceof Error ? e.message : String(e);
+                        const failure = toToolFailure(new ToolError("VALIDATION_ERROR", `Signature validation failed: ${message}`, {
+                            details: {
+                                basicValidation: { valid: basicValid, missingFields },
+                                signatureValidation: {
+                                    valid: false,
+                                    algorithm: parsed.algorithm,
+                                    payloadSource: hasRawBody ? "rawBody" : "json-stringify",
+                                    error: message,
+                                },
+                            },
+                        }));
+                        return json({
+                            ...failure,
+                            basicValidation: { valid: basicValid, missingFields },
+                            signatureValidation: {
+                                valid: false,
+                                algorithm: parsed.algorithm,
+                                payloadSource: hasRawBody ? "rawBody" : "json-stringify",
+                                error: message,
+                            },
+                        });
+                    }
+                }
+                // Basic validation only
+                return json({
+                    ok: basicValid,
+                    basicValidation: { valid: basicValid, missingFields },
+                    note: basicValid
+                        ? "Basic field validation passed. Provide signature + publicKey for signature verification."
+                        : "Basic validation failed: missing required fields.",
+                });
+            }
+            // ------- metrics.healthCheck -----------------------------------------------
+            if (toolName === "metrics.healthCheck") {
+                const parsed = MetricsHealthCheckInputSchema.parse(args);
+                const client = requireClient(ctx);
+                const window = parsed.window;
+                const thresholds = parsed.thresholds;
+                let source = "prometheus";
+                let statusBreakdown = {};
+                let totalEvents = 0;
+                let topEvents = [];
+                try {
+                    // Query 1: status breakdown
+                    const statusResponse = await client.queryPrometheus({
+                        query: `sum by (status) (increase(rubix_event_runtime_seconds_count[${window}]))`,
+                        type: "instant",
+                    });
+                    // Parse Prometheus vector response
+                    const statusResult = statusResponse.data?.result ?? [];
+                    for (const item of statusResult) {
+                        const status = item.metric?.status ?? "UNKNOWN";
+                        const value = Math.round(parseFloat(item.value?.[1] ?? "0"));
+                        if (value > 0) {
+                            statusBreakdown[status] = value;
+                            totalEvents += value;
+                        }
+                    }
+                    // Query 2: top events by name+entityType+status (if requested)
+                    if (parsed.includeTopEvents && totalEvents > 0) {
+                        const topResponse = await client.queryPrometheus({
+                            query: `sort_desc(sum by (event_name, entity_type, status) (increase(rubix_event_runtime_seconds_count[${window}])))`,
+                            type: "instant",
+                        });
+                        const topResult = topResponse.data?.result ?? [];
+                        const parsedResults = [];
+                        for (const item of topResult) {
+                            const count = Math.round(parseFloat(item.value?.[1] ?? "0"));
+                            if (count > 0) {
+                                parsedResults.push({
+                                    name: item.metric?.event_name ?? "unknown",
+                                    entityType: item.metric?.entity_type ?? "unknown",
+                                    status: item.metric?.status ?? "unknown",
+                                    count,
+                                });
+                            }
+                        }
+                        topEvents = parsedResults.slice(0, parsed.topN).map((item, idx) => ({
+                            rank: idx + 1,
+                            name: item.name,
+                            entityType: item.entityType,
+                            status: item.status,
+                            count: item.count,
+                            percentage: totalEvents > 0
+                                ? Math.round((item.count / totalEvents) * 1000) / 10
+                                : 0,
+                        }));
+                    }
+                }
+                catch {
+                    // Prometheus unavailable — fall back to Event API
+                    source = "event_api";
+                    const windowMs = parseWindowMs(window);
+                    const now = new Date();
+                    const from = new Date(now.getTime() - windowMs).toISOString();
+                    const to = now.toISOString();
+                    const agg = await aggregateEventsFromApi(client, {
+                        from,
+                        to,
+                        maxPages: 10,
+                        eventType: "ORCHESTRATION",
+                    });
+                    totalEvents = agg.totalEvents;
+                    statusBreakdown = agg.statusBreakdown;
+                    if (parsed.includeTopEvents) {
+                        topEvents = rankTopEvents(agg.groups, agg.totalEvents, parsed.topN);
+                    }
+                }
+                // Apply heuristic findings
+                const findings = [];
+                const failedCount = statusBreakdown["FAILED"] ?? 0;
+                const noMatchCount = statusBreakdown["NO_MATCH"] ?? 0;
+                const pendingCount = statusBreakdown["PENDING"] ?? 0;
+                const failureRate = totalEvents > 0
+                    ? Math.round((failedCount / totalEvents) * 1000) / 10
+                    : 0;
+                const pendingRate = totalEvents > 0
+                    ? Math.round((pendingCount / totalEvents) * 1000) / 10
+                    : 0;
+                // Check 1: Failure rate
+                if (failureRate > thresholds.failureRate) {
+                    findings.push({
+                        severity: "HIGH",
+                        type: "HIGH_FAILURE_RATE",
+                        message: `Failure rate ${failureRate}% exceeds ${thresholds.failureRate}% threshold (${failedCount} of ${totalEvents} events)`,
+                        value: failureRate,
+                        threshold: thresholds.failureRate,
+                    });
+                }
+                // Check 2: NO_MATCH present
+                if (noMatchCount > 0) {
+                    findings.push({
+                        severity: "CRITICAL",
+                        type: "NO_MATCH_PRESENT",
+                        message: `${noMatchCount} NO_MATCH events — event names not matching any workflow ruleset`,
+                        value: noMatchCount,
+                        threshold: 0,
+                    });
+                }
+                // Check 3: PENDING queue
+                if (pendingRate > thresholds.pendingRate) {
+                    findings.push({
+                        severity: "MEDIUM",
+                        type: "HIGH_PENDING_RATE",
+                        message: `Pending rate ${pendingRate}% exceeds ${thresholds.pendingRate}% threshold — async queue may be backed up`,
+                        value: pendingRate,
+                        threshold: thresholds.pendingRate,
+                    });
+                }
+                // Check 4: Single event dominance
+                if (topEvents.length > 0 && topEvents[0].percentage > thresholds.dominanceRate) {
+                    findings.push({
+                        severity: "MEDIUM",
+                        type: "EVENT_DOMINANCE",
+                        message: `"${topEvents[0].name}" (${topEvents[0].entityType}) accounts for ${topEvents[0].percentage}% of all events — possible runaway loop`,
+                        value: topEvents[0].percentage,
+                        threshold: thresholds.dominanceRate,
+                    });
+                }
+                // Build recommendations
+                const recommendations = [];
+                if (findings.some((f) => f.type === "HIGH_FAILURE_RATE")) {
+                    recommendations.push("Run event.list({ eventStatus: \"FAILED\", from: \"<recent>\", count: 50 }) to identify failing events");
+                    recommendations.push("Hand off to /fluent-trace for root cause analysis");
+                }
+                if (findings.some((f) => f.type === "NO_MATCH_PRESENT")) {
+                    recommendations.push("Verify event names match workflow ruleset names using /fluent-workflow-analyzer");
+                    recommendations.push("Check entity subtype and workflow deployment status");
+                }
+                if (findings.some((f) => f.type === "HIGH_PENDING_RATE")) {
+                    recommendations.push("Check platform health — PENDING events should clear within seconds");
+                }
+                if (findings.some((f) => f.type === "EVENT_DOMINANCE")) {
+                    recommendations.push("Investigate if a SendEvent rule is creating a circular event chain");
+                }
+                const healthy = findings.length === 0;
+                return json({
+                    ok: true,
+                    healthy,
+                    source,
+                    summary: {
+                        window,
+                        totalEvents,
+                        failureRate,
+                        pendingRate,
+                        statusBreakdown,
+                    },
+                    findings,
+                    topEvents: parsed.includeTopEvents ? topEvents : undefined,
+                    recommendations: recommendations.length > 0 ? recommendations : undefined,
+                });
+            }
+            // ------- metrics.sloReport -----------------------------------------------
+            if (toolName === "metrics.sloReport") {
+                const parsed = MetricsSloReportInputSchema.parse(args);
+                const client = requireClient(ctx);
+                const window = parsed.window;
+                const thresholds = parsed.thresholds;
+                const promQueries = {
+                    totalEvents: `sum(increase(rubix_event_runtime_seconds_count[${window}]))`,
+                    failedEvents: `sum(increase(rubix_event_runtime_seconds_count{status="FAILED"}[${window}]))`,
+                    noMatchEvents: `sum(increase(rubix_event_runtime_seconds_count{status="NO_MATCH"}[${window}]))`,
+                    pendingEvents: `sum(increase(rubix_event_runtime_seconds_count{status="PENDING"}[${window}]))`,
+                    runtimeP95Seconds: `histogram_quantile(0.95, sum by (le) (increase(rubix_event_runtime_seconds_bucket[${window}])))`,
+                    inflightP95Seconds: `histogram_quantile(0.95, sum by (le) (increase(rubix_event_inflight_latency_seconds_bucket[${window}])))`,
+                };
+                const now = new Date();
+                const from = new Date(now.getTime() - parseWindowMs(window)).toISOString();
+                const to = now.toISOString();
+                let source = "prometheus";
+                let totalEvents = 0;
+                let failedEvents = 0;
+                let noMatchEvents = 0;
+                let pendingEvents = 0;
+                let runtimeP95Seconds = null;
+                let inflightP95Seconds = null;
+                try {
+                    const [totalResponse, failedResponse, noMatchResponse, pendingResponse, runtimeP95Response, inflightP95Response,] = await Promise.all([
+                        client.queryPrometheus({
+                            query: promQueries.totalEvents,
+                            type: "instant",
+                        }),
+                        client.queryPrometheus({
+                            query: promQueries.failedEvents,
+                            type: "instant",
+                        }),
+                        client.queryPrometheus({
+                            query: promQueries.noMatchEvents,
+                            type: "instant",
+                        }),
+                        client.queryPrometheus({
+                            query: promQueries.pendingEvents,
+                            type: "instant",
+                        }),
+                        client.queryPrometheus({
+                            query: promQueries.runtimeP95Seconds,
+                            type: "instant",
+                        }),
+                        client.queryPrometheus({
+                            query: promQueries.inflightP95Seconds,
+                            type: "instant",
+                        }),
+                    ]);
+                    totalEvents = Math.round(extractPrometheusNumber(totalResponse, 0) ?? 0);
+                    failedEvents = Math.round(extractPrometheusNumber(failedResponse, 0) ?? 0);
+                    noMatchEvents = Math.round(extractPrometheusNumber(noMatchResponse, 0) ?? 0);
+                    pendingEvents = Math.round(extractPrometheusNumber(pendingResponse, 0) ?? 0);
+                    runtimeP95Seconds = extractPrometheusNumber(runtimeP95Response, null);
+                    inflightP95Seconds = extractPrometheusNumber(inflightP95Response, null);
+                }
+                catch {
+                    source = "event_api";
+                    const agg = await aggregateEventsFromApi(client, {
+                        from,
+                        to,
+                        maxPages: parsed.maxPages,
+                        eventType: "ORCHESTRATION",
+                    });
+                    totalEvents = agg.totalEvents;
+                    failedEvents = agg.statusBreakdown["FAILED"] ?? 0;
+                    noMatchEvents = agg.statusBreakdown["NO_MATCH"] ?? 0;
+                    pendingEvents = agg.statusBreakdown["PENDING"] ?? 0;
+                    runtimeP95Seconds = null;
+                    inflightP95Seconds = null;
+                }
+                let topFailingEvents;
+                if (parsed.includeTopFailingEvents) {
+                    try {
+                        const failingAgg = await aggregateEventsFromApi(client, {
+                            from,
+                            to,
+                            maxPages: parsed.maxPages,
+                            eventStatus: "FAILED",
+                            eventType: "ORCHESTRATION",
+                        });
+                        topFailingEvents = rankTopEvents(failingAgg.groups, failingAgg.totalEvents, parsed.topN);
+                    }
+                    catch {
+                        topFailingEvents = [];
+                    }
+                }
+                const failureRate = percentage(failedEvents, totalEvents);
+                const noMatchRate = percentage(noMatchEvents, totalEvents);
+                const pendingRate = percentage(pendingEvents, totalEvents);
+                const findings = [];
+                if (failureRate > thresholds.failureRate) {
+                    findings.push({
+                        severity: "HIGH",
+                        type: "HIGH_FAILURE_RATE",
+                        message: `Failure rate ${failureRate}% exceeds ${thresholds.failureRate}%`,
+                        value: failureRate,
+                        threshold: thresholds.failureRate,
+                    });
+                }
+                if (noMatchRate > thresholds.noMatchRate) {
+                    findings.push({
+                        severity: "CRITICAL",
+                        type: "HIGH_NO_MATCH_RATE",
+                        message: `NO_MATCH rate ${noMatchRate}% exceeds ${thresholds.noMatchRate}%`,
+                        value: noMatchRate,
+                        threshold: thresholds.noMatchRate,
+                    });
+                }
+                if (pendingRate > thresholds.pendingRate) {
+                    findings.push({
+                        severity: "MEDIUM",
+                        type: "HIGH_PENDING_RATE",
+                        message: `Pending rate ${pendingRate}% exceeds ${thresholds.pendingRate}%`,
+                        value: pendingRate,
+                        threshold: thresholds.pendingRate,
+                    });
+                }
+                if (runtimeP95Seconds !== null &&
+                    runtimeP95Seconds > thresholds.runtimeP95Seconds) {
+                    findings.push({
+                        severity: "MEDIUM",
+                        type: "HIGH_RUNTIME_P95",
+                        message: `Runtime p95 ${round3(runtimeP95Seconds)}s exceeds ${thresholds.runtimeP95Seconds}s`,
+                        value: round3(runtimeP95Seconds),
+                        threshold: thresholds.runtimeP95Seconds,
+                    });
+                }
+                if (inflightP95Seconds !== null &&
+                    inflightP95Seconds > thresholds.inflightP95Seconds) {
+                    findings.push({
+                        severity: "MEDIUM",
+                        type: "HIGH_INFLIGHT_P95",
+                        message: `Inflight p95 ${round3(inflightP95Seconds)}s exceeds ${thresholds.inflightP95Seconds}s`,
+                        value: round3(inflightP95Seconds),
+                        threshold: thresholds.inflightP95Seconds,
+                    });
+                }
+                const recommendations = [];
+                if (findings.some((f) => f.type === "HIGH_FAILURE_RATE")) {
+                    recommendations.push("Run metrics.topEvents with eventStatus=FAILED and investigate top failures via /fluent-trace.");
+                }
+                if (findings.some((f) => f.type === "HIGH_NO_MATCH_RATE")) {
+                    recommendations.push("Validate event names against workflow rulesets using /fluent-workflow-analyzer.");
+                }
+                if (findings.some((f) => f.type === "HIGH_PENDING_RATE")) {
+                    recommendations.push("Check orchestration backlog and re-run metrics.sloReport over shorter windows (e.g., 15m).");
+                }
+                if (findings.some((f) => f.type === "HIGH_RUNTIME_P95" || f.type === "HIGH_INFLIGHT_P95")) {
+                    recommendations.push("Use metrics.query to break down latency by event_name/entity_type and isolate slow workflows.");
+                }
+                return json({
+                    ok: true,
+                    source,
+                    healthy: findings.length === 0,
+                    summary: {
+                        window,
+                        timeWindow: { from, to },
+                        totalEvents,
+                        failedEvents,
+                        noMatchEvents,
+                        pendingEvents,
+                        failureRate,
+                        noMatchRate,
+                        pendingRate,
+                        runtimeP95Seconds: runtimeP95Seconds !== null ? round3(runtimeP95Seconds) : null,
+                        inflightP95Seconds: inflightP95Seconds !== null ? round3(inflightP95Seconds) : null,
+                    },
+                    thresholds,
+                    findings,
+                    topFailingEvents: parsed.includeTopFailingEvents
+                        ? topFailingEvents
+                        : undefined,
+                    recommendations: recommendations.length > 0 ? recommendations : undefined,
+                    queries: source === "prometheus"
+                        ? promQueries
+                        : {
+                            eventApiFallback: {
+                                from,
+                                to,
+                                eventType: "ORCHESTRATION",
+                                maxPages: parsed.maxPages,
+                            },
+                        },
+                });
+            }
+            // ------- metrics.labelCatalog --------------------------------------------
+            if (toolName === "metrics.labelCatalog") {
+                const parsed = MetricsLabelCatalogInputSchema.parse(args);
+                const client = requireClient(ctx);
+                parseWindowMs(parsed.window); // validate format early
+                const query = `last_over_time(${parsed.metric}[${parsed.window}])`;
+                const response = await client.queryPrometheus({
+                    query,
+                    type: "instant",
+                });
+                const vectors = extractPrometheusVectors(response);
+                const liveLabelPresence = new Map();
+                const liveLabelValues = new Map();
+                for (const vector of vectors) {
+                    const metric = vector.metric ?? {};
+                    for (const [rawKey, rawValue] of Object.entries(metric)) {
+                        if (rawKey === "__name__")
+                            continue;
+                        liveLabelPresence.set(rawKey, (liveLabelPresence.get(rawKey) ?? 0) + 1);
+                        if (!liveLabelValues.has(rawKey)) {
+                            liveLabelValues.set(rawKey, new Map());
+                        }
+                        const value = String(rawValue);
+                        const valueMap = liveLabelValues.get(rawKey);
+                        valueMap.set(value, (valueMap.get(value) ?? 0) + 1);
+                    }
+                }
+                const knownLabels = parsed.includeKnownLabels
+                    ? KNOWN_METRIC_LABELS[parsed.metric] ?? []
+                    : [];
+                const mergedLabels = new Set([
+                    ...Array.from(liveLabelPresence.keys()),
+                    ...knownLabels,
+                ]);
+                const labels = Array.from(mergedLabels)
+                    .sort((a, b) => a.localeCompare(b))
+                    .map((name) => {
+                    const presenceCount = liveLabelPresence.get(name) ?? 0;
+                    const valuesMap = liveLabelValues.get(name) ?? new Map();
+                    const sampleValues = Array.from(valuesMap.entries())
+                        .sort((a, b) => b[1] - a[1])
+                        .slice(0, parsed.maxValuesPerLabel)
+                        .map(([value]) => value);
+                    const source = knownLabels.includes(name)
+                        ? presenceCount > 0
+                            ? "both"
+                            : "known"
+                        : "live";
+                    return {
+                        name,
+                        source,
+                        presentInSeries: presenceCount,
+                        presenceRate: vectors.length > 0 ? round1((presenceCount / vectors.length) * 100) : 0,
+                        distinctValues: valuesMap.size,
+                        sampleValues,
+                    };
+                });
+                const warnings = [];
+                if (response.status !== "success") {
+                    warnings.push(`Live label sampling failed with status=${response.status}. Returning known-label hints where available.`);
+                }
+                else if (vectors.length === 0) {
+                    warnings.push("No live series returned for the selected metric/window. Label list may be incomplete.");
+                }
+                if (knownLabels.length === 0 && labels.length === 0) {
+                    warnings.push("No labels discovered from live sampling and no known-label mapping exists for this metric.");
+                }
+                return json({
+                    ok: true,
+                    metric: parsed.metric,
+                    window: parsed.window,
+                    query,
+                    liveSampling: {
+                        status: response.status,
+                        seriesSampled: vectors.length,
+                        errorType: response.errorType,
+                        error: response.error,
+                    },
+                    labels,
+                    knownLabelHintsApplied: knownLabels.length > 0,
+                    warnings: warnings.length > 0 ? warnings : undefined,
+                });
+            }
+            // ------- metrics.topEvents -----------------------------------------------
+            if (toolName === "metrics.topEvents") {
+                const parsed = MetricsTopEventsInputSchema.parse(args);
+                const client = requireClient(ctx);
+                const toTime = parsed.to ?? new Date().toISOString();
+                const agg = await aggregateEventsFromApi(client, {
+                    from: parsed.from,
+                    to: toTime,
+                    maxPages: parsed.maxPages,
+                    entityType: parsed.entityType,
+                    eventStatus: parsed.eventStatus,
+                    eventType: parsed.eventType,
+                });
+                const topEvents = rankTopEvents(agg.groups, agg.totalEvents, parsed.topN);
+                const failedCount = agg.statusBreakdown["FAILED"] ?? 0;
+                return json({
+                    ok: true,
+                    analytics: {
+                        timeWindow: { from: parsed.from, to: toTime },
+                        totalEvents: agg.totalEvents,
+                        totalPages: agg.totalPages,
+                        uniqueEventNames: agg.uniqueNames.size,
+                        uniqueEntityTypes: agg.uniqueEntityTypes.size,
+                        failureRate: agg.totalEvents > 0
+                            ? Math.round((failedCount / agg.totalEvents) * 1000) / 10
+                            : 0,
+                        statusBreakdown: agg.statusBreakdown,
+                        topEvents,
+                    },
+                });
+            }
+            // ------- entity.create ------------------------------------------------
+            if (toolName === "entity.create") {
+                const result = await handleEntityCreate(args, ctx);
+                return json(result, false, ctx.responseBudget);
+            }
+            // ------- entity.update ------------------------------------------------
+            if (toolName === "entity.update") {
+                const result = await handleEntityUpdate(args, ctx);
+                return json(result, false, ctx.responseBudget);
+            }
+            // ------- entity.get ---------------------------------------------------
+            if (toolName === "entity.get") {
+                const result = await handleEntityGet(args, ctx);
+                return json(result, false, ctx.responseBudget);
+            }
+            // ------- workflow.upload -----------------------------------------------
+            if (toolName === "workflow.upload") {
+                const result = await handleWorkflowUpload(args, ctx);
+                return json(result, false, ctx.responseBudget);
+            }
+            // ------- workflow.diff -------------------------------------------------
+            if (toolName === "workflow.diff") {
+                const result = await handleWorkflowDiff(args, ctx);
+                return json(result, false, ctx.responseBudget);
+            }
+            // ------- workflow.simulate ----------------------------------------------
+            if (toolName === "workflow.simulate") {
+                const result = await handleWorkflowSimulate(args, ctx);
+                return json(result, false, ctx.responseBudget);
+            }
+            // ------- setting.upsert ------------------------------------------------
+            if (toolName === "setting.upsert") {
+                const result = await handleSettingUpsert(args, ctx);
+                return json(result, false, ctx.responseBudget);
+            }
+            // ------- setting.bulkUpsert --------------------------------------------
+            if (toolName === "setting.bulkUpsert") {
+                const result = await handleSettingBulkUpsert(args, ctx);
+                return json(result, false, ctx.responseBudget);
+            }
+            // ------- environment.discover ------------------------------------------
+            if (toolName === "environment.discover") {
+                const result = await handleEnvironmentDiscover(args, ctx);
+                return json(result, false, ctx.responseBudget);
+            }
+            // ------- environment.validate ------------------------------------------
+            if (toolName === "environment.validate") {
+                const result = await handleEnvironmentValidate(args, ctx);
+                return json(result, false, ctx.responseBudget);
+            }
+            // ------- test.assert ---------------------------------------------------
+            if (toolName === "test.assert") {
+                const result = await handleTestAssert(args, ctx);
+                return json(result, false, ctx.responseBudget);
+            }
+            throw new ToolError("VALIDATION_ERROR", `Unknown tool: ${toolName}`);
+        }
+        catch (error) {
+            if (error instanceof z.ZodError) {
+                return json(toToolFailure(new ToolError("VALIDATION_ERROR", "Invalid tool arguments.", {
+                    details: {
+                        issues: error.issues.map((issue) => ({
+                            path: issue.path.join("."),
+                            message: issue.message,
+                        })),
+                    },
+                })), true);
+            }
+            return json(toToolFailure(error), true);
+        }
+    });
+}