@fluentcommerce/fluent-mcp-extn 0.7.0 → 0.7.3

package/dist/graphql-query-tools.js

@@ -2,12 +2,12 @@
  * GraphQL Query Execution Tools
  *
  * Four query/mutation execution tools:
- *   graphql.query        — execute a single GraphQL query or mutation
- *   graphql.queryAll     — execute with SDK auto-pagination
- *   graphql.batchMutate  — execute multiple mutations in a single aliased request
- *   graphql.introspect   — inspect the schema via introspection service
+ *   graphql_query        — execute a single GraphQL query or mutation
+ *   graphql_queryAll     — execute with SDK auto-pagination
+ *   graphql_batchMutate  — execute multiple mutations in a single aliased request
+ *   graphql_introspect   — inspect the schema via introspection service
  *
- * NOTE: graphql-schema-tools.ts handles graphql.listRoots/buildQuery/validate/generateFull.
+ * NOTE: graphql-schema-tools.ts handles graphql_listRoots/buildQuery/validate/generateFull.
  * This file handles the query execution tools.
  */
 import { z } from "zod";
@@ -58,7 +58,7 @@ export const GraphQLIntrospectInputSchema = z.object({
 // ---------------------------------------------------------------------------
 export const GRAPHQL_QUERY_TOOL_DEFINITIONS = [
     {
-        name: "graphql.query",
+        name: "graphql_query",
         description: "Execute a GraphQL query or mutation. Relay pagination: first/after with cursors on edges.",
         annotations: {
             title: "GraphQL Query",
@@ -69,8 +69,8 @@ export const GRAPHQL_QUERY_TOOL_DEFINITIONS = [
         },
     },
     {
-        name: "graphql.queryAll",
-        description: "Auto-paginated GraphQL query. Follows cursors, merges edges, deduplicates. Use instead of graphql.query when you need all records.",
+        name: "graphql_queryAll",
+        description: "Auto-paginated GraphQL query. Follows cursors, merges edges, deduplicates. Use instead of graphql_query when you need all records.",
         annotations: {
             title: "GraphQL Query All",
             readOnlyHint: true,
@@ -80,7 +80,7 @@ export const GRAPHQL_QUERY_TOOL_DEFINITIONS = [
         },
     },
     {
-        name: "graphql.batchMutate",
+        name: "graphql_batchMutate",
         description: "Execute up to 50 mutations in one aliased request. Provide mutation name, inputs array, and returnFields.",
         annotations: {
             title: "GraphQL Batch Mutate",
@@ -91,7 +91,7 @@ export const GRAPHQL_QUERY_TOOL_DEFINITIONS = [
         },
     },
     {
-        name: "graphql.introspect",
+        name: "graphql_introspect",
         description: "Inspect GraphQL schema. Modes: type, mutation, listMutations, listQueries. Cached 24h, force=true to refresh.",
         annotations: {
             title: "Introspect Schema",
@@ -143,15 +143,43 @@ function introspectCacheKey(input) {
 }
 function requireClient(ctx) {
     if (!ctx.client) {
-        throw new ToolError("CONFIG_ERROR", "SDK client is not available. Run config.validate and fix auth/base URL.");
+        throw new ToolError("CONFIG_ERROR", "SDK client is not available. Run config_validate and fix auth/base URL.");
     }
     return ctx.client;
 }
+function analyzePaginationLimits(pagination, limits) {
+    if (!pagination)
+        return { truncated: false };
+    const totalPages = typeof pagination.totalPages === "number" ? pagination.totalPages : null;
+    const totalRecords = typeof pagination.totalRecords === "number" ? pagination.totalRecords : null;
+    const pagesReached = typeof pagination.pagesFetched === "number"
+        ? pagination.pagesFetched >= limits.maxPages
+        : totalPages !== null
+            ? totalPages >= limits.maxPages
+            : false;
+    const recordsReached = typeof pagination.recordsFetched === "number"
+        ? pagination.recordsFetched >= limits.maxRecords
+        : totalRecords !== null
+            ? totalRecords >= limits.maxRecords
+            : false;
+    if (!pagesReached && !recordsReached) {
+        return { truncated: false };
+    }
+    const reasons = [];
+    if (pagesReached)
+        reasons.push(`page cap ${limits.maxPages}`);
+    if (recordsReached)
+        reasons.push(`record cap ${limits.maxRecords}`);
+    return {
+        truncated: true,
+        warning: `Auto-pagination may be truncated by the ${reasons.join(" and ")}. Narrow the query or raise the limit if you need a complete result.`,
+    };
+}
 // ---------------------------------------------------------------------------
 // Handlers
 // ---------------------------------------------------------------------------
 /**
- * Handle graphql.query tool call.
+ * Handle graphql_query tool call.
  */
 export async function handleGraphQLQuery(args, ctx) {
     const client = requireClient(ctx);
@@ -171,7 +199,7 @@ export async function handleGraphQLQuery(args, ctx) {
     return { ok: true, response: result };
 }
 /**
- * Handle graphql.queryAll tool call.
+ * Handle graphql_queryAll tool call.
  */
 export async function handleGraphQLQueryAll(args, ctx) {
     const client = requireClient(ctx);
@@ -190,16 +218,44 @@ export async function handleGraphQLQueryAll(args, ctx) {
     };
     const result = await client.graphqlPaginated(payload);
     const pagination = result.extensions?.autoPagination ?? null;
+    const paginationInfo = pagination && typeof pagination === "object"
+        ? pagination
+        : null;
+    const paginationAnalysis = analyzePaginationLimits(paginationInfo, {
+        maxPages: parsed.maxPages,
+        maxRecords: parsed.maxRecords,
+    });
     if (parsed.summarize) {
         const summary = summarizeConnection(result);
         if (summary) {
-            return { ok: true, summarized: true, ...summary, pagination };
+            return {
+                ok: true,
+                summarized: true,
+                ...summary,
+                pagination,
+                ...(paginationAnalysis.truncated
+                    ? {
+                        _truncated: true,
+                        _truncationWarning: paginationAnalysis.warning,
+                    }
+                    : {}),
+            };
         }
     }
-    return { ok: true, response: result, pagination };
+    return {
+        ok: true,
+        response: result,
+        pagination,
+        ...(paginationAnalysis.truncated
+            ? {
+                _truncated: true,
+                _truncationWarning: paginationAnalysis.warning,
+            }
+            : {}),
+    };
 }
 /**
- * Handle graphql.batchMutate tool call.
+ * Handle graphql_batchMutate tool call.
  */
 export async function handleGraphQLBatchMutate(args, ctx) {
     const client = requireClient(ctx);
@@ -249,7 +305,7 @@ export async function handleGraphQLBatchMutate(args, ctx) {
     };
 }
 /**
- * Handle graphql.introspect tool call.
+ * Handle graphql_introspect tool call.
  */
 export async function handleGraphQLIntrospect(args, ctx) {
     const client = requireClient(ctx);

package/dist/graphql-schema-tools.js

@@ -2,10 +2,10 @@
  * GraphQL Schema Tools
  *
  * Four schema-aware tools that close the gap with the official MCP server:
- *   graphql.listRoots    — list query & mutation root fields
- *   graphql.buildQuery   — generate a query/mutation string from structured inputs
- *   graphql.validate     — validate a GraphQL document against the live schema
- *   graphql.generateFull — generate a maximal-selection query for a root field
+ *   graphql_listRoots    — list query & mutation root fields
+ *   graphql_buildQuery   — generate a query/mutation string from structured inputs
+ *   graphql_validate     — validate a GraphQL document against the live schema
+ *   graphql_generateFull — generate a maximal-selection query for a root field
  *
  * All tools share a single SchemaService instance (cached, with force-refresh).
  */
@@ -346,7 +346,7 @@ function getSchemaService(ctx) {
 // ---------------------------------------------------------------------------
 export const GRAPHQL_SCHEMA_TOOL_DEFINITIONS = [
     {
-        name: "graphql.listRoots",
+        name: "graphql_listRoots",
         description: "List all query and mutation root fields from the live schema.",
         annotations: {
             title: "List Schema Roots",
@@ -357,7 +357,7 @@ export const GRAPHQL_SCHEMA_TOOL_DEFINITIONS = [
         },
     },
     {
-        name: "graphql.planOperation",
+        name: "graphql_planOperation",
         description: "Inspect a query/mutation root field and return required args, nested input shape, variables template, and a ready-to-run document scaffold. Use when the model is unsure which inputs are mandatory.",
         annotations: {
             title: "Plan GraphQL Operation",
@@ -368,7 +368,7 @@ export const GRAPHQL_SCHEMA_TOOL_DEFINITIONS = [
         },
     },
     {
-        name: "graphql.buildQuery",
+        name: "graphql_buildQuery",
         description: "Generate a GraphQL query/mutation from { rootField, fields, args }. Auto-validates against live schema.",
         annotations: {
             title: "Build GraphQL Query",
@@ -379,7 +379,7 @@ export const GRAPHQL_SCHEMA_TOOL_DEFINITIONS = [
         },
     },
     {
-        name: "graphql.validate",
+        name: "graphql_validate",
         description: "Validate a GraphQL document against the live schema. Returns OK or validation errors.",
         annotations: {
             title: "Validate GraphQL",
@@ -390,7 +390,7 @@ export const GRAPHQL_SCHEMA_TOOL_DEFINITIONS = [
         },
     },
     {
-        name: "graphql.generateFull",
+        name: "graphql_generateFull",
         description: "Generate a maximal-field query for a root field with recursive introspection (depth 1-5, default 2).",
         annotations: {
             title: "Generate Full Query",
@@ -434,7 +434,7 @@ export async function handlePlanOperation(args, ctx) {
     }
     const field = rootType.getFields()[parsed.rootField];
     if (!field) {
-        throw new ToolError("VALIDATION_ERROR", `Root field '${parsed.rootField}' not found. Use graphql.listRoots to discover available fields.`);
+        throw new ToolError("VALIDATION_ERROR", `Root field '${parsed.rootField}' not found. Use graphql_listRoots to discover available fields.`);
     }
     const argPlans = (field.args ?? []).map((arg) => {
         const described = describeInputField(schema, arg.type, arg.name);
@@ -466,8 +466,8 @@ export async function handlePlanOperation(args, ctx) {
         variablesTemplate,
         selectionTemplate: includeSelectionSet ? selectionLines : [],
         recommendedExecutionTool: parsed.kind === "query" && selectionLines.some((line) => line.startsWith("edges {"))
-            ? "graphql.queryAll"
-            : "graphql.query",
+            ? "graphql_queryAll"
+            : "graphql_query",
         document,
     };
 }
@@ -538,7 +538,7 @@ export async function handleGenerateFull(args, ctx) {
     }
     const field = rootType.getFields()[parsed.rootField];
     if (!field) {
-        throw new ToolError("VALIDATION_ERROR", `Root field '${parsed.rootField}' not found. Use graphql.listRoots to discover available fields.`);
+        throw new ToolError("VALIDATION_ERROR", `Root field '${parsed.rootField}' not found. Use graphql_listRoots to discover available fields.`);
     }
     const returnTypeName = unwrapNamed(field.type).name;
     const selection = buildMaxSelection(schema, returnTypeName, parsed.depth);
@@ -548,7 +548,7 @@ export async function handleGenerateFull(args, ctx) {
 }
 /**
  * Force-clear the schema cache for the current client.
- * Exposed for use by graphql.introspect's force param.
+ * Exposed for use by graphql_introspect's force param.
  */
 export function clearSchemaCache(ctx) {
     if (!ctx.client)

package/dist/metrics-tools.js

@@ -1,6 +1,6 @@
 /**
- * Metrics tools: metrics.query, metrics.topEvents, metrics.healthCheck,
- * metrics.sloReport, metrics.labelCatalog, metrics.catalog
+ * Metrics tools: metrics_query, metrics_topEvents, metrics_healthCheck,
+ * metrics_sloReport, metrics_labelCatalog, metrics.catalog
  *
  * Prometheus-backed observability plus Event API fallback for
  * health assessment, SLO reporting, label discovery, and metric planning.
@@ -10,6 +10,7 @@ import { GraphQLIntrospectionService, } from "@fluentcommerce/fc-connect-sdk";
 import { ToolError } from "./errors.js";
 import { classifyMutationOperations, listMutationCatalog, } from "./mutation-taxonomy.js";
 import { parseWindowMs, recommendStep } from "./time-window.js";
+const MAX_METRICS_RANGE_POINTS = 5_000;
 // ---------------------------------------------------------------------------
 // Input schemas
 // ---------------------------------------------------------------------------
@@ -151,52 +152,52 @@ export const MetricsMutationAuditInputSchema = z.object({
 // ---------------------------------------------------------------------------
 export const METRICS_TOOL_DEFINITIONS = [
     {
-        name: "metrics.query",
+        name: "metrics_query",
         description: "Query Prometheus metrics via GraphQL (instant or range). Requires METRICS_VIEW permission.",
         annotations: { title: "Query Metrics", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     },
     {
-        name: "metrics.topEvents",
+        name: "metrics_topEvents",
         description: "Aggregate events by name+entityType+status in a time window. Returns top-N rankings.",
         annotations: { title: "Top Events", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     },
     {
-        name: "metrics.healthCheck",
+        name: "metrics_healthCheck",
         description: "Single-call health assessment via Prometheus. Checks failure rate, NO_MATCH, PENDING, dominance. Falls back to Event API.",
         annotations: { title: "Health Check", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     },
     {
-        name: "metrics.sloReport",
+        name: "metrics_sloReport",
         description: "SLO snapshot: event volume, failure/no-match/pending rates, p95 latency. Prometheus with Event API fallback.",
         annotations: { title: "SLO Report", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     },
     {
-        name: "metrics.labelCatalog",
+        name: "metrics_labelCatalog",
         description: "Discover labels for a Prometheus metric with live sampling and known Fluent hints.",
         annotations: { title: "Label Catalog", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     },
     {
-        name: "metrics.metricCatalog",
+        name: "metrics_metricCatalog",
         description: "List known Fluent metric families with labels, variants, and example PromQL. Can optionally probe live metric names and labels.",
         annotations: { title: "Metric Catalog", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     },
     {
-        name: "metrics.planQuery",
-        description: "Plan PromQL for a metric family: validates labels, picks the right histogram variant, and returns a ready-to-run metrics.query payload.",
+        name: "metrics_planQuery",
+        description: "Plan PromQL for a metric family: validates labels, picks the right histogram variant, and returns a ready-to-run metrics_query payload.",
         annotations: { title: "Plan Metric Query", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     },
     {
-        name: "metrics.snapshot",
+        name: "metrics_snapshot",
         description: "Dashboard snapshot: runs parallel queries to show event volume, failure rates, breakdowns by entity type, avg latency, and p95 in one call. Uses delta pattern for accurate window counts.",
         annotations: { title: "Metrics Snapshot", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     },
     {
-        name: "metrics.compare",
+        name: "metrics_compare",
         description: "Compare a metric across two adjacent time windows (e.g. last 30m vs preceding 30m). Returns current/previous values, absolute delta, and percentage change per group.",
         annotations: { title: "Compare Windows", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     },
     {
-        name: "metrics.mutationAudit",
+        name: "metrics_mutationAudit",
         description: "Audit GraphQL create/update mutation traffic by domain and subdomain. Discovers mutations locally, counts each operation over a fixed window, and aggregates results.",
         annotations: { title: "Mutation Audit", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     },
@@ -204,6 +205,13 @@ export const METRICS_TOOL_DEFINITIONS = [
 // ---------------------------------------------------------------------------
 // Math helpers
 // ---------------------------------------------------------------------------
+function parseIsoTimestamp(value, field) {
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.getTime())) {
+        throw new ToolError("VALIDATION_ERROR", `metrics_query range ${field} must be a valid ISO-8601 timestamp.`);
+    }
+    return parsed;
+}
 function round1(value) {
     return Math.round(value * 10) / 10;
 }
@@ -363,7 +371,7 @@ const KNOWN_METRIC_LABELS = {
         "env_tag",
         "environment",
     ],
-    "graphql.query": [
+    "graphql_query": [
         "account.name",
         "query.type",
         "field.name",
@@ -533,12 +541,12 @@ const KNOWN_METRIC_FAMILIES = {
         ],
         examples: [],
     },
-    "graphql.query": {
-        family: "graphql.query",
+    "graphql_query": {
+        family: "graphql_query",
         category: "graphql_micrometer",
         kind: "timer",
         description: "Micrometer timer for GraphQL field-level execution.",
-        labels: KNOWN_METRIC_LABELS["graphql.query"],
+        labels: KNOWN_METRIC_LABELS["graphql_query"],
         safeGroupBy: ["query.type", "field.name", "account.name"],
         queryable: false,
         notes: [
@@ -970,8 +978,8 @@ function summarizeKnownMetricFamily(family, includeExamples) {
 // parseWindowMs imported from ./time-window.js (single source of truth)
 /**
  * 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.
+ * (name|entityType|status). Shared by metrics_topEvents and the
+ * metrics_healthCheck Event API fallback path.
  */
 async function aggregateEventsFromApi(client, params) {
     const baseParams = {
@@ -1022,6 +1030,7 @@ async function aggregateEventsFromApi(client, params) {
     return {
         totalEvents: allEvents.length,
         totalPages: page - 1,
+        truncated: hasMore,
         statusBreakdown: Object.fromEntries(statusCounts),
         groups,
         uniqueNames: new Set(allEvents.map((e) => e.name)),
@@ -1049,7 +1058,7 @@ function rankTopEvents(groups, totalEvents, topN) {
 // ---------------------------------------------------------------------------
 function requireClient(ctx) {
     if (!ctx.client) {
-        throw new ToolError("CONFIG_ERROR", "SDK client is not available. Run config.validate and fix auth/base URL.");
+        throw new ToolError("CONFIG_ERROR", "SDK client is not available. Run config_validate and fix auth/base URL.");
     }
     return ctx.client;
 }
@@ -1057,13 +1066,35 @@ function requireClient(ctx) {
 // Handlers
 // ---------------------------------------------------------------------------
 /**
- * Handle metrics.query tool call.
+ * Handle metrics_query tool call.
  */
 export async function handleMetricsQuery(args, ctx) {
     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.");
     }
+    if (parsed.type === "range") {
+        const start = parseIsoTimestamp(parsed.start, "start");
+        const end = parseIsoTimestamp(parsed.end, "end");
+        const durationMs = end.getTime() - start.getTime();
+        if (durationMs <= 0) {
+            throw new ToolError("VALIDATION_ERROR", "metrics_query range end must be after start.");
+        }
+        const stepMs = parseWindowMs(parsed.step);
+        const estimatedPoints = Math.ceil(durationMs / stepMs);
+        if (estimatedPoints > MAX_METRICS_RANGE_POINTS) {
+            const hint = recommendStep(durationMs, Math.min(500, MAX_METRICS_RANGE_POINTS));
+            throw new ToolError("VALIDATION_ERROR", `Range query would request about ${estimatedPoints} points, which exceeds the safety limit of ${MAX_METRICS_RANGE_POINTS}. Increase step to at least ${hint.step}.`, {
+                details: {
+                    estimatedPoints,
+                    maxPoints: MAX_METRICS_RANGE_POINTS,
+                    recommendedStep: hint.step,
+                    recommendedStepMs: hint.stepMs,
+                    recommendedEstimatedPoints: hint.estimatedPoints,
+                },
+            });
+        }
+    }
     const client = requireClient(ctx);
     const response = await client.queryPrometheus(parsed);
     const vectors = extractPrometheusVectors(response);
@@ -1081,7 +1112,7 @@ export async function handleMetricsQuery(args, ctx) {
     };
 }
 /**
- * Handle metrics.healthCheck tool call.
+ * Handle metrics_healthCheck tool call.
  */
 export async function handleMetricsHealthCheck(args, ctx) {
     const parsed = MetricsHealthCheckInputSchema.parse(args);
@@ -1092,6 +1123,7 @@ export async function handleMetricsHealthCheck(args, ctx) {
     let statusBreakdown = {};
     let totalEvents = 0;
     let topEvents = [];
+    let eventApiTruncated = false;
     try {
         // Query 1: status breakdown
         const statusResponse = await client.queryPrometheus({
@@ -1154,6 +1186,7 @@ export async function handleMetricsHealthCheck(args, ctx) {
         });
         totalEvents = agg.totalEvents;
         statusBreakdown = agg.statusBreakdown;
+        eventApiTruncated = agg.truncated;
         if (parsed.includeTopEvents) {
             topEvents = rankTopEvents(agg.groups, agg.totalEvents, parsed.topN);
         }
@@ -1212,7 +1245,7 @@ export async function handleMetricsHealthCheck(args, ctx) {
     // 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("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")) {
@@ -1230,6 +1263,10 @@ export async function handleMetricsHealthCheck(args, ctx) {
         ok: true,
         healthy,
         source,
+        ...(eventApiTruncated ? {
+            _truncated: true,
+            _truncationWarning: "Event API results truncated — counts may be approximate. Narrow the time window for accuracy.",
+        } : {}),
         summary: {
             window,
             totalEvents,
@@ -1243,7 +1280,7 @@ export async function handleMetricsHealthCheck(args, ctx) {
     };
 }
 /**
- * Handle metrics.sloReport tool call.
+ * Handle metrics_sloReport tool call.
  */
 export async function handleMetricsSloReport(args, ctx) {
     const parsed = MetricsSloReportInputSchema.parse(args);
@@ -1268,6 +1305,7 @@ export async function handleMetricsSloReport(args, ctx) {
     let pendingEvents = 0;
     let runtimeP95Seconds = null;
     let inflightP95Seconds = null;
+    let eventApiTruncated = false;
     try {
         const [totalResponse, failedResponse, noMatchResponse, pendingResponse, runtimeP95Response, inflightP95Response,] = await Promise.all([
             client.queryPrometheus({
@@ -1316,6 +1354,7 @@ export async function handleMetricsSloReport(args, ctx) {
         pendingEvents = agg.statusBreakdown["PENDING"] ?? 0;
         runtimeP95Seconds = null;
         inflightP95Seconds = null;
+        eventApiTruncated = agg.truncated;
     }
     let topFailingEvents;
     if (parsed.includeTopFailingEvents) {
@@ -1386,21 +1425,25 @@ export async function handleMetricsSloReport(args, ctx) {
     }
     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.");
+        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).");
+        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.");
+        recommendations.push("Use metrics_query to break down latency by event_name/entity_type and isolate slow workflows.");
     }
     return {
         ok: true,
         source,
         healthy: findings.length === 0,
+        ...(eventApiTruncated ? {
+            _truncated: true,
+            _truncationWarning: "Event API results truncated — counts may be approximate. Narrow the time window or increase maxPages for accuracy.",
+        } : {}),
         summary: {
             window,
             timeWindow: { from, to },
@@ -1433,7 +1476,7 @@ export async function handleMetricsSloReport(args, ctx) {
     };
 }
 /**
- * Handle metrics.labelCatalog tool call.
+ * Handle metrics_labelCatalog tool call.
  */
 export async function handleMetricsLabelCatalog(args, ctx) {
     const parsed = MetricsLabelCatalogInputSchema.parse(args);
@@ -1449,7 +1492,7 @@ export async function handleMetricsLabelCatalog(args, ctx) {
     let sampled = null;
     const warnings = [];
     if (!sampling.queryable) {
-        warnings.push("This documented metric is a Micrometer meter name, not a guaranteed Prometheus family. Use metrics.metricCatalog with includeLiveMetrics=true to inspect exported metric names first.");
+        warnings.push("This documented metric is a Micrometer meter name, not a guaranteed Prometheus family. Use metrics_metricCatalog with includeLiveMetrics=true to inspect exported metric names first.");
     }
     else {
         sampled = await sampleMetricLabels(client, sampling.metrics, parsed.window, parsed.maxValuesPerLabel, knownLabels);
@@ -1478,7 +1521,7 @@ export async function handleMetricsLabelCatalog(args, ctx) {
     };
 }
 /**
- * Handle metrics.metricCatalog tool call.
+ * Handle metrics_metricCatalog tool call.
  */
 export async function handleMetricsMetricCatalog(args, ctx) {
     const parsed = MetricsMetricCatalogInputSchema.parse(args);
@@ -1572,7 +1615,7 @@ export async function handleMetricsMetricCatalog(args, ctx) {
     };
 }
 /**
- * Handle metrics.planQuery tool call.
+ * Handle metrics_planQuery tool call.
  */
 export async function handleMetricsPlanQuery(args) {
     const parsed = MetricsPlanQueryInputSchema.parse(args);
@@ -1585,7 +1628,7 @@ export async function handleMetricsPlanQuery(args) {
             metric: parsed.metric,
             warnings: [
                 "Metric is not in the built-in catalog.",
-                "Use metrics.metricCatalog with includeLiveMetrics=true to inspect live metric names before building PromQL.",
+                "Use metrics_metricCatalog with includeLiveMetrics=true to inspect live metric names before building PromQL.",
             ],
         };
     }
@@ -1761,7 +1804,7 @@ export async function handleMetricsPlanQuery(args) {
         query,
         recommendedQueryType: parsed.goal === "delta" || parsed.goal === "recency" || parsed.goal === "raw" ? "instant" : "instant",
         executeWith: {
-            tool: "metrics.query",
+            tool: "metrics_query",
             arguments: {
                 query,
                 type: "instant",
@@ -1772,7 +1815,7 @@ export async function handleMetricsPlanQuery(args) {
             recommendedStep: recommendStep(parseWindowMs(parsed.window)).step,
             estimatedPoints: recommendStep(parseWindowMs(parsed.window)).estimatedPoints,
             executeWith: {
-                tool: "metrics.query",
+                tool: "metrics_query",
                 arguments: {
                     query,
                     type: "range",
@@ -1785,14 +1828,14 @@ export async function handleMetricsPlanQuery(args) {
                 countAudit: {
                     ...countAudit,
                     resetAuditExecuteWith: {
-                        tool: "metrics.query",
+                        tool: "metrics_query",
                         arguments: {
                             query: countAudit.resetAuditQuery,
                             type: "instant",
                         },
                     },
                     comparisonExecuteWith: {
-                        tool: "metrics.query",
+                        tool: "metrics_query",
                         arguments: {
                             query: countAudit.comparisonQuery,
                             type: "instant",
@@ -1819,7 +1862,7 @@ export async function handleMetricsPlanQuery(args) {
     };
 }
 /**
- * Handle metrics.topEvents tool call.
+ * Handle metrics_topEvents tool call.
  */
 export async function handleMetricsTopEvents(args, ctx) {
     const parsed = MetricsTopEventsInputSchema.parse(args);
@@ -1837,6 +1880,10 @@ export async function handleMetricsTopEvents(args, ctx) {
     const failedCount = agg.statusBreakdown["FAILED"] ?? 0;
     return {
         ok: true,
+        ...(agg.truncated ? {
+            _truncated: true,
+            _truncationWarning: `Event API results truncated at ${agg.totalPages} pages (${agg.totalEvents} events fetched). Counts may be approximate. Narrow the time window or increase maxPages for accuracy.`,
+        } : {}),
         analytics: {
             timeWindow: { from: parsed.from, to: toTime },
             totalEvents: agg.totalEvents,
@@ -1852,7 +1899,7 @@ export async function handleMetricsTopEvents(args, ctx) {
     };
 }
 // ---------------------------------------------------------------------------
-// metrics.snapshot — compound dashboard in one call
+// metrics_snapshot — compound dashboard in one call
 // ---------------------------------------------------------------------------
 export async function handleMetricsSnapshot(args, ctx) {
     const parsed = MetricsSnapshotInputSchema.parse(args);
@@ -1981,7 +2028,7 @@ export async function handleMetricsSnapshot(args, ctx) {
     };
 }
 // ---------------------------------------------------------------------------
-// metrics.compare — compare two adjacent time windows
+// metrics_compare — compare two adjacent time windows
 // ---------------------------------------------------------------------------
 export async function handleMetricsCompare(args, ctx) {
     const parsed = MetricsCompareInputSchema.parse(args);
@@ -1993,7 +2040,7 @@ export async function handleMetricsCompare(args, ctx) {
             ok: true,
             valid: false,
             metric: parsed.metric,
-            error: { code: "UNKNOWN_METRIC", message: "Metric not in catalog or not queryable. Use metrics.metricCatalog to discover available metrics." },
+            error: { code: "UNKNOWN_METRIC", message: "Metric not in catalog or not queryable. Use metrics_metricCatalog to discover available metrics." },
         };
     }
     const family = resolved.family;