@littlebearapps/outlook-assistant 3.13.0 → 3.14.1

package/email/index.js

@@ -27,20 +27,16 @@ const handleDraft = require('./draft');
 
 // Import flag handlers from advanced module
 const { handleSetMessageFlag, handleClearMessageFlag } = require('../advanced');
+const { toolMetadata } = require('../utils/risk-classes');
+const { toolError } = require('../utils/tool-error');
 
 // Consolidated email tool definitions (17 → 6)
 const emailTools = [
   {
     name: 'search-emails',
     description:
-      'Search, list, delta-sync, or thread-group emails — six modes selected by parameters (read-only). With no params: lists recent emails in `folder` (default `inbox`). With `query`/`from`/`to`/`subject`/date filters: full search (combines via OData filter). With `searchExpression` (deprecated alias `kqlQuery`): a raw Microsoft Graph `$search` expression for advanced server-side search. With `deltaMode: true`: returns current state plus a `deltaToken`; pass the token back on the next call for incremental changes only — ideal for inbox monitoring. With `groupByConversation: true`: returns conversation threads. With `conversationId`: returns all messages in a single thread. With `internetMessageId`: looks up a message by its RFC Message-ID header. Set `sharedMailbox` (or alias `email`) to search a shared/delegated mailbox instead of the signed-in account — works with custom folders and nested folder paths. Personal Outlook.com accounts have limited `$search` support — this tool falls back through OData filters / boolean filters / recent listing automatically, but structured filters (`from`/`subject`/`receivedAfter`/`hasAttachments`/`unreadOnly`) return cleaner results. Returns paged messages with id/subject/from/receivedDateTime/preview by default; use `outputVerbosity` to expand.',
-    annotations: {
-      title: 'Search Emails',
-      readOnlyHint: true,
-      // openWorldHint: output includes email content authored by external
-      // senders (bodies/previews/threads) — may contain prompt-injection. (#92)
-      openWorldHint: true,
-    },
+      'Search, list, delta-sync or thread-group emails (read-only); parameters set the mode. No params: recent emails in `folder` (default `inbox`). `query`/`from`/`to`/`subject`/date filters: search, combined as an OData filter. `searchExpression` (deprecated alias `kqlQuery`): a raw Graph `$search` expression. `deltaMode: true`: current state plus a `deltaToken` to pass back next time for changes only. `groupByConversation: true`: conversation threads. `conversationId`: every message in one thread. `internetMessageId`: the message with that RFC Message-ID. `sharedMailbox` (alias `email`) searches a shared/delegated mailbox, custom folders and nested paths included. Personal Outlook.com accounts have limited `$search`, so the tool falls back to OData filters and a recent listing automatically; structured filters (`from`/`subject`/`receivedAfter`/`hasAttachments`/`unreadOnly`) give cleaner results there. Returns up to `count` messages (id/subject/from/receivedDateTime/preview); `outputVerbosity` expands them.',
+    ...toolMetadata('search-emails', 'Search Emails'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -63,7 +59,7 @@ const emailTools = [
         groupByConversation: {
           type: 'boolean',
           description:
-            'List conversations (threads) grouped by conversationId instead of individual emails. Honors `sharedMailbox`/`email` (and custom `folder` paths) to group within a shared/delegated mailbox.',
+            'List conversations (threads) grouped by conversationId, not individual emails. Honors `sharedMailbox`/`email` (and custom `folder` paths) to group within a shared/delegated mailbox.',
         },
         // Search/list params
         query: {
@@ -79,7 +75,7 @@ const emailTools = [
         kqlQuery: {
           type: 'string',
           description:
-            'DEPRECATED alias for `searchExpression` (this was never full KQL — it is a Graph `$search` expression). Prefer `searchExpression`.',
+            'DEPRECATED alias for `searchExpression` (this was never full KQL — it is a Graph `$search` expression).',
         },
         folder: {
           type: 'string',
@@ -89,7 +85,7 @@ const emailTools = [
         sharedMailbox: {
           type: 'string',
           description:
-            'Email address of a shared/delegated mailbox to search instead of the signed-in account. Combine with `folder` (incl. custom subfolders/paths) or `searchAllFolders`. Work/school only; needs the server opt-in setting OUTLOOK_SHARED_MAILBOX (otherwise the call is refused with setup guidance).',
+            'Email address of a shared/delegated mailbox to search (default: the signed-in account). Combine with `folder` (incl. custom subfolders/paths) or `searchAllFolders`. Work/school only; needs the server opt-in setting OUTLOOK_SHARED_MAILBOX (otherwise the call is refused with setup guidance).',
         },
         email: {
           type: 'string',
@@ -131,7 +127,7 @@ const emailTools = [
         count: {
           type: 'number',
           description:
-            'Number of results (list default: 25, search default: 10, max: 50)',
+            'Number of results (list default: 25, search default: 10, max: 50). There is no page cursor: when the result says more emails are available, raise `count` or narrow `receivedAfter`/`receivedBefore`.',
         },
         outputVerbosity: {
           type: 'string',
@@ -200,13 +196,8 @@ const emailTools = [
   {
     name: 'read-email',
     description:
-      'Read a single email by id (read-only). Default: returns the full message body (HTML stripped to text by default), subject, from/to/cc, receivedDateTime, conversationId, attachments metadata, and webLink as Markdown. With `headersMode: true`: returns RFC-822 forensic headers instead (DKIM, SPF, DMARC, Received chain, Message-ID, Authentication-Results) — pair with `importantOnly: true` for the security-relevant subset, `groupByType: true` for category-bucketed view, or `raw: true` for JSON instead of Markdown. With `includeHeaders: true` (non-headers-mode): adds basic headers alongside body. Use `outputVerbosity` (minimal/standard/full) to control field count. **If the id came from a shared/delegated mailbox (e.g. via `search-emails` or `access-shared-mailbox` with `sharedMailbox` set), you MUST pass the same `sharedMailbox` (or alias `email`) here** — message IDs are mailbox-scoped, and reading a shared-mailbox id without it fails with 404 ErrorInvalidMailboxItemId.',
-    annotations: {
-      title: 'Read Email',
-      readOnlyHint: true,
-      // openWorldHint: returns full message body from external senders. (#92)
-      openWorldHint: true,
-    },
+      'Read a single email by id (read-only). Returns subject, from/to/cc, date and the body as Markdown (HTML stripped to text): up to 2,000 characters by default, up to 40,000 with `outputVerbosity: full`; a cut body ends with a note on how to get the rest. With `headersMode: true`: returns RFC-822 forensic headers in place of the body (DKIM, SPF, DMARC, Received chain, Message-ID, Authentication-Results) — `importantOnly: true` for the security-relevant subset, `groupByType: true` for a category-bucketed view, `raw: true` for JSON. With `includeHeaders: true` (non-headers-mode): adds basic headers alongside the body. **If the id came from a shared/delegated mailbox (e.g. via `search-emails` or `access-shared-mailbox` with `sharedMailbox` set), you MUST pass the same `sharedMailbox` (or alias `email`) here** — message IDs are mailbox-scoped, and reading a shared-mailbox id without it fails with 404 ErrorInvalidMailboxItemId.',
+    ...toolMetadata('read-email', 'Read Email'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -226,7 +217,7 @@ const emailTools = [
         headersMode: {
           type: 'boolean',
           description:
-            'Return forensic headers instead of email content (default: false)',
+            'Return forensic headers in place of the email content (default: false)',
         },
         includeHeaders: {
           type: 'boolean',
@@ -236,7 +227,8 @@ const emailTools = [
         outputVerbosity: {
           type: 'string',
           enum: ['minimal', 'standard', 'full'],
-          description: 'Output detail level (default: standard)',
+          description:
+            'Output detail level (default: standard). minimal: body preview only; standard: body up to 2,000 characters; full: adds IDs, body up to 40,000 characters. For a longer body, export it with `export` target=message.',
         },
         // Headers mode params
         groupByType: {
@@ -252,7 +244,7 @@ const emailTools = [
         raw: {
           type: 'boolean',
           description:
-            'Return raw JSON instead of Markdown (headersMode only, default: false)',
+            'Return the headers as raw JSON, not Markdown (headersMode only, default: false)',
         },
       },
       additionalProperties: false,
@@ -268,14 +260,8 @@ const emailTools = [
   {
     name: 'send-email',
     description:
-      'Compose and send an email immediately (destructive: sends external comms). Returns a confirmation with the saved-message id. Safety controls: `dryRun: true` returns the composed message for review without sending; `checkRecipients: true` runs `get-mail-tips` first to flag out-of-office / mailbox-full / delivery-restricted / external recipients; combine both for a full pre-send review. Subject to session rate limits (`OUTLOOK_MAX_EMAILS_PER_SESSION` env) and recipient allowlist (`OUTLOOK_ALLOWED_RECIPIENTS` env) when configured — calls outside the allowlist fail before any Graph request. For multi-step compose/review workflows prefer `draft` (action=`create` → `update` → `send`) since drafts can be inspected in Outlook before sending. Comma-separated recipient strings or arrays both accepted.',
-    annotations: {
-      title: 'Send Email',
-      readOnlyHint: false,
-      destructiveHint: true,
-      idempotentHint: false,
-      openWorldHint: true,
-    },
+      'Compose and send an email immediately (destructive: sends external comms). Returns a confirmation. Safety controls: `dryRun: true` returns the composed message for review without sending; `checkRecipients: true` runs `get-mail-tips` first and returns its warnings. If the tips show an out-of-office reply, a full mailbox, a delivery restriction or external recipients, the send is refused until repeated with `acknowledgeWarnings: true`. Personal Outlook.com accounts return no tips, and no warnings is not proof of delivery. Subject to the session limit (`OUTLOOK_MAX_SEND_EMAIL_PER_SESSION`, else `OUTLOOK_MAX_EMAILS_PER_SESSION`; 0 refuses every send) and recipient allowlist (`OUTLOOK_ALLOWED_RECIPIENTS`) when configured; both refuse before any Graph request. For a review-before-send workflow, use `draft` (action=`create` → `update` → `send`); a draft can be checked in Outlook before it goes. Comma-separated recipient strings or arrays both accepted.',
+    ...toolMetadata('send-email', 'Send Email'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -316,7 +302,13 @@ const emailTools = [
         checkRecipients: {
           type: 'boolean',
           description:
-            'Check recipients for out-of-office, mailbox full, delivery restrictions before sending (default: false). Combine with dryRun=true for pre-send review.',
+            'Check recipients with mail tips before sending (default: false). Out-of-office, mailbox full, delivery restrictions or external recipients refuse the send unless acknowledgeWarnings=true. Combine with dryRun=true for pre-send review.',
+        },
+        acknowledgeWarnings: {
+          type: 'boolean',
+          default: false,
+          description:
+            'Send even though checkRecipients flagged an out-of-office reply, a full mailbox, a delivery restriction or external recipients (default: false). Without it those warnings refuse the send. Pass only after the user has seen the warnings. No effect without checkRecipients.',
         },
       },
       additionalProperties: false,
@@ -327,14 +319,8 @@ const emailTools = [
   {
     name: 'draft',
     description:
-      'Full draft lifecycle for review-before-send workflows (destructive: covers `send` and `delete`). action=`create` saves a new draft in the Drafts folder and returns its id (use `dryRun: true` to preview without saving; `checkRecipients: true` runs mail-tips first). action=`update` patches an existing draft by `id` (only fields passed are changed). action=`send` dispatches an existing draft — shares the rate limit with `send-email`. action=`delete` deletes a draft: it skips Deleted Items and goes to Recoverable Items (restorable for a limited time, depending on your account, via "Recover deleted items" in Outlook). update/send/delete refuse any `id` that is not an unsent draft (received or sent messages are never changed). action=`reply`/`reply-all` creates a reply draft from a message `id` (use `comment` to prepend text — mutually exclusive with `body`). action=`forward` creates a forward draft (requires `id` and `to`). Recipient allowlist applies to create/update/forward. Returns the draft object on create/update/reply/forward; status confirmation on send/delete.',
-    annotations: {
-      title: 'Draft Operations',
-      readOnlyHint: false,
-      destructiveHint: true,
-      idempotentHint: false,
-      openWorldHint: true,
-    },
+      "Draft lifecycle for review-before-send workflows (destructive: covers `send` and `delete`). action=`create` saves a new draft and returns its id (`dryRun: true` previews without saving; `checkRecipients: true` runs mail-tips first). action=`update` patches a draft by `id` (only fields passed change). action=`send` sends a draft and counts against the `send-email` session limit (0 refuses every send). action=`delete` moves a draft to Recoverable Items (restorable for a limited time). update/send/delete refuse any `id` that is not an unsent draft. action=`reply`/`reply-all` creates a reply draft from a message `id` (`comment` prepends text; not with `body`). action=`forward` creates a forward draft (needs `id` and `to`). The recipient allowlist (OUTLOOK_ALLOWED_RECIPIENTS) applies to create/update/forward, to the draft's current to/cc/bcc on send, and to reply/reply-all, whose draft is deleted if a recipient is not allowed. Returns the draft on create/update/reply/forward; a status on send/delete.",
+    ...toolMetadata('draft', 'Draft Operations'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -390,7 +376,7 @@ const emailTools = [
         dryRun: {
           type: 'boolean',
           description:
-            'Preview draft without saving (action=create only, default: false)',
+            'Preview only (action=create): shows the draft without saving it. Other actions refuse dryRun and change nothing. Default false.',
         },
         checkRecipients: {
           type: 'boolean',
@@ -406,14 +392,8 @@ const emailTools = [
   {
     name: 'update-email',
     description:
-      'Update message state without modifying content (idempotent — safe to retry). action=`mark-read`/`mark-unread` toggles the `isRead` flag on a single message by `id`. action=`flag` sets a follow-up flag with optional `dueDateTime`/`startDateTime` (ISO 8601 with a time: a value with `Z` or a ±hh:mm offset is kept as that exact instant; a value without one is read in the configured default timezone (OUTLOOK_DEFAULT_TIMEZONE); date-only or unparseable values are refused before any change). With only `dueDateTime`, the start defaults to 09:00 on the due date in the default timezone, or to the due time if that is earlier. action=`unflag` clears the flag. action=`complete` marks the flag as done. Flag/unflag/complete accept either `id` (single) or `ids` (batch array) — messages in a batch are updated one at a time (one PATCH each, not Graph `$batch`). Pass `sharedMailbox` (or alias `email`) to update messages in a shared/delegated mailbox instead of the signed-in account (requires Mail.ReadWrite.Shared + delegate access). Returns status confirmation per message.',
-    annotations: {
-      title: 'Update Email',
-      readOnlyHint: false,
-      destructiveHint: false,
-      idempotentHint: true,
-      openWorldHint: false,
-    },
+      'Update message state without modifying content (idempotent — safe to retry). action=`mark-read`/`mark-unread` sets `isRead` on a single message by `id`. action=`flag` sets a follow-up flag with optional `dueDateTime`/`startDateTime`: ISO 8601 with a time, kept as that exact instant when it has `Z` or a ±hh:mm offset and read in OUTLOOK_DEFAULT_TIMEZONE when it has none; date-only or unparseable values are refused before any change. With only `dueDateTime`, the start is 09:00 on the due date, or the due time if earlier. action=`unflag` clears the flag; action=`complete` marks it done. Flag/unflag/complete take `id` (single) or `ids` (batch, updated one at a time: one PATCH each, not Graph `$batch`). `sharedMailbox` (alias `email`) updates messages in a shared/delegated mailbox (default: the signed-in account; needs Mail.ReadWrite.Shared and delegate access). Returns a status per message.',
+    ...toolMetadata('update-email', 'Update Email'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -425,7 +405,7 @@ const emailTools = [
         id: {
           type: 'string',
           description:
-            'Single message ID (required for mark-read/mark-unread, or use instead of ids for flag actions)',
+            'Single message ID (required for mark-read/mark-unread; flag actions take `id` or `ids`)',
         },
         ids: {
           type: 'array',
@@ -447,7 +427,7 @@ const emailTools = [
         sharedMailbox: {
           type: 'string',
           description:
-            'Email address of a shared/delegated mailbox whose message(s) to update instead of the signed-in account. Requires delegate access + Mail.ReadWrite.Shared. Work/school only; needs the server opt-in setting OUTLOOK_SHARED_MAILBOX (otherwise the call is refused with setup guidance).',
+            'Email address of the shared/delegated mailbox whose message(s) to update (default: the signed-in account). Requires delegate access + Mail.ReadWrite.Shared. Work/school only; needs the server opt-in setting OUTLOOK_SHARED_MAILBOX (otherwise the call is refused with setup guidance).',
         },
         email: {
           type: 'string',
@@ -491,29 +471,17 @@ const emailTools = [
             sharedMailbox,
           });
         default:
-          return {
-            content: [
-              {
-                type: 'text',
-                text: "Invalid action. Use 'mark-read', 'mark-unread', 'flag', 'unflag', or 'complete'.",
-              },
-            ],
-          };
+          return toolError(
+            "Invalid action. Use 'mark-read', 'mark-unread', 'flag', 'unflag', or 'complete'."
+          );
       }
     },
   },
   {
     name: 'attachments',
     description:
-      'Inspect or retrieve email attachments. action=`list` (default) returns metadata for all attachments on `messageId` (id, name, contentType, size, isInline) — read-only. action=`view` returns inline content for text/JSON/XML attachments via `attachmentId`; binary types require download. action=`download` saves the attachment to disk at `outputDir` (default system tmpdir, auto-created) and returns the saved file path. `messageId` is required for all actions; `attachmentId` is required for view/download. If `messageId` came from a shared/delegated mailbox, pass the same `sharedMailbox` (or alias `email`) — attachment IDs are scoped to the message and fail under /me otherwise. Use `outputVerbosity` to control list field count.',
-    annotations: {
-      title: 'Attachments',
-      readOnlyHint: false,
-      destructiveHint: false,
-      // openWorldHint: action=view returns attachment content supplied by
-      // external senders. (#92)
-      openWorldHint: true,
-    },
+      'Inspect or retrieve email attachments. action=`list` (default) returns metadata for all attachments on `messageId` (id, name, contentType, size, isInline) — read-only. action=`view` returns inline content for text/JSON/XML attachments via `attachmentId`; binary types require download. action=`download` saves the attachment under a new, unique name in `outputDir` (default system temp directory, auto-created; must be inside the temp directory, ~/Downloads, ~/Documents or OUTLOOK_EXPORT_DIR) and returns the saved file path. `messageId` is required for all actions; `attachmentId` is required for view/download. If `messageId` came from a shared/delegated mailbox, pass the same `sharedMailbox` (or alias `email`) — attachment IDs are scoped to the message and fail under /me otherwise. Use `outputVerbosity` to control list field count.',
+    ...toolMetadata('attachments', 'Attachments'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -542,7 +510,7 @@ const emailTools = [
         outputDir: {
           type: 'string',
           description:
-            'Directory to save file (action=download, default: system tmpdir). Auto-created if missing.',
+            'Absolute directory (or ~/…) to save the file in (action=download, default: system temp directory). Auto-created if missing. Must be inside the system temp directory, ~/Downloads, ~/Documents or OUTLOOK_EXPORT_DIR, with no dot-prefixed folder names.',
         },
         savePath: {
           type: 'string',
@@ -563,29 +531,17 @@ const emailTools = [
         case 'list':
           return handleListAttachments(args);
         default:
-          return {
-            content: [
-              {
-                type: 'text',
-                text: `Unknown action '${action}'. Valid actions: list, view, download.`,
-              },
-            ],
-          };
+          return toolError(
+            `Unknown action '${action}'. Valid actions: list, view, download.`
+          );
       }
     },
   },
   {
     name: 'export',
     description:
-      'Export emails to file formats for archival, forensics, or programmatic processing. target=`message` (default) exports a single email by `id` to `savePath` — accepts `mime`/`eml`/`markdown`/`json`/`csv`. target=`messages` batch-exports either an explicit `emailIds` array or messages matching `searchQuery` (or `query` shortcut) into `outputDir` — accepts `markdown`/`json`/`csv`. target=`conversation` exports a full thread (up to 1000 messages) by `conversationId` into `outputDir` (chronological by default; pass `order: "reverse"` for newest-first) — accepts `eml`/`mbox`/`markdown`/`json`/`html`/`csv`. target=`mime` returns raw RFC-822 MIME bytes for `id` (use `headersOnly` for just headers, `base64` for encoded transport, `maxSize` to cap at default 1MB). All targets accept `sharedMailbox` (alias `email`) to export from a shared/delegated mailbox instead of the signed-in account — pass it whenever the id(s)/conversationId/searchQuery come from a shared mailbox, or exports fail with 404 ErrorInvalidMailboxItemId. `includeAttachments` defaults to true for single-message exports and false for batch. Format support varies by target — see the format param enum.',
-    annotations: {
-      title: 'Export Emails',
-      readOnlyHint: false,
-      destructiveHint: false,
-      // openWorldHint: exports full message/MIME/conversation content from
-      // external senders. (#92)
-      openWorldHint: true,
-    },
+      'Export emails to files. target=`message` (default) exports one email by `id` (mime/eml/markdown/json/csv) to `savePath`: a directory (or a path ending in `/`, created if missing) gets a new, unique file name; a file path is created new and an existing file is replaced only with `overwrite: true`. target=`messages` batch-exports `emailIds`, or matches for `searchQuery`/`query`, into `outputDir`, at most 100 messages per call. target=`conversation` exports a thread (up to 1000 messages) by `conversationId` into `outputDir` (eml/mbox/markdown/json/html/csv; `order: "reverse"` for newest first). target=`mime` returns raw RFC-822 MIME for `id` (`headersOnly`, `base64`, `maxSize`, default 1MB). Files are written only inside the system temp directory (the default), ~/Downloads, ~/Documents or OUTLOOK_EXPORT_DIR, never to dot-prefixed names. Pass `sharedMailbox` (alias `email`) when the ids come from a shared mailbox. `includeAttachments` defaults to true for one message, false for batch.',
+    ...toolMetadata('export', 'Export Emails'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -603,11 +559,17 @@ const emailTools = [
           type: 'string',
           enum: ['mime', 'eml', 'markdown', 'json', 'mbox', 'html', 'csv'],
           description:
-            'Export format. Valid values vary by target: target=message accepts mime/eml/markdown/json/csv (mbox and html are conversation-only). target=conversation accepts eml/mbox/markdown/json/html/csv. target=messages (batch) accepts markdown/json/csv. mime is an alias for eml (same RFC822 bytes, .eml extension on disk).',
+            'Export format. Valid values vary by target: target=message accepts mime/eml/markdown/json/csv (mbox and html are conversation-only). target=conversation accepts eml/mbox/markdown/json/html/csv. target=messages (batch) accepts mime/eml/markdown/json (one file per message) or csv (one file). mime is an alias for eml (same RFC822 bytes, .eml extension on disk).',
         },
         savePath: {
           type: 'string',
-          description: 'File path or directory (target=message)',
+          description:
+            'Absolute file path or directory, or one starting with ~/ (target=message). Relative paths are refused. Must be inside the system temp directory, ~/Downloads, ~/Documents or OUTLOOK_EXPORT_DIR. An existing file is not replaced unless overwrite is true.',
+        },
+        overwrite: {
+          type: 'boolean',
+          description:
+            'Replace an existing file at savePath (target=message, default: false). Never replaces a symlink, a hard-linked file, a dotfile, or a file in a dot-directory below the allowed folder.',
         },
         includeAttachments: {
           type: 'boolean',
@@ -618,20 +580,43 @@ const emailTools = [
         emailIds: {
           type: 'array',
           items: { type: 'string' },
-          description: 'Email IDs to export (target=messages)',
+          description:
+            'Email IDs to export (target=messages). At most 100 per call: any beyond the first 100 are left out, and the result says how many.',
         },
         searchQuery: {
           type: 'object',
           properties: {
-            folder: { type: 'string' },
-            from: { type: 'string' },
-            subject: { type: 'string' },
-            receivedAfter: { type: 'string' },
-            receivedBefore: { type: 'string' },
-            maxResults: { type: 'number' },
+            folder: {
+              type: 'string',
+              description:
+                'Folder to search (default: inbox): a well-known name, display name, `Parent/Child` path or folder ID',
+            },
+            from: {
+              type: 'string',
+              description: 'Sender address or name to match (Graph `$search`)',
+            },
+            subject: {
+              type: 'string',
+              description: 'Subject text to match (Graph `$search`)',
+            },
+            receivedAfter: {
+              type: 'string',
+              description:
+                'Only messages received at or after this date/time (ISO 8601)',
+            },
+            receivedBefore: {
+              type: 'string',
+              description:
+                'Only messages received at or before this date/time (ISO 8601)',
+            },
+            maxResults: {
+              type: 'number',
+              description:
+                'Most messages to export (default: 25, max: 100 per call). Newest first, or by relevance when `from`/`subject` is set.',
+            },
           },
           description:
-            'Search query to find emails (target=messages, alternative to emailIds)',
+            'Search to find emails (target=messages, alternative to emailIds)',
         },
         query: {
           type: 'string',
@@ -641,7 +626,7 @@ const emailTools = [
         outputDir: {
           type: 'string',
           description:
-            'Output directory (target=messages/conversation, required)',
+            'Absolute output directory, or one starting with ~/ (target=messages, required; target=message/conversation, default: system temp directory). Must be inside the system temp directory, ~/Downloads, ~/Documents or OUTLOOK_EXPORT_DIR.',
         },
         // Conversation export
         conversationId: {
@@ -657,7 +642,7 @@ const emailTools = [
         sharedMailbox: {
           type: 'string',
           description:
-            'Email address of a shared/delegated mailbox to export from instead of the signed-in account. Applies to all targets (message/messages/conversation/mime) — pass it whenever the id(s)/conversationId/searchQuery belong to a shared mailbox. Requires delegate access + Mail.Read.Shared. Work/school only; needs the server opt-in setting OUTLOOK_SHARED_MAILBOX (otherwise the call is refused with setup guidance).',
+            'Email address of a shared/delegated mailbox to export from (default: the signed-in account). Applies to all targets (message/messages/conversation/mime) — pass it whenever the id(s)/conversationId/searchQuery belong to a shared mailbox. Requires delegate access + Mail.Read.Shared. Work/school only; needs the server opt-in setting OUTLOOK_SHARED_MAILBOX (otherwise the call is refused with setup guidance).',
         },
         email: {
           type: 'string',
@@ -692,14 +677,9 @@ const emailTools = [
         case 'message':
           return handleExportEmail(args);
         default:
-          return {
-            content: [
-              {
-                type: 'text',
-                text: `Unknown export target '${target}'. Valid targets: message, messages, conversation, mime.`,
-              },
-            ],
-          };
+          return toolError(
+            `Unknown export target '${target}'. Valid targets: message, messages, conversation, mime.`
+          );
       }
     },
   },
@@ -707,11 +687,7 @@ const emailTools = [
     name: 'get-mail-tips',
     description:
       'Pre-send recipient validation via Graph `POST /me/getMailTips` (read-only; uses the existing `Mail.Read` scope — no extra permissions). Returns per-recipient tips covering automatic replies (out-of-office), mailbox full status, custom admin mail tips, delivery restrictions, moderation requirements, external-vs-internal scope, max message size, and group member counts (total + external). Use ahead of `send-email` or `draft` action=`create` to catch issues like OOO replies or external-recipient warnings before the message goes out; `send-email`/`draft` accept `checkRecipients: true` to invoke this automatically. Accepts either a comma-separated string or an array of addresses; `tipTypes` filters which tips are requested (defaults to all).',
-    annotations: {
-      title: 'Mail Tips',
-      readOnlyHint: true,
-      openWorldHint: false,
-    },
+    ...toolMetadata('get-mail-tips', 'Mail Tips'),
     inputSchema: {
       type: 'object',
       properties: {

package/email/list.js

@@ -16,6 +16,7 @@ const {
   DEFAULT_LIMITS,
 } = require('../utils/response-formatter');
 const { getEmailFields } = require('../utils/field-presets');
+const { toolError, authRequiredError } = require('../utils/tool-error');
 
 /**
  * Maps verbosity level to field preset
@@ -101,7 +102,7 @@ async function handleListEmails(args) {
     const meta = {
       returned: response.value.length,
       totalAvailable: response['@odata.count'] || null,
-      hasMore: Boolean(response['@odata.nextLink']),
+      hasMore: Boolean(response.hasMore || response['@odata.nextLink']),
       verbosity: verbosity,
     };
 
@@ -124,24 +125,10 @@ async function handleListEmails(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'authenticate' tool first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error listing emails: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error listing emails: ${error.message}`);
   }
 }