datadog-mcp 5.5.0 → 5.7.0

package/dist/index.js

@@ -292550,7 +292550,12 @@ var configSchema = external_exports.object({
     // Fallback when AI doesn't specify log limit
     defaultMetricDataPoints: external_exports.number().default(1e3),
     // Fallback for timeseries data points
-    defaultTimeRangeHours: external_exports.number().default(24)
+    defaultTimeRangeHours: external_exports.number().default(24),
+    // Maximum events scanned by the `events.histogram` action before returning a
+    // partial result with `bucketCountIncomplete: true` and `nextCursor`.
+    // Bounds latency on bucketed queries while still giving callers a path to
+    // continue scanning if they want a fully complete histogram.
+    maxEventsForHistogram: external_exports.number().default(5e3)
   }).default({}),
   features: external_exports.object({
     readOnly: external_exports.boolean().default(false),
@@ -292625,7 +292630,8 @@ function loadConfig() {
       defaultLimit: Number.parseInt(process.env.MCP_DEFAULT_LIMIT ?? "50", 10),
       defaultLogLines: Number.parseInt(process.env.MCP_DEFAULT_LOG_LINES ?? "200", 10),
       defaultMetricDataPoints: Number.parseInt(process.env.MCP_DEFAULT_METRIC_POINTS ?? "1000", 10),
-      defaultTimeRangeHours: Number.parseInt(process.env.MCP_DEFAULT_TIME_RANGE ?? "24", 10)
+      defaultTimeRangeHours: Number.parseInt(process.env.MCP_DEFAULT_TIME_RANGE ?? "24", 10),
+      maxEventsForHistogram: Number.parseInt(process.env.MCP_MAX_EVENTS_HISTOGRAM ?? "5000", 10)
     },
     features: {
       readOnly: args.booleans.has("read-only") || process.env.MCP_READ_ONLY === "true",
@@ -302904,6 +302910,182 @@ function formatDurationNs(ns) {
   return `${(ns / 6e10).toFixed(2)}m`;
 }
 
+// src/utils/timezone.ts
+var ERROR_PREFIX = "EINVALID_TIMEZONE";
+var WEEKDAY_TO_INDEX = {
+  Sunday: 0,
+  Monday: 1,
+  Tuesday: 2,
+  Wednesday: 3,
+  Thursday: 4,
+  Friday: 5,
+  Saturday: 6
+};
+function validateIanaZone(tz) {
+  if (typeof tz !== "string" || tz.length === 0) {
+    throw new Error(
+      `${ERROR_PREFIX}: timezone must be a non-empty IANA identifier (e.g. "UTC", "Europe/Paris", "America/New_York")`
+    );
+  }
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: tz });
+    return;
+  } catch {
+    const suggestions = suggestZones(tz);
+    const suggestionText = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}?` : "";
+    throw new Error(`${ERROR_PREFIX}: "${tz}" is not a valid IANA timezone.${suggestionText}`);
+  }
+}
+function suggestZones(input) {
+  let zones;
+  try {
+    zones = Intl.supportedValuesOf("timeZone");
+  } catch {
+    return [];
+  }
+  const lower = input.toLowerCase();
+  const scored = zones.map((zone) => ({
+    zone,
+    score: scoreZone(zone, lower)
+  }));
+  scored.sort((a, b) => a.score - b.score);
+  return scored.slice(0, 3).map((s) => s.zone);
+}
+function scoreZone(zone, lowerInput) {
+  const lowerZone = zone.toLowerCase();
+  const baseDistance = levenshtein(lowerZone, lowerInput);
+  if (lowerZone.includes(lowerInput) || lowerInput.includes(lowerZone)) {
+    return baseDistance - 100;
+  }
+  return baseDistance;
+}
+function levenshtein(a, b) {
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  if (a.length > b.length) {
+    const tmp = a;
+    a = b;
+    b = tmp;
+  }
+  let previous = new Array(a.length + 1);
+  let current = new Array(a.length + 1);
+  for (let i = 0; i <= a.length; i++) previous[i] = i;
+  for (let j = 1; j <= b.length; j++) {
+    current[0] = j;
+    const bChar = b.charCodeAt(j - 1);
+    for (let i = 1; i <= a.length; i++) {
+      const cost = a.charCodeAt(i - 1) === bChar ? 0 : 1;
+      const prevI = previous[i] ?? 0;
+      const currIMinus1 = current[i - 1] ?? 0;
+      const prevIMinus1 = previous[i - 1] ?? 0;
+      current[i] = Math.min(prevI + 1, currIMinus1 + 1, prevIMinus1 + cost);
+    }
+    const tmp = previous;
+    previous = current;
+    current = tmp;
+  }
+  return previous[a.length] ?? 0;
+}
+var partsFormatterCache = /* @__PURE__ */ new Map();
+var offsetFormatterCache = /* @__PURE__ */ new Map();
+function getPartsFormatter(tz) {
+  const cached2 = partsFormatterCache.get(tz);
+  if (cached2) return cached2;
+  const fmt = new Intl.DateTimeFormat("en-US", {
+    timeZone: tz,
+    hourCycle: "h23",
+    // 0-23, avoids "24" edge case at midnight
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    weekday: "long"
+  });
+  partsFormatterCache.set(tz, fmt);
+  return fmt;
+}
+function getOffsetFormatter(tz) {
+  const cached2 = offsetFormatterCache.get(tz);
+  if (cached2) return cached2;
+  const fmt = new Intl.DateTimeFormat("en-US", {
+    timeZone: tz,
+    timeZoneName: "longOffset"
+  });
+  offsetFormatterCache.set(tz, fmt);
+  return fmt;
+}
+function getDateParts(epochMs, tz) {
+  let parts;
+  try {
+    parts = getPartsFormatter(tz).formatToParts(epochMs);
+  } catch {
+    throw new Error(`${ERROR_PREFIX}: "${tz}" is not a valid IANA timezone.`);
+  }
+  const out = {
+    year: "",
+    month: "",
+    day: "",
+    hour: "",
+    minute: "",
+    second: "",
+    weekday: ""
+  };
+  for (const part of parts) {
+    if (part.type === "year") out.year = part.value;
+    else if (part.type === "month") out.month = part.value;
+    else if (part.type === "day") out.day = part.value;
+    else if (part.type === "hour") out.hour = part.value;
+    else if (part.type === "minute") out.minute = part.value;
+    else if (part.type === "second") out.second = part.value;
+    else if (part.type === "weekday") out.weekday = part.value;
+  }
+  return out;
+}
+function getOffsetIso(epochMs, tz) {
+  let parts;
+  try {
+    parts = getOffsetFormatter(tz).formatToParts(epochMs);
+  } catch {
+    throw new Error(`${ERROR_PREFIX}: "${tz}" is not a valid IANA timezone.`);
+  }
+  const offsetPart = parts.find((p) => p.type === "timeZoneName");
+  const raw = offsetPart?.value ?? "";
+  if (raw === "GMT" || raw === "GMT+00:00" || raw === "GMT-00:00") {
+    return "Z";
+  }
+  if (raw.startsWith("GMT")) {
+    return raw.slice(3);
+  }
+  return raw;
+}
+function formatLocal(epochMs, tz) {
+  validateIanaZone(tz);
+  const parts = getDateParts(epochMs, tz);
+  const offset = getOffsetIso(epochMs, tz);
+  return `${parts.year}-${parts.month}-${parts.day}T${parts.hour}:${parts.minute}:${parts.second}${offset}`;
+}
+function bucketHourOfDay(epochMs, tz) {
+  validateIanaZone(tz);
+  const parts = getDateParts(epochMs, tz);
+  return Number(parts.hour);
+}
+function bucketDayOfWeek(epochMs, tz) {
+  validateIanaZone(tz);
+  const parts = getDateParts(epochMs, tz);
+  const index = WEEKDAY_TO_INDEX[parts.weekday];
+  if (index === void 0) {
+    throw new Error(`${ERROR_PREFIX}: could not resolve weekday for "${parts.weekday}" in "${tz}"`);
+  }
+  return index;
+}
+function bucketDayOfMonth(epochMs, tz) {
+  validateIanaZone(tz);
+  const parts = getDateParts(epochMs, tz);
+  return Number(parts.day);
+}
+
 // src/tools/events.ts
 var ActionSchema = external_exports.enum([
   "list",
@@ -302914,8 +303096,10 @@ var ActionSchema = external_exports.enum([
   "top",
   "timeseries",
   "incidents",
-  "discover"
+  "discover",
+  "histogram"
 ]);
+var HistogramBucketBySchema = external_exports.enum(["hour_of_day", "day_of_week", "day_of_month"]);
 var InputSchema = {
   action: ActionSchema.describe("Action to perform"),
   id: external_exports.string().optional().describe("Event ID (for get action)"),
@@ -302945,8 +303129,35 @@ var InputSchema = {
   ),
   maxEvents: external_exports.number().min(1).max(5e3).optional().describe(
     "Maximum events to fetch for grouping in top action (default: 5000, max: 5000). Higher = more accurate but slower"
+  ),
+  // Monitor transition filter (additive — see requirement 5.2 / monitors action=history)
+  transitionType: external_exports.array(
+    external_exports.enum([
+      "alert",
+      "alert recovery",
+      "warning",
+      "warning recovery",
+      "no data",
+      "no data recovery",
+      "renotify"
+    ])
+  ).optional().describe(
+    'Filter events by monitor state transition type. When set, restricts results to events with @monitor.transition.transition_type matching any value. Use ["alert","alert recovery"] to count real fires/recoveries and skip renotifies. Empty array is treated as undefined (no filter). For a fires-only count by monitor ID, prefer monitors action=history.'
+  ),
+  // Histogram action (Requirement 3): bucket events by local hour/day-of-week/day-of-month.
+  bucket_by: HistogramBucketBySchema.optional().describe(
+    "Bucket dimension for histogram action: hour_of_day (0-23), day_of_week (0=Sun..6=Sat), day_of_month (1-31)."
+  ),
+  timezone: external_exports.string().optional().describe(
+    'Optional IANA timezone (e.g. "UTC", "Europe/Paris"). DST-safe. For histogram: controls hour/day bucketing (default: UTC). For search/aggregate/top/incidents read actions: adds sibling *Local ISO 8601 strings (e.g. timestampLocal) next to existing timestamps. Omit for byte-identical legacy shape.'
   )
 };
+function annotateEventTimezone(event, tz) {
+  if (!event.timestamp) return event;
+  const ms = new Date(event.timestamp).getTime();
+  if (!Number.isFinite(ms)) return event;
+  return { ...event, timestampLocal: formatLocal(ms, tz) };
+}
 function extractMonitorInfo(title) {
   const priorityMatch = title.match(/^\[P(\d+)\]\s*/);
   const priority = priorityMatch ? `P${priorityMatch[1]}` : void 0;
@@ -303133,17 +303344,17 @@ async function listEventsV1(api, params, limits) {
     tags: params.tags?.join(","),
     unaggregated: true
   });
-  let events = response.events ?? [];
+  let events2 = response.events ?? [];
   if (params.query) {
     const lowerQuery = params.query.toLowerCase();
-    events = events.filter(
+    events2 = events2.filter(
       (e) => e.title?.toLowerCase().includes(lowerQuery) || e.text?.toLowerCase().includes(lowerQuery)
     );
   }
-  const result = events.slice(0, effectiveLimit).map(formatEventV1);
+  const result = events2.slice(0, effectiveLimit).map(formatEventV1);
   return {
     events: result,
-    total: events.length
+    total: events2.length
   };
 }
 async function getEventV1(api, id) {
@@ -303172,6 +303383,88 @@ async function createEventV1(api, params) {
     }
   };
 }
+var UNINDEXED_ALERT_TAG_PREFIXES = [
+  "monitor_priority",
+  "notification_preset",
+  "monitor_tags",
+  "alert_cycle_key",
+  "monitor_group_key",
+  "notification_method"
+];
+var NARROW_TIME_RANGE_THRESHOLD_MS = 5 * 60 * 1e3;
+function extractTagPrefixes(query, tags) {
+  const prefixes = [];
+  if (query) {
+    const re = /(?:^|\s)([a-zA-Z_][a-zA-Z0-9_]*):[^\s)]+/g;
+    let match;
+    while ((match = re.exec(query)) !== null) {
+      if (match[1]) {
+        prefixes.push(match[1]);
+      }
+    }
+  }
+  if (tags) {
+    for (const tag of tags) {
+      const colonIdx = tag.indexOf(":");
+      if (colonIdx > 0) {
+        prefixes.push(tag.slice(0, colonIdx));
+      }
+    }
+  }
+  return prefixes;
+}
+function countNonSourceTerms(query) {
+  if (!query) return 0;
+  const tokens = query.split(/\s+/).filter((t) => t.length > 0 && t !== "OR" && t !== "AND");
+  let nonSource = 0;
+  for (const token of tokens) {
+    const stripped = token.replace(/[()]/g, "");
+    if (stripped.length === 0) continue;
+    if (stripped.startsWith("source:")) continue;
+    nonSource++;
+  }
+  return nonSource;
+}
+function computeDiagnostics(input) {
+  const diagnostics = [];
+  const query = input.query ?? "";
+  const queryHasSourceAlert = /(^|\s|\()source:alert(\s|\)|$)/.test(query) || // NOSONAR S5852: anchored alternation, bounded input, no nested quantifiers
+  (input.sources?.includes("alert") ?? false) || (input.tags?.includes("source:alert") ?? false);
+  if (queryHasSourceAlert) {
+    const prefixes = extractTagPrefixes(input.query, input.tags);
+    const unindexedHits = prefixes.filter((p) => UNINDEXED_ALERT_TAG_PREFIXES.includes(p));
+    const uniqueHits = Array.from(new Set(unindexedHits));
+    if (uniqueHits.length > 0) {
+      diagnostics.push({
+        code: "UNINDEXED_TAG_PREFIX",
+        message: `Query filters on tag prefix(es) that Datadog does not index for source:alert events: ${uniqueHits.join(", ")}.`,
+        hint: "Drop these filters and post-filter the results client-side, or aggregate via monitors/get + monitors.list with matching options."
+      });
+    }
+  }
+  if (typeof input.fromMs === "number" && typeof input.toMs === "number" && input.toMs > input.fromMs && input.toMs - input.fromMs < NARROW_TIME_RANGE_THRESHOLD_MS) {
+    diagnostics.push({
+      code: "NARROW_TIME_RANGE",
+      message: "Time range is shorter than 5 minutes; alert events may not have been indexed yet.",
+      hint: "Widen the range (e.g. last 1h) or retry after the indexing delay (~30s) has elapsed."
+    });
+  }
+  if (queryHasSourceAlert) {
+    const otherTerms = countNonSourceTerms(input.query);
+    const otherTags = (input.tags ?? []).filter((t) => !t.startsWith("source:")).length;
+    if (otherTerms === 0 && otherTags === 0) {
+      diagnostics.push({
+        code: "RESTRICTIVE_SOURCE_FILTER",
+        message: "Only source:alert filter was applied; the matching event set may genuinely be empty.",
+        hint: "Use events.aggregate or monitors.list to confirm no alerts fired in the window, or broaden sources (e.g. source:monitor, source:audit)."
+      });
+    }
+  }
+  return diagnostics;
+}
+function quoteIfNeeded(value) {
+  return /^[A-Za-z0-9_.-]+$/.test(value) ? value : `"${value}"`;
+}
 function buildEventQuery(params) {
   const parts = [];
   if (params.query) {
@@ -303189,9 +303482,16 @@ function buildEventQuery(params) {
   if (params.priority) {
     parts.push(`priority:${params.priority}`);
   }
+  if (params.transitionType && params.transitionType.length > 0) {
+    const inner = params.transitionType.map(quoteIfNeeded).join(" OR ");
+    parts.push(`@monitor.transition.transition_type:(${inner})`);
+  }
   return parts.length > 0 ? parts.join(" ") : "*";
 }
 async function searchEventsV2(api, params, limits, site) {
+  if (params.timezone !== void 0) {
+    validateIanaZone(params.timezone);
+  }
   const defaultFrom = hoursAgo(limits.defaultTimeRangeHours);
   const defaultTo = now();
   const [validFrom, validTo] = ensureValidTimeRange(
@@ -303204,7 +303504,8 @@ async function searchEventsV2(api, params, limits, site) {
     query: params.query,
     sources: params.sources,
     tags: params.tags,
-    priority: params.priority
+    priority: params.priority,
+    transitionType: params.transitionType
   });
   const effectiveLimit = params.limit ?? limits.defaultLimit;
   const body = {
@@ -303220,12 +303521,13 @@ async function searchEventsV2(api, params, limits, site) {
     }
   };
   const response = await api.searchEvents({ body });
-  const events = (response.data ?? []).map(formatEventV2);
+  const rawEvents = (response.data ?? []).map(formatEventV2);
+  const events2 = params.timezone !== void 0 ? rawEvents.map((e) => annotateEventTimezone(e, params.timezone)) : rawEvents;
   const nextCursor = response.meta?.page?.after;
-  return {
-    events,
+  const baseResult = {
+    events: events2,
     meta: {
-      count: events.length,
+      count: events2.length,
       query: fullQuery,
       from: fromTime,
       to: toTime,
@@ -303233,8 +303535,131 @@ async function searchEventsV2(api, params, limits, site) {
       datadog_url: buildEventsUrl(fullQuery, validFrom, validTo, site)
     }
   };
+  if (events2.length === 0) {
+    const diagnostics = computeDiagnostics({
+      query: params.query,
+      tags: params.tags,
+      sources: params.sources,
+      fromMs: validFrom * 1e3,
+      toMs: validTo * 1e3
+    });
+    return { ...baseResult, diagnostics };
+  }
+  return baseResult;
+}
+function bucketEvent(epochMs, bucketBy, tz) {
+  switch (bucketBy) {
+    case "hour_of_day":
+      return bucketHourOfDay(epochMs, tz);
+    case "day_of_week":
+      return bucketDayOfWeek(epochMs, tz);
+    case "day_of_month":
+      return bucketDayOfMonth(epochMs, tz);
+    default: {
+      const exhaustive = bucketBy;
+      throw new Error(`Unhandled bucket_by: ${String(exhaustive)}`);
+    }
+  }
+}
+function eventEpochMs(event) {
+  const ts = event.attributes?.timestamp;
+  if (ts === void 0 || ts === null) return null;
+  if (ts instanceof Date) {
+    const ms2 = ts.getTime();
+    return Number.isFinite(ms2) ? ms2 : null;
+  }
+  const ms = new Date(String(ts)).getTime();
+  return Number.isFinite(ms) ? ms : null;
+}
+async function histogramEventsV2(api, params, limits, site) {
+  const timezone = params.timezone ?? "UTC";
+  validateIanaZone(timezone);
+  const defaultFrom = hoursAgo(limits.defaultTimeRangeHours);
+  const defaultTo = now();
+  const [validFrom, validTo] = ensureValidTimeRange(
+    parseTime(params.from, defaultFrom),
+    parseTime(params.to, defaultTo)
+  );
+  const fromTime = new Date(validFrom * 1e3).toISOString();
+  const toTime = new Date(validTo * 1e3).toISOString();
+  const fullQuery = buildEventQuery({
+    query: params.query,
+    sources: params.sources,
+    tags: params.tags
+  });
+  const cap = limits.maxEventsForHistogram;
+  const perPage = Math.max(1, Math.min(1e3, cap));
+  const buckets = {};
+  let totalEvents = 0;
+  let cursor = params.cursor;
+  let bucketCountIncomplete = false;
+  let exhaustedPages = false;
+  const maxPages = 100;
+  let pageCount = 0;
+  while (pageCount < maxPages) {
+    const body = {
+      filter: {
+        query: fullQuery,
+        from: fromTime,
+        to: toTime
+      },
+      sort: "timestamp",
+      page: {
+        limit: perPage,
+        cursor
+      }
+    };
+    const response = await api.searchEvents({ body });
+    const data = response.data ?? [];
+    const responseCursor = response.meta?.page?.after ?? void 0;
+    for (const event of data) {
+      const epochMs = eventEpochMs(event);
+      if (epochMs === null) continue;
+      const bucket = bucketEvent(epochMs, params.bucket_by, timezone);
+      const key = String(bucket);
+      buckets[key] = (buckets[key] ?? 0) + 1;
+      totalEvents++;
+      if (totalEvents >= cap) {
+        bucketCountIncomplete = true;
+        cursor = responseCursor;
+        break;
+      }
+    }
+    if (bucketCountIncomplete) break;
+    if (data.length === 0 || !responseCursor) {
+      exhaustedPages = true;
+      break;
+    }
+    cursor = responseCursor;
+    pageCount++;
+  }
+  const result = {
+    buckets,
+    bucketBy: params.bucket_by,
+    timezone,
+    totalEvents,
+    meta: {
+      query: fullQuery,
+      from: fromTime,
+      to: toTime,
+      datadog_url: buildEventsUrl(fullQuery, validFrom, validTo, site)
+    }
+  };
+  if (bucketCountIncomplete) {
+    result.bucketCountIncomplete = true;
+    if (cursor) {
+      result.nextCursor = cursor;
+    }
+  } else if (!exhaustedPages && pageCount >= maxPages && cursor) {
+    result.bucketCountIncomplete = true;
+    result.nextCursor = cursor;
+  }
+  return result;
 }
 async function aggregateEventsV2(api, params, limits, site) {
+  if (params.timezone !== void 0) {
+    validateIanaZone(params.timezone);
+  }
   const counts = /* @__PURE__ */ new Map();
   const defaultFrom = hoursAgo(limits.defaultTimeRangeHours);
   const defaultTo = now();
@@ -303247,7 +303672,8 @@ async function aggregateEventsV2(api, params, limits, site) {
   const fullQuery = buildEventQuery({
     query: params.query,
     sources: params.sources,
-    tags: params.tags
+    tags: params.tags,
+    transitionType: params.transitionType
   });
   const groupByFields = params.groupBy ?? ["monitor_name"];
   const maxEventsToAggregate = 1e4;
@@ -303270,9 +303696,9 @@ async function aggregateEventsV2(api, params, limits, site) {
   while (pageCount < maxPages && eventCount < maxEventsToAggregate) {
     const pageBody = { ...body, page: { ...body.page, cursor } };
     const response = await api.searchEvents({ body: pageBody });
-    const events = response.data ?? [];
-    if (events.length === 0) break;
-    for (const event of events) {
+    const events2 = response.data ?? [];
+    if (events2.length === 0) break;
+    for (const event of events2) {
       const formatted = formatEventV2(event);
       const groupKey = buildGroupKey(formatted, groupByFields);
       const existing = counts.get(groupKey);
@@ -303293,7 +303719,8 @@ async function aggregateEventsV2(api, params, limits, site) {
   const buckets = sorted.map(([key, data]) => ({
     key,
     count: data.count,
-    sample: data.sample
+    // Requirement 4: annotate sample timestamps only when timezone is supplied.
+    sample: params.timezone !== void 0 ? annotateEventTimezone(data.sample, params.timezone) : data.sample
   }));
   return {
     buckets,
@@ -303310,6 +303737,9 @@ async function aggregateEventsV2(api, params, limits, site) {
   };
 }
 async function topEventsV2(api, params, limits, site) {
+  if (params.timezone !== void 0) {
+    validateIanaZone(params.timezone);
+  }
   if (params.contextTags !== void 0) {
     if (!Array.isArray(params.contextTags)) {
       throw new Error("contextTags must be an array");
@@ -303329,7 +303759,8 @@ async function topEventsV2(api, params, limits, site) {
       to: params.to,
       sources: params.sources,
       tags: effectiveTags,
-      limit: params.maxEvents ?? 5e3
+      limit: params.maxEvents ?? 5e3,
+      transitionType: params.transitionType
     },
     limits,
     site
@@ -303346,7 +303777,7 @@ async function topEventsV2(api, params, limits, site) {
         value = event.monitorInfo?.name ?? event.title;
       } else {
         const tag = event.tags.find((t) => t.startsWith(`${field}:`));
-        value = tag ? tag.split(":", 2)[1] : "unknown";
+        value = tag ? tag.split(":", 2)[1] ?? "unknown" : "unknown";
       }
       groupValues[field] = value;
       keyParts.push(`${field}:${value}`);
@@ -303407,6 +303838,9 @@ function parseIntervalToMs(interval) {
   return ns ? Math.floor(ns / 1e6) : 36e5;
 }
 async function timeseriesEventsV2(api, params, limits, site) {
+  if (params.timezone !== void 0) {
+    validateIanaZone(params.timezone);
+  }
   const defaultFrom = hoursAgo(limits.defaultTimeRangeHours);
   const defaultTo = now();
   const [validFrom, validTo] = ensureValidTimeRange(
@@ -303418,7 +303852,8 @@ async function timeseriesEventsV2(api, params, limits, site) {
   const fullQuery = buildEventQuery({
     query: params.query ?? "source:alert",
     sources: params.sources,
-    tags: params.tags
+    tags: params.tags,
+    transitionType: params.transitionType
   });
   const intervalMs = parseIntervalToMs(params.interval);
   const groupByFields = params.groupBy ?? ["monitor_name"];
@@ -303440,9 +303875,9 @@ async function timeseriesEventsV2(api, params, limits, site) {
   while (pageCount < maxPages && eventCount < maxEventsToProcess) {
     const pageBody = { ...body, page: { ...body.page, cursor } };
     const response = await api.searchEvents({ body: pageBody });
-    const events = response.data ?? [];
-    if (events.length === 0) break;
-    for (const event of events) {
+    const events2 = response.data ?? [];
+    if (events2.length === 0) break;
+    for (const event of events2) {
       const formatted = formatEventV2(event);
       const groupKey = buildGroupKey(formatted, groupByFields);
       const eventTs = new Date(formatted.timestamp).getTime();
@@ -303459,6 +303894,7 @@ async function timeseriesEventsV2(api, params, limits, site) {
     if (!cursor) break;
     pageCount++;
   }
+  const tz = params.timezone;
   const sortedBuckets = [...timeBuckets.entries()].sort((a, b) => a[0] - b[0]).map(([bucketTs, groupCounts]) => {
     const counts = {};
     let total = 0;
@@ -303466,12 +303902,16 @@ async function timeseriesEventsV2(api, params, limits, site) {
       counts[key] = count;
       total += count;
     }
-    return {
+    const bucket = {
       timestamp: new Date(bucketTs).toISOString(),
       timestampMs: bucketTs,
       counts,
       total
     };
+    if (tz !== void 0) {
+      bucket.timestampLocal = formatLocal(bucketTs, tz);
+    }
+    return bucket;
   });
   const effectiveLimit = params.limit ?? 100;
   const limitedBuckets = sortedBuckets.slice(0, effectiveLimit);
@@ -303492,6 +303932,9 @@ async function timeseriesEventsV2(api, params, limits, site) {
   };
 }
 async function incidentsEventsV2(api, params, limits, site) {
+  if (params.timezone !== void 0) {
+    validateIanaZone(params.timezone);
+  }
   const defaultFrom = hoursAgo(limits.defaultTimeRangeHours);
   const defaultTo = now();
   const [validFrom, validTo] = ensureValidTimeRange(
@@ -303503,7 +303946,8 @@ async function incidentsEventsV2(api, params, limits, site) {
   const fullQuery = buildEventQuery({
     query: params.query ?? "source:alert",
     sources: params.sources,
-    tags: params.tags
+    tags: params.tags,
+    transitionType: params.transitionType
   });
   const dedupeWindowNs = parseDurationToNs(params.dedupeWindow ?? "5m");
   const dedupeWindowMs = dedupeWindowNs ? Math.floor(dedupeWindowNs / 1e6) : 3e5;
@@ -303525,9 +303969,9 @@ async function incidentsEventsV2(api, params, limits, site) {
   while (pageCount < maxPages && eventCount < maxEventsToProcess) {
     const pageBody = { ...body, page: { ...body.page, cursor } };
     const response = await api.searchEvents({ body: pageBody });
-    const events = response.data ?? [];
-    if (events.length === 0) break;
-    for (const event of events) {
+    const events2 = response.data ?? [];
+    if (events2.length === 0) break;
+    for (const event of events2) {
       const formatted = formatEventV2(event);
       const monitorName = formatted.monitorInfo?.name ?? formatted.title;
       if (!monitorName) {
@@ -303595,6 +304039,7 @@ async function incidentsEventsV2(api, params, limits, site) {
     if (!cursor) break;
     pageCount++;
   }
+  const tz = params.timezone;
   const incidentList = [...incidents.values()].map((inc) => {
     let duration3;
     if (inc.recoveredAt) {
@@ -303607,7 +304052,7 @@ async function incidentsEventsV2(api, params, limits, site) {
         duration3 = `${(durationMs / 36e5).toFixed(1)}h`;
       }
     }
-    return {
+    const base = {
       monitorName: inc.monitorName,
       firstTrigger: inc.firstTrigger.toISOString(),
       lastTrigger: inc.lastTrigger.toISOString(),
@@ -303615,8 +304060,17 @@ async function incidentsEventsV2(api, params, limits, site) {
       recovered: inc.recovered,
       recoveredAt: inc.recoveredAt?.toISOString(),
       duration: duration3,
-      sample: inc.sample
+      // Requirement 4: annotate the nested sample event timestamp when tz is supplied.
+      sample: tz !== void 0 ? annotateEventTimezone(inc.sample, tz) : inc.sample
     };
+    if (tz !== void 0) {
+      base.firstTriggerLocal = formatLocal(inc.firstTrigger.getTime(), tz);
+      base.lastTriggerLocal = formatLocal(inc.lastTrigger.getTime(), tz);
+      if (inc.recoveredAt) {
+        base.recoveredAtLocal = formatLocal(inc.recoveredAt.getTime(), tz);
+      }
+    }
+    return base;
   });
   incidentList.sort(
     (a, b) => new Date(b.firstTrigger).getTime() - new Date(a.firstTrigger).getTime()
@@ -303639,15 +304093,15 @@ async function incidentsEventsV2(api, params, limits, site) {
     }
   };
 }
-async function enrichWithMonitorMetadata(events, monitorsApi) {
+async function enrichWithMonitorMetadata(events2, monitorsApi) {
   const monitorIds = /* @__PURE__ */ new Set();
-  for (const event of events) {
+  for (const event of events2) {
     if (event.monitorId) {
       monitorIds.add(event.monitorId);
     }
   }
   if (monitorIds.size === 0) {
-    return events;
+    return events2;
   }
   const monitorCache = /* @__PURE__ */ new Map();
   try {
@@ -303661,9 +304115,9 @@ async function enrichWithMonitorMetadata(events, monitorsApi) {
       }
     }
   } catch {
-    return events;
+    return events2;
   }
-  return events.map((event) => {
+  return events2.map((event) => {
     const enriched = { ...event };
     if (event.monitorId) {
       const monitor = monitorCache.get(event.monitorId);
@@ -303688,18 +304142,26 @@ async function enrichWithMonitorMetadata(events, monitorsApi) {
 function registerEventsTool(server, apiV1, apiV2, monitorsApi, limits, readOnly = false, site = "datadoghq.com") {
   server.tool(
     "events",
-    `Track Datadog events. Actions: list, get, create, search, aggregate, top, timeseries, incidents, discover.
+    `Track Datadog events. Actions: list, get, create, search, aggregate, top, timeseries, incidents, discover, histogram.
 For monitor alerts, use tags: ["source:alert"].
 
+IMPORTANT \u2014 re-evaluation vs transition:
+  - source:alert events INCLUDE renotifies and re-evaluations (every Datadog re-evaluation of an alerting monitor emits an event). A "how many times did monitor X fire" question answered with source:alert alone over-counts.
+  - To restrict to real state transitions, pass transitionType (e.g. ["alert","alert recovery"]). This appends @monitor.transition.transition_type:(...) to the query and matches the design's live investigation.
+  - For a fires-only numeric count rooted in a single monitor ID, prefer the higher-level primitive monitors action=history \u2014 it returns {transitions, count, meta} with the same filter applied for you.
+
+transitionType: Optional array of monitor transition types (alert, alert recovery, warning, warning recovery, no data, no data recovery, renotify). Empty array is treated as undefined.
 top: Generic event grouping by any fields (groupBy parameter). Returns groups ranked by count with optional context breakdown.
   - Example: {groupBy: ["service"], message: "...", service: "api", total_count: 50, by_context: [{context: "queue:X", count: 30}]}
   - Use for deployments, configs, custom events, or monitor alerts
   - Returns "message" field (event title), NOT monitor name (use monitors tool for real names)
+  - total_count includes renotifies when source:alert is used without transitionType \u2014 see monitors action=history for fires-only counts
 discover: Returns available tag prefixes from events.
 aggregate: Custom groupBy, returns pipe-delimited keys.
 search: Full event details.
 timeseries: Time-bucketed trends with interval.
-incidents: Deduplicate alerts with dedupeWindow.`,
+incidents: Deduplicate alerts with dedupeWindow.
+histogram: Bucket events by local hour_of_day / day_of_week / day_of_month in the requested IANA timezone (DST-safe). Pass bucket_by (required) and optional timezone (default UTC) and cursor (for continuation). Caps at limits.maxEventsForHistogram (default 5000); when reached returns bucketCountIncomplete:true + nextCursor.`,
     InputSchema,
     async ({
       action,
@@ -303720,7 +304182,10 @@ incidents: Deduplicate alerts with dedupeWindow.`,
       dedupeWindow,
       enrich,
       contextTags,
-      maxEvents
+      maxEvents,
+      transitionType,
+      bucket_by,
+      timezone
     }) => {
       try {
         checkReadOnly(action, readOnly);
@@ -303769,7 +304234,9 @@ incidents: Deduplicate alerts with dedupeWindow.`,
                 tags,
                 priority,
                 limit,
-                cursor
+                cursor,
+                transitionType,
+                timezone
               },
               limits,
               site
@@ -303791,7 +304258,9 @@ incidents: Deduplicate alerts with dedupeWindow.`,
                   sources,
                   tags,
                   groupBy,
-                  limit
+                  limit,
+                  transitionType,
+                  timezone
                 },
                 limits,
                 site
@@ -303810,7 +304279,9 @@ incidents: Deduplicate alerts with dedupeWindow.`,
                   limit,
                   groupBy,
                   contextTags,
-                  maxEvents
+                  maxEvents,
+                  transitionType,
+                  timezone
                 },
                 limits,
                 site
@@ -303843,7 +304314,9 @@ incidents: Deduplicate alerts with dedupeWindow.`,
                   tags,
                   groupBy,
                   interval,
-                  limit
+                  limit,
+                  transitionType,
+                  timezone
                 },
                 limits,
                 site
@@ -303860,12 +304333,34 @@ incidents: Deduplicate alerts with dedupeWindow.`,
                   sources,
                   tags,
                   dedupeWindow,
-                  limit
+                  limit,
+                  transitionType,
+                  timezone
                 },
                 limits,
                 site
               )
             );
+          case "histogram": {
+            const histogramBucketBy = requireParam(bucket_by, "bucket_by", "histogram");
+            return toolResult(
+              await histogramEventsV2(
+                apiV2,
+                {
+                  query,
+                  from,
+                  to,
+                  sources,
+                  tags,
+                  bucket_by: histogramBucketBy,
+                  timezone,
+                  cursor
+                },
+                limits,
+                site
+              )
+            );
+          }
           default:
             throw new Error(`Unknown action: ${action}`);
         }
@@ -303876,6 +304371,177 @@ incidents: Deduplicate alerts with dedupeWindow.`,
   );
 }
 
+// src/utils/templatePreview.ts
+var SUPPORTED_CONDITIONALS = [
+  "is_alert",
+  "is_warning",
+  "is_no_data",
+  "is_recovery",
+  "is_alert_to_warning",
+  "is_warning_to_alert"
+];
+var SUPPORTED_SET = new Set(SUPPORTED_CONDITIONALS);
+function unsupportedSyntaxError(detail) {
+  const supportedList = SUPPORTED_CONDITIONALS.join(", ");
+  return new Error(
+    `EUNSUPPORTED_TEMPLATE_SYNTAX: ${detail}. Supported syntax is {{variable.name}} and conditionals {{#name}}...{{/name}} / {{^name}}...{{/name}} where name is one of: ${supportedList}. Loops ({{#each ...}}) and partials ({{> ...}}) are not supported.`
+  );
+}
+function lookupVariable(path, variables) {
+  if (Object.prototype.hasOwnProperty.call(variables, path)) {
+    const value = variables[path];
+    return value === void 0 || value === null ? void 0 : String(value);
+  }
+  const segments = path.split(".");
+  let cursor = variables;
+  for (const segment of segments) {
+    if (cursor === null || cursor === void 0) {
+      return void 0;
+    }
+    if (typeof cursor !== "object") {
+      return void 0;
+    }
+    const record2 = cursor;
+    if (!Object.prototype.hasOwnProperty.call(record2, segment)) {
+      return void 0;
+    }
+    cursor = record2[segment];
+  }
+  if (cursor === void 0 || cursor === null) {
+    return void 0;
+  }
+  if (typeof cursor === "object") {
+    return void 0;
+  }
+  return String(cursor);
+}
+var TAG_REGEX = /\{\{\s*([#^/>])?\s*([^}]*?)\s*\}\}/g;
+function parseBlocks(template) {
+  const stack = [{ children: [] }];
+  let cursor = 0;
+  TAG_REGEX.lastIndex = 0;
+  let match;
+  while ((match = TAG_REGEX.exec(template)) !== null) {
+    const [fullTag, prefix, rawName] = match;
+    const tagStart = match.index;
+    const name = rawName?.trim() ?? "";
+    if (tagStart > cursor) {
+      const top = stack[stack.length - 1];
+      if (top) {
+        top.children.push({ kind: "literal", text: template.slice(cursor, tagStart) });
+      }
+    }
+    if (prefix === ">") {
+      throw unsupportedSyntaxError(`partials are not supported (found {{> ${name}}})`);
+    }
+    if (prefix === "#" || prefix === "^") {
+      if (name.startsWith("each") || /\s/.test(name)) {
+        throw unsupportedSyntaxError(`loops are not supported (found {{${prefix}${name}}})`);
+      }
+      if (!SUPPORTED_SET.has(name)) {
+        throw unsupportedSyntaxError(`unknown conditional '${name}' in {{${prefix}${name}}}`);
+      }
+      stack.push({
+        children: [],
+        closer: { conditional: name, negated: prefix === "^" }
+      });
+    } else if (prefix === "/") {
+      const frame = stack.pop();
+      if (!frame || !frame.closer) {
+        throw unsupportedSyntaxError(`unmatched closing tag {{/${name}}}`);
+      }
+      if (frame.closer.conditional !== name) {
+        throw unsupportedSyntaxError(
+          `mismatched closing tag {{/${name}}} (expected {{/${frame.closer.conditional}}})`
+        );
+      }
+      const parent = stack[stack.length - 1];
+      if (!parent) {
+        throw unsupportedSyntaxError("block stack underflow while closing tag");
+      }
+      parent.children.push({
+        kind: "block",
+        conditional: frame.closer.conditional,
+        negated: frame.closer.negated,
+        children: frame.children
+      });
+    } else {
+      const top = stack[stack.length - 1];
+      if (top) {
+        top.children.push({ kind: "literal", text: fullTag });
+      }
+    }
+    cursor = tagStart + fullTag.length;
+  }
+  if (cursor < template.length) {
+    const top = stack[stack.length - 1];
+    if (top) {
+      top.children.push({ kind: "literal", text: template.slice(cursor) });
+    }
+  }
+  if (stack.length !== 1) {
+    const open = stack[stack.length - 1]?.closer?.conditional;
+    throw unsupportedSyntaxError(`unclosed conditional block ${open ? `{{#${open}}}` : ""}`);
+  }
+  const root = stack[0];
+  if (!root) {
+    throw unsupportedSyntaxError("parser produced no root frame");
+  }
+  return root.children;
+}
+function renderBlocks(tokens, conditionals, resolved) {
+  let out = "";
+  for (const token of tokens) {
+    if (token.kind === "literal") {
+      out += token.text;
+      continue;
+    }
+    const flag = conditionals[token.conditional] ?? false;
+    resolved[token.conditional] = flag;
+    const include = token.negated ? !flag : flag;
+    if (include) {
+      out += renderBlocks(token.children, conditionals, resolved);
+    } else {
+      renderBlocks(token.children, conditionals, resolved);
+    }
+  }
+  return out;
+}
+var VARIABLE_TAG_REGEX = /\{\{\s*([^#^/>\s][^}]*?)\s*\}\}/g;
+function substituteVariables(text, variables) {
+  const usedSet = /* @__PURE__ */ new Set();
+  const missingSet = /* @__PURE__ */ new Set();
+  const rendered = text.replace(VARIABLE_TAG_REGEX, (_match, captured) => {
+    const name = captured.trim();
+    const value = lookupVariable(name, variables);
+    if (value === void 0) {
+      missingSet.add(name);
+      return `{{undefined:${name}}}`;
+    }
+    usedSet.add(name);
+    return value;
+  });
+  return {
+    rendered,
+    used: [...usedSet],
+    missing: [...missingSet]
+  };
+}
+function renderMonitorTemplate(template, context) {
+  const variables = context.variables ?? {};
+  const conditionals = context.conditionals ?? {};
+  const tree = parseBlocks(template);
+  const conditionalsResolved = {};
+  const afterConditionals = renderBlocks(tree, conditionals, conditionalsResolved);
+  const { rendered, used, missing } = substituteVariables(afterConditionals, variables);
+  return {
+    rendered,
+    variablesUsed: used,
+    variablesMissing: missing,
+    conditionalsResolved
+  };
+}
+
 // src/tools/monitors.ts
 var ActionSchema2 = external_exports.enum([
   "list",
@@ -303886,8 +304552,15 @@ var ActionSchema2 = external_exports.enum([
   "delete",
   "mute",
   "unmute",
-  "top"
+  "top",
+  "history",
+  "preview",
+  "test_notification"
 ]);
+var PreviewContextSchema = external_exports.object({
+  variables: external_exports.record(external_exports.unknown()).optional(),
+  conditionals: external_exports.record(external_exports.enum(SUPPORTED_CONDITIONALS), external_exports.boolean()).optional()
+}).optional().describe("Substitution context for monitors.preview (variables + conditionals).");
 var InputSchema2 = {
   action: ActionSchema2.describe("Action to perform"),
   id: external_exports.string().optional().describe("Monitor ID (required for get/update/delete/mute/unmute)"),
@@ -303899,15 +304572,44 @@ var InputSchema2 = {
   ),
   limit: external_exports.number().min(1).optional().describe("Maximum number of monitors to return (default: 50)"),
   config: external_exports.record(external_exports.unknown()).optional().describe("Monitor configuration (for create/update)"),
-  message: external_exports.string().optional().describe("Mute message (for mute action)"),
+  message: external_exports.string().optional().describe(
+    "Mute message (for mute action) OR inline template source for the preview action. For preview, supply either this inline string or `monitor_id` (or the existing `id` field) so the action can load the monitor message via getMonitor."
+  ),
   end: external_exports.number().optional().describe("Mute end timestamp (for mute action)"),
+  monitor_id: external_exports.number().optional().describe(
+    "Numeric monitor ID used by the preview action when no inline `message` is supplied. Equivalent to passing the existing `id` field as a numeric string."
+  ),
+  context: PreviewContextSchema,
   // Top action parameters
   from: external_exports.string().optional().describe('Start time (ISO 8601, relative like "1h", or Unix timestamp)'),
   to: external_exports.string().optional().describe('End time (ISO 8601, relative like "1h", or Unix timestamp)'),
   contextTags: external_exports.array(external_exports.string()).optional().describe(
     "Tag prefixes for context breakdown in top action (default: queue, service, ingress, pod_name, kube_namespace, kube_container_name)"
   ),
-  maxEvents: external_exports.number().min(1).max(5e3).optional().describe("Maximum events to fetch for top action (default: 5000, max: 5000)")
+  maxEvents: external_exports.number().min(1).max(5e3).optional().describe("Maximum events to fetch for top action (default: 5000, max: 5000)"),
+  // History action parameters
+  transitionType: external_exports.array(
+    external_exports.enum([
+      "alert",
+      "alert recovery",
+      "warning",
+      "warning recovery",
+      "no data",
+      "no data recovery",
+      "renotify"
+    ])
+  ).optional().describe(
+    'For history action: filter by monitor state transition types. Default: ["alert","alert recovery"] (real fires + recoveries, excludes renotifies). Pass ["alert"] for fires only, or include "renotify" for full chronological audit.'
+  ),
+  group: external_exports.string().optional().describe(
+    'For history action: filter transitions to a specific multi-alert monitor group (e.g., "pod_name:foo,kube_namespace:bar"). Optional; omit for all groups.'
+  ),
+  dry_run: external_exports.boolean().optional().describe(
+    "When create + dry_run=true, validate the monitor body via POST /api/v1/monitor/validate without creating it. Allowed under --read-only because no monitor is created. Returns { valid, dryRun, monitor }. 400 responses surface verbatim like a failed create."
+  ),
+  timezone: external_exports.string().optional().describe(
+    'Optional IANA timezone (e.g. "UTC", "Europe/Paris"). When supplied on get/list, the response adds sibling createdLocal/modifiedLocal ISO 8601 strings next to created/modified. Omit for byte-identical legacy shape. Invalid zones return EINVALID_TIMEZONE.'
+  )
 };
 var MonitorThresholdsSchema = external_exports.object({
   critical: external_exports.number().optional(),
@@ -304001,6 +304703,18 @@ function summarizeZodIssue(error2) {
   const expected = issue2.code === "invalid_type" && "expected" in issue2 ? `expected ${String(issue2.expected)}` : issue2.message;
   return `${path}: ${expected}`;
 }
+function annotateMonitorTimezone(monitor, tz) {
+  const annotated = { ...monitor };
+  if (monitor.created) {
+    const ms = new Date(monitor.created).getTime();
+    if (Number.isFinite(ms)) annotated.createdLocal = formatLocal(ms, tz);
+  }
+  if (monitor.modified) {
+    const ms = new Date(monitor.modified).getTime();
+    if (Number.isFinite(ms)) annotated.modifiedLocal = formatLocal(ms, tz);
+  }
+  return annotated;
+}
 function formatMonitor(m, site = "datadoghq.com") {
   const monitorId = m.id ?? 0;
   return {
@@ -304032,14 +304746,165 @@ function formatMonitorDetail(m, site = "datadoghq.com") {
   }
   return detail;
 }
-async function listMonitors(api, params, limits, site) {
+var DEFAULT_HISTORY_TRANSITION_TYPES = [
+  "alert",
+  "alert recovery"
+];
+function quoteIfNeeded2(value) {
+  return /^[A-Za-z0-9_.-]+$/.test(value) ? value : `"${value}"`;
+}
+function buildMonitorHistoryQuery(params) {
+  const parts = ["source:alert", `@monitor.id:${params.monitorId}`];
+  const transitionTypes = params.transitionType && params.transitionType.length > 0 ? params.transitionType : void 0;
+  if (transitionTypes) {
+    const inner = transitionTypes.map(quoteIfNeeded2).join(" OR ");
+    parts.push(`@monitor.transition.transition_type:(${inner})`);
+  }
+  if (params.group && params.group.length > 0) {
+    const escaped = params.group.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    parts.push(`@monitor.groups:"${escaped}"`);
+  }
+  return parts.join(" ");
+}
+function isMonitorState(value) {
+  return value === "Alert" || value === "Warn" || value === "OK" || value === "No Data";
+}
+function isTransitionType(value) {
+  return value === "alert" || value === "alert recovery" || value === "warning" || value === "warning recovery" || value === "no data" || value === "no data recovery" || value === "renotify";
+}
+function extractTimestamp(outer, inner) {
+  const outerTs = outer.timestamp;
+  if (outerTs instanceof Date) {
+    return outerTs.toISOString();
+  }
+  if (typeof outerTs === "string" && outerTs.length > 0) {
+    const d = new Date(outerTs);
+    if (!Number.isNaN(d.getTime())) return d.toISOString();
+  }
+  const innerTs = inner.timestamp;
+  if (typeof innerTs === "number" && Number.isFinite(innerTs)) {
+    return new Date(innerTs).toISOString();
+  }
+  if (typeof innerTs === "string" && innerTs.length > 0) {
+    const parsed = Number.parseInt(innerTs, 10);
+    if (!Number.isNaN(parsed)) {
+      return new Date(parsed).toISOString();
+    }
+  }
+  return "";
+}
+function formatMonitorTransition(event) {
+  const outer = event.attributes ?? {};
+  const inner = outer.attributes ?? {};
+  const monitor = inner.monitor;
+  if (!monitor) {
+    return null;
+  }
+  const transition = monitor.transition ?? monitor.additionalProperties?.transition;
+  if (!transition) {
+    return null;
+  }
+  const fromState = isMonitorState(transition.source_state) ? transition.source_state : null;
+  const toState = isMonitorState(transition.destination_state) ? transition.destination_state : null;
+  const transitionType = isTransitionType(transition.transition_type) ? transition.transition_type : null;
+  if (!fromState || !toState || !transitionType) {
+    return null;
+  }
+  const groupsRaw = monitor.groups;
+  const group = Array.isArray(groupsRaw) && groupsRaw.length > 0 ? groupsRaw.map((g) => String(g)).join(",") : null;
+  const monitorId = typeof monitor.id === "number" ? monitor.id : 0;
+  const monitorName = typeof monitor.name === "string" && monitor.name.length > 0 ? monitor.name : `Monitor ${monitorId}`;
+  return {
+    timestamp: extractTimestamp(outer, inner),
+    monitorId,
+    monitorName,
+    group,
+    fromState,
+    toState,
+    transitionType,
+    eventId: String(event.id ?? "")
+  };
+}
+async function historyMonitor(eventsApi, monitorId, params, limits, site) {
+  const defaultFrom = hoursAgo(limits.defaultTimeRangeHours);
+  const defaultTo = now();
+  const [validFrom, validTo] = ensureValidTimeRange(
+    parseTime(params.from, defaultFrom),
+    parseTime(params.to, defaultTo)
+  );
+  const fromTime = new Date(validFrom * 1e3).toISOString();
+  const toTime = new Date(validTo * 1e3).toISOString();
+  const effectiveTransitionTypes = params.transitionType && params.transitionType.length > 0 ? params.transitionType : [...DEFAULT_HISTORY_TRANSITION_TYPES];
+  const query = buildMonitorHistoryQuery({
+    monitorId,
+    transitionType: effectiveTransitionTypes,
+    group: params.group
+  });
+  const transitions = [];
+  const maxEventsToProcess = 1e4;
+  const maxPages = 100;
+  let eventCount = 0;
+  let pageCount = 0;
+  const body = {
+    filter: {
+      query,
+      from: fromTime,
+      to: toTime
+    },
+    sort: "timestamp",
+    page: { limit: 1e3 }
+  };
+  let cursor;
+  while (pageCount < maxPages && eventCount < maxEventsToProcess) {
+    const pageBody = { ...body, page: { ...body.page, cursor } };
+    const response = await eventsApi.searchEvents({ body: pageBody });
+    const events2 = response.data ?? [];
+    if (events2.length === 0) break;
+    for (const event of events2) {
+      const transition = formatMonitorTransition(event);
+      if (transition !== null) {
+        transitions.push(transition);
+      }
+      eventCount++;
+      if (eventCount >= maxEventsToProcess) break;
+    }
+    cursor = response.meta?.page?.after;
+    if (!cursor) break;
+    pageCount++;
+  }
+  const truncated = eventCount >= maxEventsToProcess;
+  const resolvedGroup = params.group && params.group.length > 0 ? params.group : null;
+  const count = transitions.length;
+  const meta = {
+    monitorId,
+    query,
+    from: fromTime,
+    to: toTime,
+    transitionTypes: effectiveTransitionTypes,
+    group: resolvedGroup,
+    count,
+    totalFetched: eventCount,
+    truncated,
+    datadog_url: buildEventsUrl(query, validFrom, validTo, site)
+  };
+  return {
+    transitions,
+    count,
+    meta
+  };
+}
+async function listMonitors(api, params, limits, site, timezone) {
+  if (timezone !== void 0) {
+    validateIanaZone(timezone);
+  }
   const effectiveLimit = params.limit ?? limits.defaultLimit;
   const response = await api.listMonitors({
     name: params.name,
     tags: params.tags?.join(","),
     groupStates: params.groupStates?.join(",")
   });
-  const monitors2 = response.slice(0, effectiveLimit).map((m) => formatMonitor(m, site));
+  const baseMonitors = response.slice(0, effectiveLimit).map((m) => formatMonitor(m, site));
+  const monitors2 = timezone !== void 0 ? baseMonitors.map((m) => annotateMonitorTimezone(m, timezone)) : baseMonitors;
   const statusCounts = {
     total: response.length,
     alert: response.filter((m) => m.overallState === "Alert").length,
@@ -304056,14 +304921,19 @@ async function listMonitors(api, params, limits, site) {
     )
   };
 }
-async function getMonitor(api, id, site) {
+async function getMonitor(api, id, site, timezone) {
+  if (timezone !== void 0) {
+    validateIanaZone(timezone);
+  }
   const monitorId = Number.parseInt(id, 10);
   if (Number.isNaN(monitorId)) {
     throw new Error(`Invalid monitor ID: ${id}`);
   }
   const monitor = await api.getMonitor({ monitorId });
+  const baseDetail = formatMonitorDetail(monitor, site);
+  const detail = timezone !== void 0 ? annotateMonitorTimezone(baseDetail, timezone) : baseDetail;
   return {
-    monitor: formatMonitorDetail(monitor, site),
+    monitor: detail,
     datadog_url: buildMonitorUrl(monitorId, site)
   };
 }
@@ -304165,6 +305035,37 @@ async function createMonitor(api, config2, site = "datadoghq.com") {
   }
   return result;
 }
+async function dryRunMonitor(api, config2) {
+  const normalized = normalizeMonitorConfig(config2);
+  const body = normalized;
+  await api.validateMonitor({ body });
+  return {
+    valid: true,
+    dryRun: true,
+    monitor: normalized
+  };
+}
+async function previewMonitor(api, args, site = "datadoghq.com") {
+  let template;
+  let monitorId;
+  if (args.inlineMessage !== void 0 && args.inlineMessage !== "") {
+    template = args.inlineMessage;
+  } else if (args.monitorIdSource !== void 0 && args.monitorIdSource !== "") {
+    const loaded = await getMonitor(api, args.monitorIdSource, site);
+    template = loaded.monitor.message ?? "";
+    monitorId = loaded.monitor.id;
+  } else {
+    throw new Error(
+      "Action 'preview' requires either an inline 'message' or a 'monitor_id' (or 'id') to load the template from."
+    );
+  }
+  const result = renderMonitorTemplate(template, args.context ?? {});
+  return monitorId !== void 0 ? { ...result, monitorId } : result;
+}
+var TEST_NOTIFICATION_NOT_SUPPORTED_MESSAGE = "ENOT_SUPPORTED: action 'test_notification' is not implemented \u2014 the Datadog public REST API exposes no monitor test-notification endpoint at v1 or v2 as of the events-dx-improvements spec. Use the Datadog UI's 'Test Notifications' button on the monitor page, or open an issue if Datadog publishes such an endpoint. Reference: https://docs.datadoghq.com/api/latest/monitors/";
+function testNotificationMonitor(_args) {
+  throw new McpError(ErrorCode.InvalidRequest, TEST_NOTIFICATION_NOT_SUPPORTED_MESSAGE);
+}
 async function updateMonitor(api, id, config2, site = "datadoghq.com") {
   const monitorId = Number.parseInt(id, 10);
   const normalized = normalizeMonitorConfig(config2, true);
@@ -304249,7 +305150,7 @@ async function topMonitors(eventsApi, monitorsApi, params, limits, site) {
     }
   });
   const rawEvents = searchResponse.data ?? [];
-  const events = rawEvents.map(formatEventV2);
+  const events2 = rawEvents.map(formatEventV2);
   const contextPrefixes = new Set(
     params.contextTags ?? [
       "queue",
@@ -304261,7 +305162,7 @@ async function topMonitors(eventsApi, monitorsApi, params, limits, site) {
     ]
   );
   const monitorGroups = /* @__PURE__ */ new Map();
-  for (const event of events) {
+  for (const event of events2) {
     const monitorId = event.monitorId;
     if (typeof monitorId !== "number") continue;
     let group = monitorGroups.get(monitorId);
@@ -304330,7 +305231,7 @@ async function topMonitors(eventsApi, monitorsApi, params, limits, site) {
       from: fromTime,
       to: toTime,
       totalMonitors: monitorGroups.size,
-      totalEvents: events.length,
+      totalEvents: events2.length,
       contextPrefixes: Array.from(contextPrefixes),
       datadog_url: buildEventsUrl(query, validFrom, validTo, site)
     }
@@ -304339,7 +305240,7 @@ async function topMonitors(eventsApi, monitorsApi, params, limits, site) {
 function registerMonitorsTool(server, api, eventsApi, limits, readOnly = false, site = "datadoghq.com") {
   server.tool(
     "monitors",
-    `Manage Datadog monitors. Actions: list, get, search, create, update, delete, mute, unmute, top.
+    `Manage Datadog monitors. Actions: list, get, search, create, update, delete, mute, unmute, top, history, preview, test_notification.
 Filters: name, tags, groupStates (alert/warn/ok/no data).
 get/create/update return the full options object so callers can safely read-then-patch.
 
@@ -304361,8 +305262,40 @@ top: Ranked monitors by alert frequency with real monitor names and context brea
   - Returns: {rank, monitor_id, name (with {{template.vars}}), message (template), total_count, by_context}
   - Perfect for weekly/daily alert reports
   - Gets real monitor names from monitors API (not event titles)
-
-For generic event grouping (deployments, configs), use events tool instead.`,
+  - WARNING: total_count is the raw alert-event count and INCLUDES renotifies/re-evaluations.
+    For monitors stuck in Alert state, Datadog emits a renotify event every renotify_interval
+    minutes, which inflates this count well beyond the number of real fires. When the question
+    is "how many times did this monitor actually fire", use action=history instead.
+
+history: Count and list real state transitions for one monitor over a time window.
+  - Inputs: id (required, monitor ID), from/to (optional time range), transitionType (optional
+    filter, defaults to ["alert","alert recovery"]), group (optional multi-alert group filter).
+  - Returns: {transitions: [{timestamp, monitorId, monitorName, group, fromState, toState,
+    transitionType, eventId}], count, meta}
+  - count = transitions.length \u2014 the number of REAL state changes (fires + recoveries by
+    default), NOT the renotify-inflated count returned by action=top or events action=search.
+  - Backed by Datadog v2 events search with a hardcoded source:alert + @monitor.transition.
+    transition_type filter that excludes renotifies by default. To include renotifies, pass
+    transitionType including "renotify".
+
+preview: Render a Datadog monitor message template against a context (read-only safe).
+  - Inputs: either inline 'message' OR 'monitor_id' (or existing 'id'); plus optional 'context' { variables, conditionals }.
+  - Supported syntax: {{variable.name}} substitution and conditional blocks {{#name}}...{{/name}} / {{^name}}...{{/name}}
+    where name is one of: ${SUPPORTED_CONDITIONALS.join(", ")}.
+  - Missing variables render as {{undefined:name}} markers and are reported in 'variablesMissing'.
+  - Loops ({{#each ...}}) and partials ({{> ...}}) return EUNSUPPORTED_TEMPLATE_SYNTAX.
+  - Allowed under --read-only (no mutation; at most a getMonitor load).
+
+test_notification: KNOWN LIMITATION \u2014 always returns ENOT_SUPPORTED.
+  - Datadog's public REST API exposes no monitor test-notification endpoint at v1 or v2
+    (audited against the official OpenAPI specs). The v1 SDK has no notifyMonitor / testMonitor method.
+  - Allowed under --read-only because no Datadog HTTP call is attempted.
+  - If Datadog publishes such an endpoint in future, this action will be reimplemented to invoke it.
+  - Workaround: use the 'Test Notifications' button in the Datadog monitor UI.
+
+For generic event grouping (deployments, configs), use events tool instead. Note that the
+events tool's action=search with source:alert ALSO includes renotifies; use its
+transitionType filter (or this action=history) for fires-only counts.`,
     InputSchema2,
     async ({
       action,
@@ -304373,22 +305306,32 @@ For generic event grouping (deployments, configs), use events tool instead.`,
       groupStates,
       limit,
       config: config2,
+      message,
       end,
       from,
       to,
       contextTags,
-      maxEvents
+      maxEvents,
+      transitionType,
+      group,
+      dry_run: dryRun,
+      monitor_id: monitorIdNum,
+      context,
+      timezone
     }) => {
       try {
-        checkReadOnly(action, readOnly);
+        const isDryRunCreate = action === "create" && dryRun === true;
+        if (!isDryRunCreate) {
+          checkReadOnly(action, readOnly);
+        }
         switch (action) {
           case "list":
             return toolResult(
-              await listMonitors(api, { name, tags, groupStates, limit }, limits, site)
+              await listMonitors(api, { name, tags, groupStates, limit }, limits, site, timezone)
             );
           case "get": {
             const monitorId = requireParam(id, "id", "get");
-            return toolResult(await getMonitor(api, monitorId, site));
+            return toolResult(await getMonitor(api, monitorId, site, timezone));
           }
           case "search": {
             const searchQuery = requireParam(query, "query", "search");
@@ -304396,6 +305339,9 @@ For generic event grouping (deployments, configs), use events tool instead.`,
           }
           case "create": {
             const monitorConfig = requireParam(config2, "config", "create");
+            if (dryRun) {
+              return toolResult(await dryRunMonitor(api, monitorConfig));
+            }
             return toolResult(await createMonitor(api, monitorConfig, site));
           }
           case "update": {
@@ -304432,6 +305378,40 @@ For generic event grouping (deployments, configs), use events tool instead.`,
                 site
               )
             );
+          case "history": {
+            const monitorIdString = requireParam(id, "id", "history");
+            const monitorId = Number.parseInt(monitorIdString, 10);
+            if (Number.isNaN(monitorId)) {
+              throw new Error(`Invalid monitor ID: ${monitorIdString}`);
+            }
+            return toolResult(
+              await historyMonitor(
+                eventsApi,
+                monitorId,
+                { from, to, transitionType, group },
+                limits,
+                site
+              )
+            );
+          }
+          case "preview": {
+            const monitorIdSource = monitorIdNum !== void 0 ? String(monitorIdNum) : id ?? void 0;
+            return toolResult(
+              await previewMonitor(
+                api,
+                {
+                  inlineMessage: message,
+                  monitorIdSource,
+                  context
+                },
+                site
+              )
+            );
+          }
+          case "test_notification": {
+            const monitorIdSource = monitorIdNum !== void 0 ? String(monitorIdNum) : id ?? void 0;
+            return testNotificationMonitor({ monitorId: monitorIdSource });
+          }
           default:
             throw new Error(`Unknown action: ${action}`);
         }
@@ -305048,6 +306028,56 @@ var InputSchema5 = {
     "Maximum data points per timeseries (for query action). AI controls resolution vs token usage (default: 1000)."
   )
 };
+var ROLLUP_METHODS = /* @__PURE__ */ new Set(["avg", "max", "min", "sum", "count"]);
+var DEFAULT_ROLLUP_METHOD = "avg";
+function parseRollupFromQuery(query) {
+  if (typeof query !== "string") return null;
+  const matches = [...query.matchAll(/\.rollup\(\s*([^)]*?)\s*\)/g)];
+  const lastMatch = matches[matches.length - 1];
+  if (lastMatch === void 0) return null;
+  const inner = lastMatch[1];
+  if (inner === void 0 || inner.length === 0) return null;
+  const parts = inner.split(",").map((p) => p.trim());
+  if (parts.length === 1) {
+    const raw = parts[0] ?? "";
+    const interval = Number.parseInt(raw, 10);
+    if (!Number.isFinite(interval) || interval <= 0 || String(interval) !== raw) {
+      return null;
+    }
+    return { interval, method: DEFAULT_ROLLUP_METHOD, methodInferred: true };
+  }
+  if (parts.length === 2) {
+    const method = parts[0] ?? "";
+    const secondsRaw = parts[1] ?? "";
+    if (!ROLLUP_METHODS.has(method)) return null;
+    const interval = Number.parseInt(secondsRaw, 10);
+    if (!Number.isFinite(interval) || interval <= 0 || String(interval) !== secondsRaw) {
+      return null;
+    }
+    return { interval, method, methodInferred: false };
+  }
+  return null;
+}
+function computeEffectiveRollup(series) {
+  const intervals = [];
+  for (const s of series) {
+    const pts = s.pointlist ?? [];
+    if (pts.length < 2) continue;
+    const first = pts[0];
+    const second = pts[1];
+    if (first === void 0 || second === void 0) continue;
+    const deltaMs = (second[0] ?? 0) - (first[0] ?? 0);
+    if (deltaMs <= 0) continue;
+    intervals.push(Math.round(deltaMs / 1e3));
+  }
+  const primary = intervals[0];
+  if (primary === void 0) return null;
+  const unique = Array.from(new Set(intervals)).sort((a, b) => a - b);
+  if (unique.length === 1) {
+    return { interval: primary };
+  }
+  return { interval: primary, intervalsObserved: unique };
+}
 async function queryMetrics(api, params, limits, site) {
   const defaultFrom = hoursAgo(limits.defaultTimeRangeHours);
   const defaultTo = now();
@@ -305060,7 +306090,8 @@ async function queryMetrics(api, params, limits, site) {
     to: toTs,
     query: params.query
   });
-  const series = (response.series ?? []).map((s) => ({
+  const rawSeries = response.series ?? [];
+  const series = rawSeries.map((s) => ({
     metric: s.metric ?? "",
     points: (s.pointlist ?? []).slice(0, params.pointLimit ?? limits.defaultMetricDataPoints).map((p) => ({
       timestamp: p[0] ?? 0,
@@ -305069,6 +306100,13 @@ async function queryMetrics(api, params, limits, site) {
     scope: s.scope ?? "",
     tags: s.tagSet ?? []
   }));
+  const rollupRequested = parseRollupFromQuery(params.query);
+  const rollupEffective = computeEffectiveRollup(
+    rawSeries.map((s) => ({
+      pointlist: s.pointlist ?? []
+    }))
+  );
+  const rollupOverridden = rollupRequested !== null && rollupEffective !== null && (rollupEffective.interval !== rollupRequested.interval || (rollupEffective.intervalsObserved?.some((i) => i !== rollupRequested.interval) ?? false));
   return {
     series,
     meta: {
@@ -305076,7 +306114,10 @@ async function queryMetrics(api, params, limits, site) {
       from: new Date(fromTs * 1e3).toISOString(),
       to: new Date(toTs * 1e3).toISOString(),
       seriesCount: series.length,
-      datadog_url: buildMetricsUrl(params.query, fromTs, toTs, site)
+      datadog_url: buildMetricsUrl(params.query, fromTs, toTs, site),
+      rollupRequested,
+      rollupEffective,
+      rollupOverridden
     }
   };
 }
@@ -306617,11 +307658,11 @@ async function searchEvents(api, params, limits, site) {
     sort: params.sort === "timestamp" ? "timestamp" : "-timestamp",
     pageLimit: params.limit ?? limits.defaultLimit
   });
-  const events = (response.data ?? []).map(formatEvent);
+  const events2 = (response.data ?? []).map(formatEvent);
   return {
-    events,
+    events: events2,
     meta: {
-      totalCount: events.length,
+      totalCount: events2.length,
       timeRange: {
         from: new Date(fromTime * 1e3).toISOString(),
         to: new Date(toTime * 1e3).toISOString()
@@ -306834,19 +307875,19 @@ async function getSessionWaterfall(api, params, limits, site) {
     sort: "timestamp",
     pageLimit: limits.defaultLimit
   });
-  const events = (response.data ?? []).map(formatWaterfallEvent);
+  const events2 = (response.data ?? []).map(formatWaterfallEvent);
   const summary = {
-    views: events.filter((e) => e.type === "view").length,
-    resources: events.filter((e) => e.type === "resource").length,
-    actions: events.filter((e) => e.type === "action").length,
-    errors: events.filter((e) => e.type === "error").length,
-    longTasks: events.filter((e) => e.type === "long_task").length
+    views: events2.filter((e) => e.type === "view").length,
+    resources: events2.filter((e) => e.type === "resource").length,
+    actions: events2.filter((e) => e.type === "action").length,
+    errors: events2.filter((e) => e.type === "error").length,
+    longTasks: events2.filter((e) => e.type === "long_task").length
   };
   return {
-    events,
+    events: events2,
     summary,
     meta: {
-      totalCount: events.length,
+      totalCount: events2.length,
       applicationId: params.applicationId,
       sessionId: params.sessionId,
       viewId: params.viewId ?? null,
@@ -308026,6 +309067,17 @@ var dashboards = {
   docsUrl: "https://docs.datadoghq.com/api/latest/dashboards/"
 };
 
+// src/schema/events.ts
+var events = {
+  /**
+   * Diagnostic codes emitted on zero-result `events.search` responses.
+   * Each code is also documented inline in `src/tools/events.ts` next to the
+   * heuristic that produces it.
+   */
+  diagnosticCodes: ["UNINDEXED_TAG_PREFIX", "NARROW_TIME_RANGE", "RESTRICTIVE_SOURCE_FILTER"],
+  docsUrl: "https://docs.datadoghq.com/api/latest/events/"
+};
+
 // src/schema/metrics.ts
 var metrics = {
   aggregators: ["avg", "max", "min", "sum", "count"],
@@ -308086,14 +309138,14 @@ var slos = {
 };
 
 // src/schema/index.ts
-var schemas = { dashboards, metrics, monitors, slos };
+var schemas = { dashboards, events, metrics, monitors, slos };
 var schemaResources = Object.keys(schemas);
 
 // src/tools/schema.ts
 var ResourceSchema2 = external_exports.enum(schemaResources);
 var InputSchema20 = {
   resource: ResourceSchema2.describe(
-    "Datadog resource type to get schema for: dashboards, metrics, monitors, slos"
+    "Datadog resource type to get schema for: dashboards, events, metrics, monitors, slos"
   )
 };
 function getSchema(resource) {