@littlebearapps/outlook-assistant 3.12.0 → 3.12.1

package/.env.example

@@ -31,6 +31,14 @@ USE_TEST_MODE=false
 # receivedBefore rather than raising this if you can.
 # OUTLOOK_SEARCH_SCAN_LIMIT=500
 
+# Inactivity timeout for each Graph request attempt (milliseconds): an attempt
+# that receives no data for this long is abandoned with a timeout error. It is
+# not an overall deadline — a slow response that keeps arriving isn't cut off.
+# Throttled (429) and busy (503/504) responses are retried automatically (up to
+# 3 times, honouring Retry-After); POST requests such as sending mail are only
+# retried on a 429 asking for a short wait (10 s or less, 20 s in total).
+# OUTLOOK_REQUEST_TIMEOUT_MS=60000
+
 # Optional: Default authentication method (device-code or browser)
 # device-code: No auth server needed, works remotely/headless
 # browser: Traditional OAuth redirect via localhost:3333

package/README.md

@@ -143,7 +143,7 @@ Outlook Assistant is designed with safety-first principles for AI-driven email a
 
 **Input and file hardening** — IDs containing `.` or `..` path segments are refused before any request is made, continuation links (`deltaToken`) must point at `graph.microsoft.com`, and attachment downloads and exports write sanitised filenames inside the output directory without overwriting existing files or following symlinks.
 
-**Draft protections** — The `draft` tool shares `send-email` safety controls: dry-run preview, recipient allowlist, mail-tips validation, and rate limiting. The `send` action shares the `send-email` rate limit counter, preventing circumvention via the draft-then-send pathway.
+**Draft protections** — The `draft` tool shares `send-email` safety controls: dry-run preview, recipient allowlist, mail-tips validation, and rate limiting. The `send` action shares the `send-email` rate limit counter, preventing circumvention via the draft-then-send pathway. `update`, `send` and `delete` refuse any ID that is not an unsent draft, so a received or sent message is never edited, deleted or re-sent.
 
 **Token-optimised architecture** — Tools are consolidated using the STRAP (Single Tool, Resource, Action Pattern) approach. 22 tools instead of 55 reduces per-turn overhead by ~11,000 tokens (~64%), keeping more of the AI's context window available for your actual conversation. Fewer tools also means the AI selects the right tool more accurately — research shows tool selection degrades beyond ~40 tools.
 
@@ -166,7 +166,7 @@ npx @littlebearapps/outlook-assistant
 To check which version you have, or to see the available options:
 
 ```bash
-outlook-assistant --version     # prints e.g. 3.12.0
+outlook-assistant --version     # prints e.g. 3.12.1
 outlook-assistant --help        # usage, options and key environment variables
 ```
 
@@ -374,6 +374,7 @@ USE_TEST_MODE=false
 | `OUTLOOK_ALLOWED_RECIPIENTS` | Comma-separated allowlist of domains/addresses for sends, drafts, and rule forwards. | unrestricted |
 | `OUTLOOK_SHARED_MAILBOX` | Opt-in shared-mailbox support (work/school only). `read` requests `Mail.Read.Shared`; `true` (or `readwrite`/`1`) also requests `Mail.ReadWrite.Shared`. Unset leaves sign-in unchanged. After enabling, restart and run `auth action=authenticate force=true`. | unset (off) |
 | `OUTLOOK_SEARCH_SCAN_LIMIT` | How many recent messages the client-side search fallback scans. Personal accounts match `to` locally within this window, so the default caps how far back a `to` search reaches. Max 5000. | `500` |
+| `OUTLOOK_REQUEST_TIMEOUT_MS` | Inactivity timeout for each Graph request attempt, in milliseconds: an attempt that receives no data for this long is abandoned with a timeout error. It isn't an overall deadline, so a slow response that keeps arriving isn't cut off. Throttled (`429`) and busy (`503`/`504`) responses are retried automatically, honouring `Retry-After`. | `60000` |
 
 ### MCP Client Configuration
 
@@ -451,7 +452,9 @@ outlook-assistant/
 │   ├── conversations.js     # Thread listing/export
 │   ├── attachments.js       # Attachment operations
 │   └── ...
-├── calendar/                # Calendar module (3 tools; list.js builds list-events filters)
+├── calendar/                # Calendar module (3 tools)
+│   ├── attendees.js         # Attendee builder (email or {email, type})
+│   └── list.js              # list-events filters
 ├── contacts/                # Contacts module (2 tools)
 ├── categories/              # Categories module (3 tools)
 ├── settings/                # Settings module (1 tool)
@@ -462,6 +465,8 @@ outlook-assistant/
     ├── graph-api.js         # Microsoft Graph API client (includes $batch, path guards)
     ├── mailbox.js           # me vs users/{sharedMailbox} prefix, shared-mailbox opt-in
     ├── safety.js            # Rate limiting, recipient allowlist, dry-run
+    ├── safe-write.js        # Exclusive, outputDir-confined file writes
+    ├── datetime.js          # ISO 8601 parsing and timezone conversion
     ├── odata-helpers.js     # OData query building
     ├── field-presets.js     # Token-efficient field selections
     ├── response-formatter.js # Verbosity levels

package/advanced/index.js

@@ -20,6 +20,12 @@ const {
 } = require('../utils/mailbox');
 const { resolveFolder } = require('../folder/resolve');
 const { getAllFoldersHierarchy } = require('../folder/list');
+const {
+  InvalidDateTimeError,
+  toGraphDateTimeTimeZone,
+  zonedParts,
+  zonedWallTimeToUtcMs,
+} = require('../utils/datetime');
 
 /**
  * Format an email for display (simplified)
@@ -408,6 +414,49 @@ async function handleListSharedMailboxFolders(sharedMailbox, args) {
   }
 }
 
+/**
+ * Default follow-up start for a flag with only a due date: 09:00 in
+ * DEFAULT_TIMEZONE on the due's local date, or the due itself when the due is
+ * earlier than that (a start after the due would be nonsense).
+ */
+function deriveFlagStart(due) {
+  let wall;
+  if (due.timeZone === DEFAULT_TIMEZONE) {
+    wall = due.dateTime;
+  } else {
+    const parts = zonedParts(Date.parse(`${due.dateTime}Z`), DEFAULT_TIMEZONE);
+    if (!parts) return { ...due };
+    wall = `${parts.date}T${parts.time}`;
+  }
+  const nineAm = `${wall.slice(0, 10)}T09:00:00`;
+  // Same zone and fixed-width prefix, so string order is time order.
+  return wall < nineAm
+    ? { ...due }
+    : { dateTime: nineAm, timeZone: DEFAULT_TIMEZONE };
+}
+
+/**
+ * Describe a flag dateTimeTimeZone envelope as UTC plus DEFAULT_TIMEZONE,
+ * e.g. "2026-03-01 09:00 UTC (2026-03-01 20:00 Australia/Melbourne)".
+ */
+function describeFlagTime(envelope) {
+  const ms =
+    envelope.timeZone === 'UTC'
+      ? Date.parse(`${envelope.dateTime}Z`)
+      : zonedWallTimeToUtcMs(envelope.dateTime, envelope.timeZone);
+  const local = (date, time) =>
+    `${date} ${time.slice(0, 5)} ${DEFAULT_TIMEZONE}`;
+  if (Number.isNaN(ms)) {
+    // DEFAULT_TIMEZONE isn't an IANA zone Intl knows; show it as given.
+    return local(envelope.dateTime.slice(0, 10), envelope.dateTime.slice(11));
+  }
+  const iso = new Date(ms).toISOString();
+  const utc = `${iso.slice(0, 10)} ${iso.slice(11, 16)} UTC`;
+  const parts =
+    DEFAULT_TIMEZONE === 'UTC' ? null : zonedParts(ms, DEFAULT_TIMEZONE);
+  return parts ? `${utc} (${local(parts.date, parts.time)})` : utc;
+}
+
 /**
  * Set message flag handler
  */
@@ -435,43 +484,38 @@ async function handleSetMessageFlag(args) {
     };
   }
 
+  // Build flag object. Zoned values (Z/offset) are sent as the same instant in
+  // UTC; zone-less values are read in DEFAULT_TIMEZONE. Bad dates are refused
+  // here, before authenticating or calling Graph.
+  const flag = {
+    flagStatus: 'flagged',
+  };
   try {
-    const accessToken = await ensureAuthenticated();
-
-    // Build flag object
-    const flag = {
-      flagStatus: 'flagged',
-    };
-
+    if (startDateTime) {
+      flag.startDateTime = toGraphDateTimeTimeZone(
+        startDateTime,
+        'startDateTime'
+      );
+    }
     if (dueDateTime) {
-      // Graph API expects { dateTime, timeZone } envelope without trailing Z
-      // When timeZone is specified, the dateTime value is interpreted in that zone
-      const dueDt = dueDateTime.replace(/Z$/i, '');
-      flag.dueDateTime = {
-        dateTime: dueDt,
-        timeZone: DEFAULT_TIMEZONE,
-      };
-
-      // Graph API requires startDateTime when dueDateTime is set
-      // Default to start of the same day if not explicitly provided
-      if (startDateTime) {
-        flag.startDateTime = {
-          dateTime: startDateTime.replace(/Z$/i, ''),
-          timeZone: DEFAULT_TIMEZONE,
-        };
-      } else {
-        const startOfDay = `${dueDt.split('T')[0]}T09:00:00`;
-        flag.startDateTime = {
-          dateTime: startOfDay,
-          timeZone: DEFAULT_TIMEZONE,
-        };
+      flag.dueDateTime = toGraphDateTimeTimeZone(dueDateTime, 'dueDateTime');
+      // Graph requires startDateTime when dueDateTime is set.
+      if (!flag.startDateTime) {
+        flag.startDateTime = deriveFlagStart(flag.dueDateTime);
       }
-    } else if (startDateTime) {
-      flag.startDateTime = {
-        dateTime: startDateTime.replace(/Z$/i, ''),
-        timeZone: DEFAULT_TIMEZONE,
+    }
+  } catch (error) {
+    if (error instanceof InvalidDateTimeError) {
+      return {
+        content: [{ type: 'text', text: error.message }],
+        isError: true,
       };
     }
+    throw error;
+  }
+
+  try {
+    const accessToken = await ensureAuthenticated();
 
     // Process all messages
     const results = [];
@@ -493,11 +537,11 @@ async function handleSetMessageFlag(args) {
     if (results.length > 0) {
       output.push(`Flagged ${results.length} message(s) for follow-up`);
 
-      if (dueDateTime) {
-        output.push(`**Due**: ${new Date(dueDateTime).toLocaleString()}`);
+      if (flag.dueDateTime) {
+        output.push(`**Due**: ${describeFlagTime(flag.dueDateTime)}`);
       }
-      if (startDateTime) {
-        output.push(`**Start**: ${new Date(startDateTime).toLocaleString()}`);
+      if (flag.startDateTime) {
+        output.push(`**Start**: ${describeFlagTime(flag.startDateTime)}`);
       }
     }
 

package/calendar/attendees.js

@@ -0,0 +1,101 @@
+/**
+ * Shared attendee builder for create-event and manage-event update (#249).
+ *
+ * Callers pass each attendee as a plain email string or as
+ * `{ email, type }` where type is `required`, `optional` or `resource`.
+ * Graph's PATCH on `attendees` replaces the whole list, so an entry
+ * without a type takes the type that address already has on the event
+ * (matched case-insensitively) and only falls back to `required` for a
+ * new address. An explicit type always wins.
+ */
+
+const ATTENDEE_TYPES = ['required', 'optional', 'resource'];
+const ATTENDEE_FIELDS = new Set(['email', 'type']);
+
+function invalid(index, reason) {
+  return new Error(`Invalid attendee at position ${index + 1}: ${reason}`);
+}
+
+/**
+ * Validate one attendee entry.
+ * @param {string|object} entry - Email string or {email, type}
+ * @param {number} index - Position in the list (for error messages)
+ * @returns {{email: string, type: (string|undefined)}}
+ * @throws {Error} 'Invalid attendee at position N: …'
+ */
+function normaliseAttendeeInput(entry, index) {
+  if (typeof entry === 'string') {
+    const email = entry.trim();
+    if (!email) throw invalid(index, 'email address is empty.');
+    return { email, type: undefined };
+  }
+
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    throw invalid(
+      index,
+      `expected an email address or an {email, type} object, got ${JSON.stringify(entry)}.`
+    );
+  }
+
+  const unknown = Object.keys(entry).find((k) => !ATTENDEE_FIELDS.has(k));
+  if (unknown) {
+    throw invalid(
+      index,
+      `unknown attendee field '${unknown}'. Use {email, type}.`
+    );
+  }
+  if (typeof entry.email !== 'string' || !entry.email.trim()) {
+    throw invalid(index, 'email address is missing or empty.');
+  }
+
+  const type = entry.type ?? undefined;
+  if (type !== undefined && !ATTENDEE_TYPES.includes(type)) {
+    throw invalid(
+      index,
+      `type '${type}' must be one of: ${ATTENDEE_TYPES.join(', ')}.`
+    );
+  }
+  return { email: entry.email.trim(), type };
+}
+
+/**
+ * Validate a whole attendee list.
+ * @param {Array} list
+ * @returns {Array<{email: string, type: (string|undefined)}>}
+ */
+function normaliseAttendees(list) {
+  if (!Array.isArray(list)) {
+    throw new Error(
+      'Invalid attendees: expected a list of email addresses or {email, type} objects.'
+    );
+  }
+  return list.map((entry, index) => normaliseAttendeeInput(entry, index));
+}
+
+/**
+ * Build the Graph `attendees` array.
+ * @param {Array} list - Email strings and/or {email, type} objects
+ * @param {Array} current - The event's current Graph attendees (update only)
+ * @returns {Array<{emailAddress: {address: string}, type: string}>}
+ */
+function buildAttendees(list, current = []) {
+  const currentTypes = new Map();
+  for (const attendee of current || []) {
+    const address = attendee?.emailAddress?.address;
+    if (typeof address === 'string' && ATTENDEE_TYPES.includes(attendee.type)) {
+      currentTypes.set(address.toLowerCase(), attendee.type);
+    }
+  }
+
+  return normaliseAttendees(list).map(({ email, type }) => ({
+    emailAddress: { address: email },
+    type: type || currentTypes.get(email.toLowerCase()) || 'required',
+  }));
+}
+
+module.exports = {
+  ATTENDEE_TYPES,
+  normaliseAttendeeInput,
+  normaliseAttendees,
+  buildAttendees,
+};

package/calendar/cancel.js

@@ -30,10 +30,11 @@ async function handleCancelEvent(args) {
     // Build API endpoint
     const endpoint = `me/events/${eventId}/cancel`;
 
-    // Request body
-    const body = {
-      comment: comment || 'Cancelled via API',
-    };
+    // Only send a comment the caller gave; no placeholder text.
+    const body = {};
+    if (typeof comment === 'string' && comment.trim() !== '') {
+      body.comment = comment;
+    }
 
     // Make API call
     await callGraphAPI(accessToken, 'POST', endpoint, body);

package/calendar/create.js

@@ -4,6 +4,7 @@
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { DEFAULT_TIMEZONE } = require('../config');
+const { buildAttendees } = require('./attendees');
 
 /**
  * Create event handler
@@ -24,6 +25,19 @@ async function handleCreateEvent(args) {
     };
   }
 
+  // Plain strings are required attendees; {email, type} sets the type (#249).
+  let graphAttendees;
+  if (attendees) {
+    try {
+      graphAttendees = buildAttendees(attendees);
+    } catch (error) {
+      return {
+        content: [{ type: 'text', text: error.message }],
+        isError: true,
+      };
+    }
+  }
+
   try {
     // Get access token
     const accessToken = await ensureAuthenticated();
@@ -42,10 +56,7 @@ async function handleCreateEvent(args) {
         dateTime: end.dateTime || end,
         timeZone: end.timeZone || DEFAULT_TIMEZONE,
       },
-      attendees: attendees?.map((email) => ({
-        emailAddress: { address: email },
-        type: 'required',
-      })),
+      attendees: graphAttendees,
       body: { contentType: 'HTML', content: body || '' },
     };
 

package/calendar/decline.js

@@ -10,7 +10,7 @@ const { ensureAuthenticated } = require('../auth');
  * @returns {object} - MCP response
  */
 async function handleDeclineEvent(args) {
-  const { eventId, comment } = args;
+  const { eventId, comment, sendResponse } = args;
 
   if (!eventId) {
     return {
@@ -30,10 +30,15 @@ async function handleDeclineEvent(args) {
     // Build API endpoint
     const endpoint = `me/events/${eventId}/decline`;
 
-    // Request body
-    const body = {
-      comment: comment || 'Declined via API',
-    };
+    // Only send what the caller gave: no placeholder comment, and Graph's
+    // own default (notify the organiser) unless sendResponse is set.
+    const body = {};
+    if (typeof comment === 'string' && comment.trim() !== '') {
+      body.comment = comment;
+    }
+    if (typeof sendResponse === 'boolean') {
+      body.sendResponse = sendResponse;
+    }
 
     // Make API call
     await callGraphAPI(accessToken, 'POST', endpoint, body);

package/calendar/index.js

@@ -7,13 +7,31 @@ const handleCreateEvent = require('./create');
 const handleCancelEvent = require('./cancel');
 const handleDeleteEvent = require('./delete');
 const handleUpdateEvent = require('./update');
+const { ATTENDEE_TYPES } = require('./attendees');
+
+// One attendee: an email string, or {email, type} (#249). schema-coerce
+// doesn't validate inside array items, so calendar/attendees.js re-checks.
+const ATTENDEE_ITEM_SCHEMA = {
+  oneOf: [
+    { type: 'string' },
+    {
+      type: 'object',
+      properties: {
+        email: { type: 'string' },
+        type: { type: 'string', enum: [...ATTENDEE_TYPES] },
+      },
+      required: ['email'],
+      additionalProperties: false,
+    },
+  ],
+};
 
 // Calendar tool definitions (consolidated: 5 → 3)
 const calendarTools = [
   {
     name: 'list-events',
     description:
-      'List calendar events for the signed-in user (read-only). By default returns upcoming events (start ≥ now). Optional `startAfter`, `startBefore` and `subject` filters find past, current or specifically-named events; supplying any of them replaces the default "now" lower bound and the filters are AND-ed together. Results are oldest first, except when the search only looks backwards (`startBefore` without `startAfter`, or `subject` alone), where they are newest first. Returns an array of events with id, subject, start/end, attendees, location, organiser, and webLink. Use `count` (default 10, max 50) to control page size. Each start/end is returned as a canonical UTC ISO-8601 instant (e.g. `2026-04-02T22:00:00.000Z`) followed by a labelled local rendering in the configured display timezone (default Australia/Melbourne; override with `OUTLOOK_DEFAULT_TIMEZONE`) — the UTC value is authoritative, so consumers never have to guess the zone.',
+      'List calendar events for the signed-in user (read-only). By default returns upcoming events (start ≥ now). Optional `startAfter`, `startBefore` and `subject` filters find past, current or specifically-named events; supplying any of them replaces the default "now" lower bound and the filters are AND-ed together. Results are oldest first, except when the search only looks backwards (`startBefore` without `startAfter`, or `subject` alone), where they are newest first. Each event shows its subject, location, start/end, a body preview and its id. Use `count` (default 10, max 100) to control page size. Each start/end is returned as a canonical UTC ISO-8601 instant (e.g. `2026-04-02T22:00:00.000Z`) followed by a labelled local rendering in the configured display timezone (default Australia/Melbourne; override with `OUTLOOK_DEFAULT_TIMEZONE`) — the UTC value is authoritative, so consumers never have to guess the zone.',
     annotations: {
       title: 'List Calendar Events',
       readOnlyHint: true,
@@ -24,7 +42,7 @@ const calendarTools = [
       properties: {
         count: {
           type: 'number',
-          description: 'Number of events to retrieve (default: 10, max: 50)',
+          description: 'Number of events to retrieve (default: 10, max: 100)',
         },
         startAfter: {
           type: 'string',
@@ -77,10 +95,9 @@ const calendarTools = [
         },
         attendees: {
           type: 'array',
-          items: {
-            type: 'string',
-          },
-          description: 'List of attendee email addresses',
+          items: ATTENDEE_ITEM_SCHEMA,
+          description:
+            "Attendees: email address strings (required attendees) or {email, type} objects, where type is 'required', 'optional' or 'resource' (a room or equipment)",
         },
         body: {
           type: 'string',
@@ -95,7 +112,7 @@ const calendarTools = [
   {
     name: 'manage-event',
     description:
-      "Manage an existing calendar event (destructive: covers update/decline/cancel/delete — use dryRun where supported to preview). action=`update` edits fields in place via PATCH (subject, start, end, attendees, body, location, isOnlineMeeting, sensitivity, showAs, importance, categories, reminderMinutesBeforeStart) — only fields you pass are changed; pass `dryRun: true` to preview the PATCH payload. action=`decline` declines an invitation (optional `comment`). action=`cancel` cancels an event you organised and notifies attendees. action=`delete` permanently removes the event. Returns the updated event on update; status confirmation otherwise. Note: there is no `accept` action — accept invitations in the Outlook UI (Graph's accept verb is unreliable across personal/M365).",
+      "Manage an existing calendar event (destructive: covers update/decline/cancel/delete — use dryRun where supported to preview). action=`update` edits fields in place via PATCH (subject, start, end, attendees, body, location, isOnlineMeeting, sensitivity, showAs, importance, categories, reminderMinutesBeforeStart) — only fields you pass are changed; pass `dryRun: true` to preview the PATCH payload. action=`decline` declines an invitation (optional `comment`; `sendResponse: false` declines without notifying the organiser). action=`cancel` cancels an event you organised and notifies attendees. action=`delete` removes the event from your calendar (Graph doesn't document a guaranteed recovery path, so don't count on restoring it); deleting a meeting you organised that has attendees still emails them a cancellation, so use `cancel` (with an optional `comment`) when you want to control that message. Returns the updated event on update; status confirmation otherwise. Note: there is no `accept` action — accept invitations in the Outlook UI (Graph's accept verb is unreliable across personal/M365).",
     annotations: {
       title: 'Manage Calendar Event',
       readOnlyHint: false,
@@ -121,7 +138,13 @@ const calendarTools = [
         },
         comment: {
           type: 'string',
-          description: 'Optional comment for declining or cancelling the event',
+          description:
+            'Message sent with a decline or cancel (optional; omitted if not given)',
+        },
+        sendResponse: {
+          type: 'boolean',
+          description:
+            'Send the decline to the organiser (action=decline only; default true). Pass false to decline without notifying the organiser.',
         },
         subject: {
           type: 'string',
@@ -161,9 +184,9 @@ const calendarTools = [
         },
         attendees: {
           type: 'array',
-          items: { type: 'string' },
+          items: ATTENDEE_ITEM_SCHEMA,
           description:
-            'Full replacement attendee list — pass complete desired list, or [] to clear (action=update only)',
+            "Full replacement attendee list — pass the complete desired list, or [] to clear (action=update only). Each entry is an email address string or an {email, type} object (type 'required', 'optional' or 'resource'). A string, or an object without a type, keeps the type that address already has on the event (new addresses are required); an explicit type always wins.",
         },
         body: {
           type: 'string',

package/calendar/list.js

@@ -8,13 +8,8 @@ const {
   escapeODataString,
   buildODataFilter,
 } = require('../utils/odata-helpers');
+const { parseIsoInstant } = require('../utils/datetime');
 
-// An ISO 8601 instant with an explicit zone: `Z` or a ±hh:mm offset. A
-// zone-less value would be read in the server's local timezone by Date.parse,
-// so results would differ between machines; date-only values are rejected for
-// the same reason.
-const ISO_INSTANT =
-  /^(\d{4})-(\d{2})-(\d{2})T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:\d{2})$/;
 const MAX_SUBJECT_LENGTH = 255;
 
 /**
@@ -31,18 +26,8 @@ class ListEventsArgumentError extends Error {}
  * does not enforce JSON Schema `format`, so we enforce here at runtime.
  */
 function toUtcIsoDateTime(value, paramName) {
-  const s = typeof value === 'string' ? value.trim() : '';
-  const m = ISO_INSTANT.exec(s);
-  const parsed = m ? Date.parse(s) : NaN;
-  const valid =
-    m &&
-    !Number.isNaN(parsed) &&
-    Number(m[1]) >= 1900 &&
-    // Reject dates Date.parse would roll over, e.g. 2026-02-30 -> 2 March.
-    new Date(
-      Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]))
-    ).getUTCDate() === Number(m[3]);
-  if (!valid) {
+  const parsed = parseIsoInstant(value);
+  if (Number.isNaN(parsed)) {
     throw new ListEventsArgumentError(
       `Invalid ${paramName}: expected an ISO 8601 datetime with "Z" or a ±hh:mm offset, e.g. "2026-01-01T00:00:00Z" (got ${JSON.stringify(String(value).slice(0, 40))}).`
     );
@@ -224,7 +209,13 @@ function formatLocal(utcIso, tz) {
  * @returns {object} - MCP response
  */
 async function handleListEvents(args) {
-  const count = Math.min(args.count || 10, config.MAX_RESULT_COUNT);
+  // Whole number in 1..MAX_RESULT_COUNT: Graph rejects $top below 1 or
+  // fractional, and the schema promises the cap.
+  const requested = args.count == null ? 10 : Math.floor(args.count);
+  const count = Math.min(
+    Math.max(Number.isFinite(requested) ? requested : 10, 1),
+    config.MAX_RESULT_COUNT
+  );
 
   // Validate arguments before authenticating, so a bad argument is reported
   // as such (and never reaches the network).