@littlebearapps/outlook-assistant 3.11.2 → 3.12.1

package/auth/tools.js

@@ -6,7 +6,12 @@ const { getAuthErrorHints } = require('./auth-errors');
 const fs = require('fs');
 const path = require('path');
 const tokenManager = require('./token-manager');
-const { initiateDeviceCodeFlow, pollForToken } = require('./device-code');
+const {
+  initiateDeviceCodeFlow,
+  pollForToken,
+  isScopeConsentError,
+  isConsentRequiredError,
+} = require('./device-code');
 
 // Path for persisting device code state across MCP server restarts
 const DEVICE_CODE_STATE_PATH = path.join(
@@ -20,6 +25,49 @@ function setToolCount(count) {
   _toolCount = count;
 }
 
+/**
+ * Scopes recorded as granted in a stored token object. Prefers the
+ * `granted_scopes` array; falls back to the token response's `scope` string
+ * (token files written before granted_scopes existed). Full-URI forms such as
+ * `https://graph.microsoft.com/Mail.Read` are reduced to the bare scope name.
+ * @param {object|null} tokens
+ * @returns {string[]|null} - null when no token is stored
+ */
+function grantedScopesOf(tokens) {
+  if (!tokens) return null;
+  let raw = [];
+  if (Array.isArray(tokens.granted_scopes) && tokens.granted_scopes.length) {
+    raw = tokens.granted_scopes;
+  } else if (typeof tokens.scope === 'string') {
+    raw = tokens.scope.split(' ');
+  }
+  return raw.map((scope) => String(scope).split('/').pop()).filter(Boolean);
+}
+
+/**
+ * Human-readable shared-mailbox status for `auth about`.
+ * @param {string[]|null} granted - Granted scopes, or null when signed out
+ * @returns {string}
+ */
+function describeSharedMailboxStatus(granted) {
+  if (config.SHARED_MAILBOX_MODE === 'off' || !config.SHARED_SCOPES.length) {
+    return 'Disabled (opt-in, work/school only: set `OUTLOOK_SHARED_MAILBOX=read` or `=true`, restart, then `auth action=authenticate force=true`)';
+  }
+  const lowerGranted = (granted || []).map((s) => s.toLowerCase());
+  const parts = config.SHARED_SCOPES.map(
+    (scope) =>
+      `${scope} ${lowerGranted.includes(scope.toLowerCase()) ? 'granted' : 'not granted'}`
+  );
+  let status = `Enabled (${config.SHARED_MAILBOX_MODE}): ${parts.join(', ')}`;
+  if (!granted) {
+    status += ' (not signed in)';
+  } else if (parts.some((p) => p.endsWith('not granted'))) {
+    status +=
+      ' (re-authenticate with `auth action=authenticate force=true`; personal accounts cannot be granted these)';
+  }
+  return status;
+}
+
 /**
  * About tool handler
  * @returns {object} - MCP response
@@ -43,6 +91,17 @@ async function handleAbout() {
   // GET /me round-trip when a valid token is available; degrades
   // gracefully when not authenticated.
   let identity = 'Not authenticated (run `auth action=authenticate`)';
+  // Granted scopes come from the stored token file (scope names only — the
+  // tokens themselves are never surfaced).
+  let granted = null;
+  try {
+    const { tokenStorage } = require('./index');
+    if (tokenStorage && typeof tokenStorage.getTokens === 'function') {
+      granted = grantedScopesOf(await tokenStorage.getTokens());
+    }
+  } catch (_e) {
+    // Leave granted as unknown
+  }
   try {
     const { ensureAuthenticated } = require('./index');
     const { callGraphAPI } = require('../utils/graph-api');
@@ -70,8 +129,10 @@ async function handleAbout() {
     `| Rate Limit | ${rateLimit} |`,
     `| Recipient Allowlist | ${allowlist} |`,
     `| Scopes | ${scopes.length} configured |`,
+    `| Shared mailboxes | ${describeSharedMailboxStatus(granted)} |`,
     ``,
-    `**Scopes**: ${scopes.join(', ')}`,
+    `**Configured scopes**: ${scopes.join(', ')}`,
+    `**Granted scopes**: ${granted ? granted.filter((s) => s !== 'offline_access').join(', ') || 'none recorded' : 'not signed in'}`,
   ];
 
   // F-1 / F-48: warn when no safety belts are wired up. AI-assisted
@@ -209,6 +270,23 @@ async function handleDeviceCodeAuth() {
   }
 
   console.error('[AUTH] Starting device code flow...');
+  // Attempt the configured scope set (base, plus `.Shared` when
+  // OUTLOOK_SHARED_MAILBOX opts in). If the account can't consent to
+  // `.Shared`, handleDeviceCodeComplete re-issues with base scopes.
+  return initiateDeviceCode(config.AUTH_CONFIG.scopes, 'full');
+}
+
+/**
+ * Shared helper: request a device code for a given scope set, persist the
+ * pending state (tagging which scope set was used so the completion step can
+ * decide whether a fallback is still available), and build the MCP response.
+ * @param {string[]} scopes - OAuth scopes to request
+ * @param {'full'|'base'} scopesUsed - Label recording which scope set was used
+ * @param {string} [prefix] - Optional leading line (used for the fallback case)
+ * @returns {Promise<object>} - MCP response
+ */
+async function initiateDeviceCode(scopes, scopesUsed, prefix) {
+  const clientId = config.AUTH_CONFIG.clientId;
 
   // #213 — initiation can throw (blocked network egress in a sandboxed
   // connector, AADSTS9002331 audience mismatch, invalid_client, non-JSON
@@ -218,11 +296,25 @@ async function handleDeviceCodeAuth() {
   // (handleDeviceCodeComplete) already has, and surface actionable hints.
   let response;
   try {
-    response = await initiateDeviceCodeFlow(
-      clientId,
-      config.AUTH_CONFIG.scopes
-    );
+    response = await initiateDeviceCodeFlow(clientId, scopes);
   } catch (error) {
+    // The `.Shared` scopes can also be rejected when the code is requested
+    // (before sign-in). Same single fallback as at completion.
+    if (
+      config.SHARED_SCOPES.length > 0 &&
+      scopesUsed === 'full' &&
+      !isConsentRequiredError(error) &&
+      isScopeConsentError(error)
+    ) {
+      console.error(
+        '[AUTH] Shared-mailbox scopes rejected at device-code request; retrying with base scopes.'
+      );
+      return initiateDeviceCode(
+        config.AUTH_CONFIG.fallbackScopes,
+        'base',
+        "Your account doesn't support shared-mailbox access; signing in with the standard scopes instead."
+      );
+    }
     return buildDeviceCodeErrorResponse(error);
   }
 
@@ -232,24 +324,31 @@ async function handleDeviceCodeAuth() {
     interval: response.interval,
     expiresIn: response.expiresIn,
     expiresAt: Date.now() + response.expiresIn * 1000,
+    scopesUsed,
   };
   saveDeviceCodeState(pendingDeviceCode);
 
   console.error(
-    `[AUTH] Device code: ${response.userCode}, expires in ${response.expiresIn}s`
+    `[AUTH] Device code (${scopesUsed} scopes): ${response.userCode}, expires in ${response.expiresIn}s`
+  );
+
+  const lines = [];
+  if (prefix) {
+    lines.push(prefix, '');
+  }
+  lines.push(
+    `## Device Code Authentication\n`,
+    `Visit: **${response.verificationUri}**`,
+    `Enter code: **${response.userCode}**\n`,
+    `The code expires in ${Math.floor(response.expiresIn / 60)} minutes.\n`,
+    `After entering the code and signing in, call this tool again with \`action=device-code-complete\` to finish authentication.`
   );
 
   return {
     content: [
       {
         type: 'text',
-        text: [
-          `## Device Code Authentication\n`,
-          `Visit: **${response.verificationUri}**`,
-          `Enter code: **${response.userCode}**\n`,
-          `The code expires in ${Math.floor(response.expiresIn / 60)} minutes.\n`,
-          `After entering the code and signing in, call this tool again with \`action=device-code-complete\` to finish authentication.`,
-        ].join('\n'),
+        text: lines.join('\n'),
       },
     ],
   };
@@ -332,6 +431,14 @@ async function handleDeviceCodeComplete() {
   }
 
   const clientId = config.AUTH_CONFIG.clientId;
+  // Capture which scope set this pending flow attempted, before any mutation.
+  const scopesUsed = pendingDeviceCode.scopesUsed || 'full';
+  // The scopes we attempted — used as the granted_scopes fallback when the
+  // token response omits `scope`.
+  const attemptedScopes =
+    scopesUsed === 'base'
+      ? config.AUTH_CONFIG.fallbackScopes
+      : config.AUTH_CONFIG.scopes;
 
   try {
     console.error('[AUTH] Polling for device code completion...');
@@ -355,12 +462,20 @@ async function handleDeviceCodeComplete() {
       tokenEndpoint: config.AUTH_CONFIG.tokenEndpoint,
     });
 
+    // Persist the GRANTED scopes so token refresh re-requests exactly what was
+    // granted (not the full configured set) — otherwise a base-only fallback
+    // would re-request `.Shared` on refresh ~1h later and log the user out.
+    const grantedScopes = tokenResponse.scope
+      ? tokenResponse.scope.split(' ').filter(Boolean)
+      : attemptedScopes;
+
     tokenStorage.tokens = {
       access_token: tokenResponse.access_token,
       refresh_token: tokenResponse.refresh_token,
       expires_in: tokenResponse.expires_in,
       expires_at: Date.now() + tokenResponse.expires_in * 1000,
       scope: tokenResponse.scope,
+      granted_scopes: grantedScopes,
       token_type: tokenResponse.token_type,
       auth_method: 'device-code',
     };
@@ -377,8 +492,75 @@ async function handleDeviceCodeComplete() {
       ],
     };
   } catch (error) {
+    // Scope-consent rejection while attempting the FULL set → re-issue with
+    // base scopes. This is the personal-account path: one extra device code.
+    // Only meaningful when shared-mailbox support is on: with the flag off the
+    // attempted set already IS the base set, so there is nothing to drop.
+    // Consent-required (AADSTS65001) is checked first: it is remediable and
+    // must surface below, never trigger a silent downgrade.
+    if (
+      config.SHARED_SCOPES.length > 0 &&
+      scopesUsed === 'full' &&
+      !isConsentRequiredError(error) &&
+      isScopeConsentError(error)
+    ) {
+      console.error(
+        '[AUTH] Shared-mailbox scopes rejected; falling back to base scopes.'
+      );
+      // Do NOT clear pendingDeviceCode — initiateDeviceCode replaces it.
+      try {
+        const fallbackResponse = await initiateDeviceCode(
+          config.AUTH_CONFIG.fallbackScopes,
+          'base',
+          "Your account doesn't support shared-mailbox access; enter this new code to finish signing in."
+        );
+        // initiateDeviceCode reports its own failures as { isError: true }
+        // instead of throwing. Clear the rejected full-scope pending state so
+        // a later completion attempt doesn't retry it.
+        if (fallbackResponse && fallbackResponse.isError) {
+          pendingDeviceCode = null;
+          saveDeviceCodeState(null);
+        }
+        return fallbackResponse;
+      } catch (reissueError) {
+        pendingDeviceCode = null;
+        saveDeviceCodeState(null);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Authentication failed: ${reissueError.message}`,
+            },
+          ],
+        };
+      }
+    }
+
     pendingDeviceCode = null;
     saveDeviceCodeState(null);
+
+    // Consent required (AADSTS65001) — remediable, so surface it instead of
+    // silently downgrading to base scopes (which would strip shared-mailbox
+    // access for every future refresh).
+    // Only when the shared scopes were requested — otherwise the generic
+    // path below (with its AADSTS hint table) is unchanged.
+    if (config.SHARED_SCOPES.length > 0 && isConsentRequiredError(error)) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: [
+              'Authentication failed: consent was not granted (AADSTS65001).',
+              '',
+              `An administrator may need to grant consent for the shared-mailbox scopes (${config.SHARED_SCOPES.join(', ')}), or re-run \`auth action=authenticate\` and approve every requested permission.`,
+              'If your organisation will not consent to them, unset OUTLOOK_SHARED_MAILBOX and restart the server to sign in with the standard scopes.',
+              'No scopes were changed — your configured capability is unchanged.',
+            ].join('\n'),
+          },
+        ],
+      };
+    }
+
     return {
       content: [
         {

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 upcoming calendar events for the signed-in user (read-only). 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; this tool does not filter — use the Outlook UI or specific date ranges via Graph for filtered queries. 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,25 @@ 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',
+          format: 'date-time',
+          description:
+            'Optional ISO 8601 datetime with `Z` or a ±hh:mm offset (required). Only return events whose start is on or after this time. Replaces the default "now" lower bound when supplied. Example: "2026-01-01T00:00:00Z" or "2026-01-01T09:00:00+10:00".',
+        },
+        startBefore: {
+          type: 'string',
+          format: 'date-time',
+          description:
+            'Optional ISO 8601 datetime with `Z` or a ±hh:mm offset (required). Only return events whose start is strictly before this time. Combine with `startAfter` to bound a window; on its own, results are newest first. Example: "2026-02-01T00:00:00Z".',
+        },
+        subject: {
+          type: 'string',
+          description:
+            'Optional substring (max 255 characters) to match against the event subject, case-insensitive (Graph `contains()`). Useful for finding past or current events by name; on its own, results are newest first.',
+          maxLength: 255,
         },
       },
       additionalProperties: false,
@@ -59,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',
@@ -77,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,
@@ -103,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',
@@ -143,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',