datadog-mcp 5.6.0 → 5.8.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",
@@ -302780,6 +302786,10 @@ function buildRumSessionUrl(applicationId, sessionId, site = "datadoghq.com") {
   const base = getAppBaseUrl(site);
   return `${base}/rum/replay/sessions/${sessionId}?applicationId=${encodeURIComponent(applicationId)}`;
 }
+function buildSloUrl(sloId, site = "datadoghq.com") {
+  const base = getAppBaseUrl(site);
+  return `${base}/slo/${sloId}`;
+}
 
 // src/utils/time.ts
 function hoursAgo(hours) {
@@ -302904,6 +302914,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 +303100,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)"),
@@ -302959,8 +303147,54 @@ var InputSchema = {
     ])
   ).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.'
+  ),
+  // Projection — applied to search action only. Reduces response payload
+  // when callers only need a subset of fields. Unknown field names are silently ignored so
+  // older clients are not broken when the EventSummary shape evolves.
+  fields: external_exports.array(external_exports.string()).optional().describe(
+    "Search action only: return only these event fields. Allowed values: id, title, message, timestamp, priority, source, tags, alertType, host, monitorId, monitorInfo, monitorMetadata (only populated when enrich=true). Default: full event."
   )
 };
+var ALLOWED_EVENT_FIELDS = /* @__PURE__ */ new Set([
+  "id",
+  "title",
+  "message",
+  "timestamp",
+  "priority",
+  "source",
+  "tags",
+  "alertType",
+  "host",
+  "monitorId",
+  "monitorInfo",
+  "monitorMetadata"
+]);
+function pickEventFields(event, fields) {
+  if (!fields || fields.length === 0) {
+    return event;
+  }
+  const projection = {};
+  for (const key of fields) {
+    if (ALLOWED_EVENT_FIELDS.has(key)) {
+      ;
+      projection[key] = event[key];
+    }
+  }
+  return projection;
+}
+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;
@@ -303147,17 +303381,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) {
@@ -303186,6 +303420,85 @@ 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}"`;
 }
@@ -303213,6 +303526,9 @@ function buildEventQuery(params) {
   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(
@@ -303242,12 +303558,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,
@@ -303255,8 +303572,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();
@@ -303293,9 +303733,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);
@@ -303316,7 +303756,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,
@@ -303333,6 +303774,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");
@@ -303370,7 +303814,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}`);
@@ -303431,6 +303875,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(
@@ -303465,9 +303912,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();
@@ -303484,6 +303931,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;
@@ -303491,12 +303939,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);
@@ -303517,6 +303969,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(
@@ -303551,9 +304006,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) {
@@ -303621,6 +304076,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) {
@@ -303633,7 +304089,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(),
@@ -303641,8 +304097,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()
@@ -303665,15 +304130,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 {
@@ -303687,9 +304152,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);
@@ -303714,7 +304179,7 @@ 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:
@@ -303732,7 +304197,8 @@ 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,
@@ -303754,7 +304220,10 @@ incidents: Deduplicate alerts with dedupeWindow.`,
       enrich,
       contextTags,
       maxEvents,
-      transitionType
+      transitionType,
+      bucket_by,
+      timezone,
+      fields
     }) => {
       try {
         checkReadOnly(action, readOnly);
@@ -303804,16 +304273,19 @@ incidents: Deduplicate alerts with dedupeWindow.`,
                 priority,
                 limit,
                 cursor,
-                transitionType
+                transitionType,
+                timezone
               },
               limits,
               site
             );
             if (enrich && result.events.length > 0) {
               const enrichedEvents = await enrichWithMonitorMetadata(result.events, monitorsApi);
-              return toolResult({ ...result, events: enrichedEvents });
+              const projected = fields?.length ? enrichedEvents.map((e) => pickEventFields(e, fields)) : enrichedEvents;
+              return toolResult({ ...result, events: projected });
             }
-            return toolResult(result);
+            const projectedEvents = fields?.length ? result.events.map((e) => pickEventFields(e, fields)) : result.events;
+            return toolResult({ ...result, events: projectedEvents });
           }
           case "aggregate":
             return toolResult(
@@ -303827,7 +304299,8 @@ incidents: Deduplicate alerts with dedupeWindow.`,
                   tags,
                   groupBy,
                   limit,
-                  transitionType
+                  transitionType,
+                  timezone
                 },
                 limits,
                 site
@@ -303847,7 +304320,8 @@ incidents: Deduplicate alerts with dedupeWindow.`,
                   groupBy,
                   contextTags,
                   maxEvents,
-                  transitionType
+                  transitionType,
+                  timezone
                 },
                 limits,
                 site
@@ -303881,7 +304355,8 @@ incidents: Deduplicate alerts with dedupeWindow.`,
                   groupBy,
                   interval,
                   limit,
-                  transitionType
+                  transitionType,
+                  timezone
                 },
                 limits,
                 site
@@ -303899,12 +304374,33 @@ incidents: Deduplicate alerts with dedupeWindow.`,
                   tags,
                   dedupeWindow,
                   limit,
-                  transitionType
+                  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}`);
         }
@@ -303915,6 +304411,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",
@@ -303926,8 +304593,14 @@ var ActionSchema2 = external_exports.enum([
   "mute",
   "unmute",
   "top",
-  "history"
+  "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)"),
@@ -303939,8 +304612,14 @@ 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)'),
@@ -303964,6 +304643,12 @@ var InputSchema2 = {
   ),
   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({
@@ -304058,6 +304743,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 {
@@ -304201,9 +304898,9 @@ async function historyMonitor(eventsApi, monitorId, params, limits, site) {
   while (pageCount < maxPages && eventCount < maxEventsToProcess) {
     const pageBody = { ...body, page: { ...body.page, cursor } };
     const response = await eventsApi.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 transition = formatMonitorTransition(event);
       if (transition !== null) {
         transitions.push(transition);
@@ -304236,14 +304933,18 @@ async function historyMonitor(eventsApi, monitorId, params, limits, site) {
     meta
   };
 }
-async function listMonitors(api, params, limits, site) {
+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,
@@ -304260,14 +304961,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)
   };
 }
@@ -304369,6 +305075,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);
@@ -304453,7 +305190,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",
@@ -304465,7 +305202,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);
@@ -304534,7 +305271,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)
     }
@@ -304543,7 +305280,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, history.
+    `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.
 
@@ -304581,6 +305318,21 @@ history: Count and list real state transitions for one monitor over a time windo
     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.`,
@@ -304594,24 +305346,32 @@ transitionType filter (or this action=history) for fires-only counts.`,
       groupStates,
       limit,
       config: config2,
+      message,
       end,
       from,
       to,
       contextTags,
       maxEvents,
       transitionType,
-      group
+      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");
@@ -304619,6 +305379,9 @@ transitionType filter (or this action=history) for fires-only counts.`,
           }
           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": {
@@ -304671,6 +305434,24 @@ transitionType filter (or this action=history) for fires-only counts.`,
               )
             );
           }
+          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}`);
         }
@@ -305287,6 +306068,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();
@@ -305299,7 +306130,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,
@@ -305308,6 +306140,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: {
@@ -305315,7 +306154,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
     }
   };
 }
@@ -305995,10 +306837,11 @@ var InputSchema8 = {
   from: external_exports.string().optional().describe('Start time for history (ISO 8601 or relative like "7d", "1w")'),
   to: external_exports.string().optional().describe("End time for history (ISO 8601 or relative, default: now)")
 };
-function formatSlo(s) {
+function formatSlo(s, site = "datadoghq.com") {
   const primaryThreshold = s.thresholds?.[0];
+  const id = s.id ?? "";
   const summary = {
-    id: s.id ?? "",
+    id,
     name: s.name ?? "",
     description: s.description ?? null,
     type: String(s.type ?? "unknown"),
@@ -306013,7 +306856,8 @@ function formatSlo(s) {
     },
     overallStatus: [],
     createdAt: s.createdAt ? new Date(s.createdAt * 1e3).toISOString() : "",
-    modifiedAt: s.modifiedAt ? new Date(s.modifiedAt * 1e3).toISOString() : ""
+    modifiedAt: s.modifiedAt ? new Date(s.modifiedAt * 1e3).toISOString() : "",
+    url: id ? buildSloUrl(id, site) : ""
   };
   if (s.query?.numerator && s.query.denominator) {
     summary.query = { numerator: s.query.numerator, denominator: s.query.denominator };
@@ -306029,11 +306873,12 @@ function formatSlo(s) {
   }
   return summary;
 }
-function formatSearchSlo(slo) {
+function formatSearchSlo(slo, site = "datadoghq.com") {
   const attrs = slo.data?.attributes;
   const primaryThreshold = attrs?.thresholds?.[0];
+  const id = slo.data?.id ?? "";
   const summary = {
-    id: slo.data?.id ?? "",
+    id,
     name: attrs?.name ?? "",
     description: attrs?.description ?? null,
     type: String(attrs?.sloType ?? "unknown"),
@@ -306054,7 +306899,8 @@ function formatSearchSlo(slo) {
       timeframe: String(os.timeframe ?? "")
     })),
     createdAt: attrs?.createdAt ? new Date(attrs.createdAt * 1e3).toISOString() : "",
-    modifiedAt: attrs?.modifiedAt ? new Date(attrs.modifiedAt * 1e3).toISOString() : ""
+    modifiedAt: attrs?.modifiedAt ? new Date(attrs.modifiedAt * 1e3).toISOString() : "",
+    url: id ? buildSloUrl(id, site) : ""
   };
   if (attrs?.query?.numerator && attrs.query.denominator) {
     summary.query = { numerator: attrs.query.numerator, denominator: attrs.query.denominator };
@@ -306073,14 +306919,14 @@ function buildSearchQuery(query, tags) {
   if (tags?.length) parts.push(...tags);
   return parts.join(" ");
 }
-async function listSlos(api, params, limits) {
+async function listSlos(api, params, limits, site = "datadoghq.com") {
   const effectiveLimit = params.limit ?? limits.defaultLimit;
   if (params.ids?.length) {
     const response2 = await api.listSLOs({
       ids: params.ids.join(","),
       limit: effectiveLimit
     });
-    const slos3 = (response2.data ?? []).map(formatSlo);
+    const slos3 = (response2.data ?? []).map((s) => formatSlo(s, site));
     return { slos: slos3, total: slos3.length };
   }
   const searchQuery = buildSearchQuery(params.query, params.tags);
@@ -306089,16 +306935,16 @@ async function listSlos(api, params, limits) {
     pageSize: effectiveLimit
   });
   const searchSlos = response.data?.attributes?.slos ?? [];
-  const slos2 = searchSlos.map(formatSearchSlo);
+  const slos2 = searchSlos.map((s) => formatSearchSlo(s, site));
   return {
     slos: slos2,
     total: slos2.length
   };
 }
-async function getSlo(api, id) {
+async function getSlo(api, id, site = "datadoghq.com") {
   const response = await api.getSLO({ sloId: id });
   return {
-    slo: response.data ? formatSlo(response.data) : null
+    slo: response.data ? formatSlo(response.data, site) : null
   };
 }
 function normalizeSloConfig(config2) {
@@ -306114,20 +306960,20 @@ function normalizeSloConfig(config2) {
   }
   return normalized;
 }
-async function createSlo(api, config2) {
+async function createSlo(api, config2, site = "datadoghq.com") {
   const body = normalizeSloConfig(config2);
   const response = await api.createSLO({ body });
   return {
     success: true,
-    slo: response.data?.[0] ? formatSlo(response.data[0]) : null
+    slo: response.data?.[0] ? formatSlo(response.data[0], site) : null
   };
 }
-async function updateSlo(api, id, config2) {
+async function updateSlo(api, id, config2, site = "datadoghq.com") {
   const body = normalizeConfigKeys(config2);
   const response = await api.updateSLO({ sloId: id, body });
   return {
     success: true,
-    slo: response.data?.[0] ? formatSlo(response.data[0]) : null
+    slo: response.data?.[0] ? formatSlo(response.data[0], site) : null
   };
 }
 async function deleteSlo(api, id) {
@@ -306167,29 +307013,29 @@ async function getSloHistory(api, id, params) {
     }
   };
 }
-function registerSlosTool(server, api, limits, readOnly = false, _site = "datadoghq.com") {
+function registerSlosTool(server, api, limits, readOnly = false, site = "datadoghq.com") {
   server.tool(
     "slos",
-    "Manage Datadog Service Level Objectives. Actions: list (with SLI status & error budget), get, create, update, delete, history. SLO types: metric-based, monitor-based. Use for: reliability tracking, error budgets, SLA compliance, performance targets.",
+    "Manage Datadog Service Level Objectives. Actions: list (with SLI status & error budget), get, create, update, delete, history. SLO types: metric-based, monitor-based. Each list/get/create/update response includes a `url` field deep-linking to the Datadog UI. Use for: reliability tracking, error budgets, SLA compliance, performance targets.",
     InputSchema8,
     async ({ action, id, ids, query, tags, limit, config: config2, from, to }) => {
       try {
         checkReadOnly(action, readOnly);
         switch (action) {
           case "list":
-            return toolResult(await listSlos(api, { ids, query, tags, limit }, limits));
+            return toolResult(await listSlos(api, { ids, query, tags, limit }, limits, site));
           case "get": {
             const sloId = requireParam(id, "id", "get");
-            return toolResult(await getSlo(api, sloId));
+            return toolResult(await getSlo(api, sloId, site));
           }
           case "create": {
             const sloConfig = requireParam(config2, "config", "create");
-            return toolResult(await createSlo(api, sloConfig));
+            return toolResult(await createSlo(api, sloConfig, site));
           }
           case "update": {
             const sloId = requireParam(id, "id", "update");
             const sloConfig = requireParam(config2, "config", "update");
-            return toolResult(await updateSlo(api, sloId, sloConfig));
+            return toolResult(await updateSlo(api, sloId, sloConfig, site));
           }
           case "delete": {
             const sloId = requireParam(id, "id", "delete");
@@ -306856,11 +307702,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()
@@ -307073,19 +307919,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,
@@ -308265,6 +309111,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"],
@@ -308325,14 +309182,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) {