@littlebearapps/outlook-assistant 3.9.1 → 3.11.0

package/README.md

@@ -100,7 +100,7 @@ Outlook Assistant works with both personal and work/school Microsoft accounts, b
 | Contacts CRUD | Full support | Full support |
 | Inbox rules | Full support | Full support |
 | Folders | Full support | Full support |
-| Free-text `query` search | Limited — use `subject`, `from`, `to` filters instead | Full KQL support |
+| Free-text `query` search | Limited — progressive fallback; `subject`, `from`, `to` filters are more direct | Full `$search` support |
 | Categories | Full support | Full support |
 | Mailbox settings | Full support | Full support |
 | Focused Inbox | API works (overrides stored) but mail routing not affected | Full support |
@@ -111,7 +111,7 @@ Outlook Assistant works with both personal and work/school Microsoft accounts, b
 
 ### What Makes This Different
 
-- **Progressive search** — on accounts where Microsoft's `$search` API is limited, Outlook Assistant automatically falls back through up to 4 search strategies to find your emails. Most Graph API wrappers fail silently; this one adapts.
+- **Progressive search** — on accounts where Microsoft's `$search` API is limited, Outlook Assistant automatically falls back through up to 4 search strategies to find your emails, and reports which one answered in `_meta.searchMetadata` along with any filter it could not honour (`droppedFilters`). Most Graph API wrappers fail silently; this one adapts and tells you.
 - **Email forensics** — raw header access for DKIM, SPF, DMARC, delivery chain, X-Mailer, X-Originating-IP, and spam scores. Returns the full data so you can investigate phishing, audit compliance, or trace delivery issues. (Auto-verdict is on the roadmap; today the data is surfaced and analysed in-conversation.)
 - **Delta sync** — incremental inbox monitoring returns only what changed since your last check, with tokens for continuous polling. Designed for agent workflows that need to watch a mailbox.
 - **Batch operations** — flag, move, export, or categorise multiple emails in a single call. Search-driven export lets you batch-export results without collecting IDs manually.
@@ -161,6 +161,17 @@ Or run directly without installing:
 npx @littlebearapps/outlook-assistant
 ```
 
+To check which version you have, or to see the available options:
+
+```bash
+outlook-assistant --version     # prints e.g. 3.11.0
+outlook-assistant --help        # usage, options and key environment variables
+```
+
+With no arguments the server speaks the Model Context Protocol over stdio. It's
+normally launched by your MCP client rather than run by hand — started from a
+terminal it will simply wait on stdin.
+
 ### 2. Register an Azure App
 
 You need a Microsoft Azure app registration to authenticate. See the **[Azure Setup Guide](docs/guides/azure-setup.md)** for a detailed walkthrough (including first-time Azure account creation), or if you've done this before:
@@ -278,6 +289,17 @@ cd outlook-assistant
 npm install
 ```
 
+### CLI options
+
+| Option | What it does |
+|--------|-------------|
+| `-v`, `--version` | Print the version to stdout and exit 0 |
+| `-h`, `--help` | Print usage, options and key environment variables, and exit 0 |
+| _(none)_ | Start the MCP server on stdio — the normal mode, invoked by your MCP client |
+
+An unrecognised argument is reported on stderr and exits 1, rather than starting
+a server that would ignore it.
+
 ## Azure App Registration
 
 > **First time with Azure?** The [Azure Setup Guide](docs/guides/azure-setup.md) covers everything from creating an account to your first authentication, including billing setup and common pitfalls.
@@ -446,7 +468,11 @@ npm run auth-server
 
 ### "Invalid client secret" (AADSTS7000215)
 
-You're using the Secret **ID** instead of the Secret **Value**. Go to Azure Portal > Certificates & secrets and copy the **Value** column.
+You're using the Secret **ID** instead of the Secret **Value**. Go to Azure Portal > Certificates & secrets and copy the **Value** column into `OUTLOOK_CLIENT_SECRET`.
+
+The Value is shown only once, when the secret is created — if you've navigated away it can't be read again, so create a new secret. An **expired** secret produces this same error, so check the Expires column too.
+
+Since v3.11.0 the server detects this error and appends the explanation to Microsoft's original message, so you see both the raw error code and what to do about it.
 
 ### Authentication URL doesn't work
 
@@ -497,7 +523,7 @@ USE_TEST_MODE=true npm start
 | [Getting Started](docs/how-to/getting-started/connect-outlook-to-claude.md) | Install, configure, and authenticate — start here |
 | [Azure Setup Guide](docs/guides/azure-setup.md) | Azure account creation, app registration, permissions, and secrets |
 | [How-To Guides](docs/how-to/index.md) | 29 practical guides for email, calendar, contacts, and settings |
-| [Roadmap](ROADMAP.md) | Active milestones (v3.7.5, v3.8.x, v3.10.0+) and recent releases |
+| [Roadmap](ROADMAP.md) | Active milestones (v3.11.1, v3.8.x, v3.12.0+) and recent releases |
 | [Troubleshooting & FAQ](docs/how-to/getting-started/verify-your-connection.md#common-connection-problems) | Common problems, re-authentication, and frequently asked questions |
 | [Tools Reference](docs/quickrefs/tools-reference.md) | All 22 tools with parameters |
 | [AI Agent Guide](docs/how-to/ai-agents/using-outlook-assistant-in-agents.md) | Tool selection and workflow patterns for AI agents |
@@ -506,7 +532,7 @@ Full documentation: [docs/](docs/README.md)
 
 ## Known Limitations
 
-- **Personal account search**: Free-text `query` and the raw `searchExpression` (formerly `kqlQuery`) rely on Microsoft's `$search` API, which has limited support on personal Outlook.com accounts — field-scoped raw `$search` (e.g. `subject:"…"`) may return nothing there. `query` mitigates this with progressive fallback (OData filters, then client-side), so for reliable personal-account search prefer structured filters (`from`, `subject`, `to`, `receivedAfter`) or `query`. Cross-folder search (`searchAllFolders: true`) returns a superset of inbox-only results.
+- **Personal account search**: Free-text `query` and the raw `searchExpression` (formerly `kqlQuery`) rely on Microsoft's `$search` API, which has limited support on personal Outlook.com accounts. `query` mitigates this with progressive fallback (OData filters, boolean filters, then a client-side scan). Field-scoped `$search` (e.g. `subject:"…"`) is rejected outright there; since v3.10.0 `from:`/`to:`/`subject:` expressions are translated into the closest equivalent OData filters and retried, but boolean operators, grouping, wildcards and other field prefixes are not — those still terminate with an explicit no-results rather than a silent broader search. Structured filters (`from`, `subject`, `to`, `receivedAfter`) remain the most direct route. Cross-folder search (`searchAllFolders: true`) returns a superset of inbox-only results.
 - **Focused Inbox**: Only available on work/school Microsoft 365 accounts.
 - **Shared mailboxes**: Require `Mail.Read.Shared` permission and a work/school account.
 - **Meeting room search**: Requires `Place.Read.All` permission with admin consent (work/school accounts only).

package/auth/auth-errors.js

@@ -0,0 +1,89 @@
+/**
+ * Azure AD (AADSTS) error translation.
+ *
+ * Microsoft's identity platform returns accurate but unfriendly errors: the
+ * error_description is a wall of prose ending in a correlation ID, and the
+ * single most common setup mistake — pasting the client secret's *ID* instead
+ * of its *Value* — surfaces only as `AADSTS7000215: Invalid client secret
+ * provided`. (#69)
+ *
+ * This module maps known codes to actionable remediation text. It only ever
+ * *adds* to the original message; the raw Azure error is always preserved so
+ * that searching for the code still works.
+ */
+
+/**
+ * Known Azure error signatures and their remediation hints.
+ * Ordered most-specific first; every matching entry contributes a hint.
+ */
+const AUTH_ERROR_HINTS = [
+  {
+    // The Secret ID vs Secret Value mistake. First row of docs/troubleshooting.md.
+    test: /AADSTS7000215/i,
+    hint:
+      'Invalid client secret. The usual cause is pasting the **Secret ID** (a UUID like `a1b2c3d4-…`) instead of the **Secret Value** (a longer string with mixed case and symbols). ' +
+      'In Azure → App registrations → your app → Certificates & secrets → Client secrets, copy the *Value* column into `OUTLOOK_CLIENT_SECRET`. ' +
+      'The Secret Value is shown only once, when the secret is created — if you have navigated away it can no longer be read, so create a new secret. ' +
+      'An expired secret produces this same error, so check the Expires column too. ' +
+      'See docs/guides/azure-setup.md#4-create-a-client-secret.',
+  },
+  {
+    test: /AADSTS9002331|personal.*account/i,
+    hint: 'This app registration appears to accept personal Microsoft accounts only. Set `OUTLOOK_AUTH_AUDIENCE=consumers` (or the correct tenant GUID) in your MCP env and retry.',
+  },
+  {
+    test: /AADSTS7000218|unauthorized_client|invalid_client/i,
+    // AADSTS7000215 is also delivered as error=invalid_client, but it means the
+    // secret is wrong, not that public client flows are disabled. Suppress the
+    // generic hint so the specific one above is not drowned out.
+    notWhen: /AADSTS7000215/i,
+    hint: "Enable 'Allow public client flows' under Azure → App registration → Authentication → Advanced settings, and add the `nativeclient` redirect URI (Mobile and desktop applications platform).",
+  },
+  {
+    test: /AADSTS700016/i,
+    hint: 'The application was not found in this directory. Check `OUTLOOK_CLIENT_ID` matches the Application (client) ID in Azure, and that `OUTLOOK_AUTH_AUDIENCE` targets the right tenant.',
+  },
+  {
+    test: /invalid_grant|AADSTS700082|AADSTS50173/i,
+    hint: 'The refresh token is expired or has been revoked (refresh tokens last ~90 days). Re-authenticate with the `auth` tool: `action=authenticate`, then `action=device-code-complete`.',
+  },
+];
+
+/** Normalise an Error or string into a searchable message. */
+function toMessage(input) {
+  if (input === null || input === undefined) return '';
+  if (input instanceof Error) return input.message || String(input);
+  if (typeof input === 'object' && input.message) return String(input.message);
+  return String(input);
+}
+
+/**
+ * Return remediation hints for a Microsoft auth error.
+ * @param {Error|string|null|undefined} input - Error or error_description
+ * @returns {string[]} - Zero or more hints; empty when the error is unknown
+ */
+function getAuthErrorHints(input) {
+  const msg = toMessage(input);
+  if (!msg) return [];
+  return AUTH_ERROR_HINTS.filter(
+    (e) => e.test.test(msg) && !(e.notWhen && e.notWhen.test(msg))
+  ).map((e) => e.hint);
+}
+
+/**
+ * Append any known remediation hints to an auth error message.
+ * Returns the message unchanged when nothing is known, so callers can use this
+ * unconditionally without polluting unrelated errors.
+ * @param {Error|string} input
+ * @returns {string}
+ */
+function describeAuthError(input) {
+  const msg = toMessage(input);
+  const hints = getAuthErrorHints(msg);
+  if (!hints.length) return msg;
+  return [msg, '', 'Suggested fixes:', ...hints.map((h) => `- ${h}`)].join(
+    '\n'
+  );
+}
+
+module.exports = { getAuthErrorHints, describeAuthError, AUTH_ERROR_HINTS };

package/auth/oauth-server.js

@@ -38,7 +38,8 @@ const templates = {
       <body style="font-family: Arial, sans-serif; text-align: center; margin-top: 50px;">
         <h1 style="color: #e74c3c;">❌ Token Exchange Failed</h1>
         <p>Failed to exchange authorization code for access token.</p>
-        <p><strong>Error:</strong> ${escapeHtml(error instanceof Error ? error.message : String(error))}</p>
+        <p><strong>Error:</strong></p>
+        <pre style="white-space: pre-wrap; text-align: left; display: inline-block; max-width: 40em; font-family: inherit;">${escapeHtml(error instanceof Error ? error.message : String(error))}</pre>
         <p>You can close this window and try again.</p>
       </body>
     </html>`,
@@ -227,7 +228,7 @@ function setupOAuthRoutes(
 module.exports = {
   setupOAuthRoutes,
   createAuthConfig,
-  // Exporting templates for potential direct use or testing, though not typical
-  // templates
+  // Exported so the rendered error pages can be asserted on directly (#69).
+  templates,
 };
 // Adding a newline at the end of the file as requested by Gemini Code Assist

package/auth/token-storage.js

@@ -3,6 +3,7 @@ const fsSync = require('fs');
 const path = require('path');
 const https = require('https');
 const querystring = require('querystring');
+const { describeAuthError } = require('./auth-errors');
 
 class TokenStorage {
   constructor(config) {
@@ -131,16 +132,22 @@ class TokenStorage {
           return await this.refreshAccessToken();
         } catch (refreshError) {
           console.error('Failed to refresh access token:', refreshError);
-          this.tokens = null; // Invalidate tokens on refresh failure
-          await this._saveTokensToFile(); // Persist invalidation
+          // Drop the in-memory tokens so callers re-authenticate. The save
+          // below is intentionally a no-op — `_saveTokensToFile` returns early
+          // when `tokens` is null — which is the behaviour we want: a transient
+          // network failure must not erase a still-valid refresh token from
+          // disk. The next process start reloads it and retries. (#72)
+          this.tokens = null;
+          await this._saveTokensToFile();
           return null;
         }
       } else {
         console.warn(
           'No refresh token available. Cannot refresh access token.'
         );
-        this.tokens = null; // Invalidate tokens as they are expired and cannot be refreshed
-        await this._saveTokensToFile(); // Persist invalidation
+        // Same as above: clears memory, leaves the file alone. (#72)
+        this.tokens = null;
+        await this._saveTokensToFile();
         return null;
       }
     }
@@ -226,8 +233,10 @@ class TokenStorage {
                 console.error('Error refreshing token:', responseBody);
                 reject(
                   new Error(
-                    responseBody.error_description ||
-                      `Token refresh failed with status ${res.statusCode}`
+                    describeAuthError(
+                      responseBody.error_description ||
+                        `Token refresh failed with status ${res.statusCode}`
+                    )
                   )
                 );
               }
@@ -320,8 +329,10 @@ class TokenStorage {
                 );
                 reject(
                   new Error(
-                    responseBody.error_description ||
-                      `Token exchange failed with status ${res.statusCode}`
+                    describeAuthError(
+                      responseBody.error_description ||
+                        `Token exchange failed with status ${res.statusCode}`
+                    )
                   )
                 );
               }

package/auth/tools.js

@@ -2,6 +2,7 @@
  * Authentication-related tools for the Outlook Assistant server
  */
 const config = require('../config');
+const { getAuthErrorHints } = require('./auth-errors');
 const fs = require('fs');
 const path = require('path');
 const tokenManager = require('./token-manager');
@@ -264,20 +265,10 @@ async function handleDeviceCodeAuth() {
 function buildDeviceCodeErrorResponse(error) {
   const msg = (error && error.message) || String(error);
   const code = error && error.code;
-  const hints = [];
+  // Shared AADSTS hint table (#69) so this path and the token-endpoint paths in
+  // token-storage.js cannot drift apart.
+  const hints = getAuthErrorHints(msg);
 
-  if (/AADSTS9002331/i.test(msg) || /personal.*account/i.test(msg)) {
-    hints.push(
-      'This app registration appears to accept personal Microsoft accounts only. Set `OUTLOOK_AUTH_AUDIENCE=consumers` (or the correct tenant GUID) in your MCP env and retry.'
-    );
-  }
-  if (
-    /invalid_client|unauthorized_client|AADSTS7000218|AADSTS700016/i.test(msg)
-  ) {
-    hints.push(
-      "Enable 'Allow public client flows' under Azure → App registration → Authentication → Advanced settings, and add the `nativeclient` redirect URI (Mobile and desktop applications platform)."
-    );
-  }
   if (
     code === 'ENOTFOUND' ||
     code === 'ETIMEDOUT' ||

package/email/index.js

@@ -73,7 +73,7 @@ const emailTools = [
         searchExpression: {
           type: 'string',
           description:
-            'Raw Microsoft Graph `$search` expression for advanced server-side search, e.g. `subject:"invoice"`, `from:github.com`, or `foo OR bar`. Quote your own phrases; a single bare token is auto-quoted. Pair with `searchAllFolders: true` for cross-folder search. Bypasses other search params. NOTE: on personal Outlook.com accounts field-scoped `$search` is best-effort and may return nothing — prefer `query` there (it has progressive fallback).',
+            'Raw Microsoft Graph `$search` expression for advanced server-side search, e.g. `subject:"invoice"`, `from:github.com`, or `foo OR bar`. Quote your own phrases; a single bare token is auto-quoted. Pair with `searchAllFolders: true` for cross-folder search. Bypasses other search params. NOTE: personal Outlook.com accounts reject field-scoped `$search` outright; since v3.10.0 recognised `from:`/`to:`/`subject:` expressions are translated into the closest equivalent OData filters and retried automatically (a `subject:` term becomes a substring match, so it is close but not identical) (reported as strategy `raw-kql-translated`). Expressions that cannot be translated exactly — free text, `AND`/`OR`, unknown prefixes — are not retried, so use `query` for those there.',
         },
         kqlQuery: {
           type: 'string',

package/email/search.js

@@ -13,6 +13,7 @@ const {
   DEFAULT_LIMITS,
 } = require('../utils/response-formatter');
 const { getEmailFields } = require('../utils/field-presets');
+const { escapeODataString } = require('../utils/odata-helpers');
 
 // Upper bound on how many recent messages the client-side fallback scans
 // before giving up. Deliberately DECOUPLED from the requested result count so
@@ -71,9 +72,16 @@ async function handleSearchEmails(args) {
   const kqlQuery =
     (args.searchExpression || '').trim() || (args.kqlQuery || '').trim();
 
-  // Select fields based on verbosity
+  // Select fields based on verbosity — but never at the cost of correctness.
+  // When more than one search term is supplied, the ladder may satisfy one
+  // server-side and narrow by the rest locally (#229), and those matchers read
+  // `toRecipients` and `bodyPreview`, which the `list` preset omits. Without
+  // this, a `from`+`to` search would drop every row at default verbosity and
+  // return "No emails found" — making `outputVerbosity`, a presentation
+  // parameter, decide which messages are found.
+  const searchTermCount = [query, from, to, subject].filter(Boolean).length;
   const selectFields = getEmailFields(
-    verbosity === VERBOSITY.FULL ? 'search' : 'list'
+    verbosity === VERBOSITY.FULL || searchTermCount > 1 ? 'search' : 'list'
   );
 
   try {
@@ -102,7 +110,12 @@ async function handleSearchEmails(args) {
 
     // Label the scope accurately — a cross-folder search is not "inbox". (#169)
     const scopeLabel = searchAllFolders ? 'all folders' : folder;
-    return formatSearchResults(response, scopeLabel, verbosity);
+    return formatSearchResults(
+      response,
+      scopeLabel,
+      verbosity,
+      searchAllFolders
+    );
   } catch (error) {
     // Handle authentication errors
     if (error.message === 'Authentication required') {
@@ -128,6 +141,134 @@ async function handleSearchEmails(args) {
   }
 }
 
+/** Field prefixes a `searchExpression` can be translated into OData filters. */
+const TRANSLATABLE_KQL_FIELDS = new Set(['from', 'to', 'subject']);
+
+/**
+ * Parse a `searchExpression` that consists purely of recognised field-scoped
+ * terms, e.g. `from:info@example.com` or `subject:"Quarterly Report"`. (#217)
+ *
+ * Unscoped `$search` works fine on personal Outlook.com accounts; only the
+ * field-scoped forms come back empty. Those same messages are reachable
+ * through the OData filters the ladder already builds, so a recognised
+ * expression can be translated and retried rather than reported as absent.
+ *
+ * This parser is deliberately strict, and returns null for anything it does
+ * not fully understand — free text, `AND`/`OR`/`NOT`, parentheses, unknown
+ * prefixes, a repeated field, or free text mixed in with a scoped term. That
+ * keeps the terminal no-fallthrough behaviour for every expression whose
+ * meaning we cannot reproduce exactly, which is what #169 V37-F-1 shipped to
+ * guarantee. Translating a half-understood expression would reintroduce it.
+ *
+ * @param {string} expression - The trimmed raw search expression
+ * @returns {object|null} - Search terms to retry with, or null if not translatable
+ */
+function parseFieldScopedExpression(expression) {
+  const trimmed = (expression || '').trim();
+  if (!trimmed) return null;
+
+  const terms = {};
+  let i = 0;
+
+  while (i < trimmed.length) {
+    while (i < trimmed.length && /\s/.test(trimmed[i])) i++;
+    if (i >= trimmed.length) break;
+
+    // Every token must be `field:value`. A token without a colon is free
+    // text; a colon further along belongs to a later token, and the slice
+    // then carries whitespace or an operator, which fails the field check.
+    const colon = trimmed.indexOf(':', i);
+    if (colon === -1) return null;
+
+    const field = trimmed.slice(i, colon).toLowerCase();
+    if (!TRANSLATABLE_KQL_FIELDS.has(field)) return null;
+    if (terms[field]) return null; // repeated field — ambiguous, don't guess
+    i = colon + 1;
+
+    let value;
+    if (trimmed[i] === '"') {
+      const end = trimmed.indexOf('"', i + 1);
+      if (end === -1) return null; // unbalanced quote
+      value = trimmed.slice(i + 1, end);
+      i = end + 1;
+      // A quoted value must be followed by whitespace or end-of-string.
+      if (i < trimmed.length && !/\s/.test(trimmed[i])) return null;
+    } else {
+      let end = i;
+      while (end < trimmed.length && !/\s/.test(trimmed[end])) end++;
+      value = trimmed.slice(i, end);
+      i = end;
+    }
+
+    if (!value) return null;
+    // Wildcards and grouping mean something in KQL that an OData `eq` or
+    // `contains` does not reproduce. Rather than translate them literally,
+    // decline the whole expression.
+    if (/[()*]/.test(value)) return null;
+    terms[field] = value;
+  }
+
+  return Object.keys(terms).length > 0 ? terms : null;
+}
+
+/**
+ * Retry a field-scoped `searchExpression` as OData filters, down the normal
+ * ladder. Returns null when the expression is not translatable, which keeps
+ * the terminal no-fallthrough behaviour #169 V37-F-1 shipped. (#217)
+ *
+ * @param {object} ctx - Everything the retry needs from the raw-KQL branch
+ * @returns {Promise<object|null>} - A merged response, or null if untranslatable
+ */
+async function retryFieldScopedExpression(ctx) {
+  const {
+    endpoint,
+    accessToken,
+    trimmedKql,
+    kqlForSearch,
+    searchTerms,
+    filterTerms,
+    maxCount,
+    selectFields,
+    searchAttempts,
+  } = ctx;
+
+  const translated = parseFieldScopedExpression(trimmedKql);
+  if (!translated) return null;
+
+  console.error(
+    `Retrying field-scoped searchExpression as OData filters: ${JSON.stringify(translated)}`
+  );
+  const retry = await progressiveSearch(
+    endpoint,
+    accessToken,
+    translated,
+    filterTerms,
+    maxCount,
+    selectFields
+  );
+  const retryCount = retry.value?.length || 0;
+  const strategies = [
+    ...searchAttempts,
+    ...(retry._searchInfo?.strategies || []),
+    // Last, so finalStrategy names the translation rather than whichever rung
+    // of the ladder happened to answer it.
+    'raw-kql-translated',
+  ];
+  retry._searchInfo = {
+    ...retry._searchInfo,
+    attemptsCount: strategies.length,
+    strategies,
+    // Report what the caller actually asked for, not the rewrite.
+    originalTerms: searchTerms,
+    filterTerms,
+    kqlApplied: kqlForSearch,
+    kqlTranslatedTo: translated,
+    appliedTerms: ['kqlQuery'],
+    noResults: retryCount === 0,
+  };
+  return retry;
+}
+
 /**
  * Execute a search with progressively simpler fallback strategies
  * @param {string} endpoint - API endpoint
@@ -158,27 +299,42 @@ async function progressiveSearch(
   //    would drop the user's filter and return unrelated recent emails
   //    with a misleading "combined-search" strategy line. (#169)
   if (searchTerms.kqlQuery) {
-    try {
-      // Pass the user's KQL through as-is. The user is responsible for
-      // their own phrase quoting (e.g. `subject:"foo bar"`); we do NOT
-      // auto-wrap, which previously produced broken nested quotes like
-      // `"subject:"foo bar""` on Graph $search and silently returned
-      // recent unfiltered messages. (#169 V37-F-1)
-      const trimmedKql = searchTerms.kqlQuery.trim();
-      const alreadyQuoted =
-        trimmedKql.startsWith('"') && trimmedKql.endsWith('"');
-      const looksLikeExpression =
-        trimmedKql.includes(':') || /\s/.test(trimmedKql);
-      // Already-quoted phrases and KQL-looking expressions (field syntax
-      // or multi-word) are passed through as-is; only bare single tokens
-      // are wrapped so Graph treats them as phrase searches.
-      let kqlForSearch;
-      if (alreadyQuoted || looksLikeExpression) {
-        kqlForSearch = trimmedKql;
-      } else {
-        kqlForSearch = `"${trimmedKql}"`;
-      }
+    // Pass the user's KQL through as-is. The user is responsible for
+    // their own phrase quoting (e.g. `subject:"foo bar"`); we do NOT
+    // auto-wrap, which previously produced broken nested quotes like
+    // `"subject:"foo bar""` on Graph $search and silently returned
+    // recent unfiltered messages. (#169 V37-F-1)
+    const trimmedKql = searchTerms.kqlQuery.trim();
+    const alreadyQuoted =
+      trimmedKql.startsWith('"') && trimmedKql.endsWith('"');
+    const looksLikeExpression =
+      trimmedKql.includes(':') || /\s/.test(trimmedKql);
+    // Already-quoted phrases and KQL-looking expressions (field syntax
+    // or multi-word) are passed through as-is; only bare single tokens
+    // are wrapped so Graph treats them as phrase searches.
+    let kqlForSearch;
+    if (alreadyQuoted || looksLikeExpression) {
+      kqlForSearch = trimmedKql;
+    } else {
+      kqlForSearch = `"${trimmedKql}"`;
+    }
 
+    // Graph rejects field-scoped expressions outright on personal accounts
+    // ("Syntax error: character ':' is not valid"), so the translated retry
+    // has to be reachable from the catch as well as the empty-result path.
+    const translationContext = {
+      endpoint,
+      accessToken,
+      trimmedKql,
+      kqlForSearch,
+      searchTerms,
+      filterTerms,
+      maxCount,
+      selectFields,
+      searchAttempts,
+    };
+
+    try {
       console.error(`Attempting raw KQL search: ${kqlForSearch}`);
       searchAttempts.push('raw-kql');
 
@@ -205,19 +361,49 @@ async function progressiveSearch(
         originalTerms: searchTerms,
         filterTerms: filterTerms,
         kqlApplied: kqlForSearch,
+        appliedTerms: ['kqlQuery'],
         // noResults flips on the helpful "Suggestions" block in the
         // formatter — without it, an empty kqlQuery result would render
         // the bare "No emails found matching your search criteria" line
         // with no guidance.
         noResults: matched === 0,
       };
-      // Always return — never silently fall through to a path that
+      // Empty-but-successful is the other #217 shape: some tenants answer a
+      // field-scoped expression with 0 rather than a 400.
+      if (matched === 0) {
+        // Guarded like the error path below: if the translated ladder threw,
+        // an unguarded call here would land in the catch and run the whole
+        // retry a second time.
+        try {
+          const retry = await retryFieldScopedExpression(translationContext);
+          if (retry) return retry;
+        } catch (retryError) {
+          console.error(`Translated retry failed: ${retryError.message}`);
+        }
+      }
+
+      // Otherwise always return — never silently fall through to a path that
       // would ignore kqlQuery and return unrelated emails.
       return response;
     } catch (error) {
       console.error(`Raw KQL search failed: ${error.message}`);
-      // Surface the failure rather than masking it with unrelated results.
       searchAttempts.push('raw-kql-error');
+
+      // A field-scoped expression is what Graph rejects here on personal
+      // accounts. Translating and retrying beats reporting mail that plainly
+      // exists as absent — the same messages come back from the equivalent
+      // OData filter. Anything untranslatable still surfaces the error. (#217)
+      try {
+        const retry = await retryFieldScopedExpression(translationContext);
+        if (retry) {
+          retry._searchInfo.kqlError = error.message;
+          return retry;
+        }
+      } catch (retryError) {
+        console.error(`Translated retry also failed: ${retryError.message}`);
+      }
+
+      // Surface the failure rather than masking it with unrelated results.
       return {
         value: [],
         _searchInfo: {
@@ -226,6 +412,7 @@ async function progressiveSearch(
           originalTerms: searchTerms,
           filterTerms: filterTerms,
           kqlError: error.message,
+          appliedTerms: ['kqlQuery'],
           noResults: true,
         },
       };
@@ -273,6 +460,8 @@ async function progressiveSearch(
           strategies: searchAttempts,
           originalTerms: searchTerms,
           filterTerms: filterTerms,
+          // The combined $filter carried every supplied term. (#229)
+          appliedTerms: SEARCH_TERM_KEYS.filter((t) => searchTerms[t]),
         };
         return response;
       }
@@ -311,7 +500,9 @@ async function progressiveSearch(
         simplifiedParams.$filter = buildToFilter(searchTerms[term]);
       } else if (term === 'subject') {
         // Use $filter with contains() — $search silently fails on personal MS accounts
-        simplifiedParams.$filter = `contains(subject, '${searchTerms[term].replace(/'/g, "''")}')`;
+        simplifiedParams.$filter = `contains(subject, '${escapeODataString(
+          searchTerms[term]
+        )}')`;
       } else if (term === 'query') {
         // On personal accounts, $search fails with 503. Use $filter with
         // contains(subject) as a best-effort fallback for free-text queries.
@@ -324,7 +515,7 @@ async function progressiveSearch(
           .split(/\s+/)
           .filter(Boolean);
         simplifiedParams.$filter = queryWords
-          .map((w) => `contains(subject, '${w.replace(/'/g, "''")}')`)
+          .map((w) => `contains(subject, '${escapeODataString(w)}')`)
           .join(' and ');
       }
 
@@ -339,16 +530,39 @@ async function progressiveSearch(
         maxCount
       );
       if (response.value && response.value.length > 0) {
+        // This $filter carried only `term`. Apply every other supplied search
+        // term locally before returning — otherwise we hand back the
+        // single-term superset while claiming the filter was applied. (#229)
+        const { matched, secondaryApplied } = applySecondarySearchTerms(
+          response.value,
+          searchTerms,
+          term
+        );
+        if (matched.length > 0) {
+          const narrowing =
+            secondaryApplied.length > 0
+              ? ` after local ${secondaryApplied.join(', ')} narrowing of ${response.value.length}`
+              : '';
+          console.error(
+            `Search with ${term} successful: found ${matched.length} results${narrowing}`
+          );
+          narrowResponse(response, matched);
+          response._searchInfo = {
+            attemptsCount: searchAttempts.length,
+            strategies: searchAttempts,
+            originalTerms: searchTerms,
+            filterTerms: filterTerms,
+            appliedTerms: [term, ...secondaryApplied],
+            ...(secondaryApplied.length > 0 && {
+              clientSideTerms: secondaryApplied,
+            }),
+          };
+          return response;
+        }
+        recordNarrowingMiss(scanState, response.value.length);
         console.error(
-          `Search with ${term} successful: found ${response.value.length} results`
+          `Search with ${term} found ${response.value.length} results, but none also satisfied ${secondaryApplied.join(', ')} — continuing`
         );
-        response._searchInfo = {
-          attemptsCount: searchAttempts.length,
-          strategies: searchAttempts,
-          originalTerms: searchTerms,
-          filterTerms: filterTerms,
-        };
-        return response;
       }
     } catch (error) {
       console.error(`Search with ${term} failed: ${error.message}`);
@@ -418,13 +632,32 @@ async function progressiveSearch(
       console.error(
         `Boolean filter search found ${response.value?.length || 0} results`
       );
-      response._searchInfo = {
-        attemptsCount: searchAttempts.length,
-        strategies: searchAttempts,
-        originalTerms: searchTerms,
-        filterTerms: filterTerms,
-      };
-      return response;
+      // This step applied only the boolean/date filters. Narrow by the
+      // caller's search terms rather than returning "every unread email" as
+      // though it were "every unread email from X". (#229)
+      const { matched, secondaryApplied } = applySecondarySearchTerms(
+        response.value || [],
+        searchTerms,
+        null
+      );
+      if (matched.length > 0 || secondaryApplied.length === 0) {
+        narrowResponse(response, matched);
+        response._searchInfo = {
+          attemptsCount: searchAttempts.length,
+          strategies: searchAttempts,
+          originalTerms: searchTerms,
+          filterTerms: filterTerms,
+          appliedTerms: secondaryApplied,
+          ...(secondaryApplied.length > 0 && {
+            clientSideTerms: secondaryApplied,
+          }),
+        };
+        return response;
+      }
+      recordNarrowingMiss(scanState, response.value.length);
+      console.error(
+        `Boolean filter search found ${response.value.length} results, but none satisfied ${secondaryApplied.join(', ')} — continuing`
+      );
     } catch (error) {
       console.error(`Boolean filter search failed: ${error.message}`);
       // Retry without $orderby if it was the issue
@@ -443,13 +676,33 @@ async function progressiveSearch(
             retryParams,
             maxCount
           );
-          response._searchInfo = {
-            attemptsCount: searchAttempts.length,
-            strategies: searchAttempts,
-            originalTerms: searchTerms,
-            filterTerms: filterTerms,
-          };
-          return response;
+          const { matched, secondaryApplied } = applySecondarySearchTerms(
+            response.value || [],
+            searchTerms,
+            null
+          );
+          // Same guard as the primary boolean path above: an empty set here
+          // means the search terms went unsatisfied, so fall through to the
+          // no-results rung rather than returning 0 with filterApplied true
+          // and no guidance.
+          if (matched.length > 0 || secondaryApplied.length === 0) {
+            narrowResponse(response, matched);
+            response._searchInfo = {
+              attemptsCount: searchAttempts.length,
+              strategies: searchAttempts,
+              originalTerms: searchTerms,
+              filterTerms: filterTerms,
+              appliedTerms: secondaryApplied,
+              ...(secondaryApplied.length > 0 && {
+                clientSideTerms: secondaryApplied,
+              }),
+            };
+            return response;
+          }
+          recordNarrowingMiss(scanState, response.value.length);
+          console.error(
+            `Boolean filter retry found ${response.value.length} results, but none satisfied ${secondaryApplied.join(', ')} — continuing`
+          );
         } catch (retryError) {
           console.error(
             `Boolean filter retry also failed: ${retryError.message}`
@@ -489,6 +742,11 @@ async function progressiveSearch(
           scanLimit: scanState.scanLimit,
           truncated: scanState.truncated,
         }),
+        // A local narrowing pass that matched nothing looked only at the page
+        // the winning filter returned, so say how much that was. (#229)
+        ...(scanState.narrowedCandidates !== undefined && {
+          narrowedCandidates: scanState.narrowedCandidates,
+        }),
       },
     };
   }
@@ -546,11 +804,13 @@ function buildFromFilter(val) {
   if (type === 'domain') {
     // Use contains() — endswith() not supported on personal accounts
     const domain = val.startsWith('@') ? val : `@${val}`;
-    return `contains(from/emailAddress/address, '${domain.substring(1)}')`;
+    return `contains(from/emailAddress/address, '${escapeODataString(
+      domain.substring(1)
+    )}')`;
   } else if (type === 'email') {
-    return `from/emailAddress/address eq '${val}'`;
+    return `from/emailAddress/address eq '${escapeODataString(val)}'`;
   }
-  return `contains(from/emailAddress/name, '${val}')`;
+  return `contains(from/emailAddress/name, '${escapeODataString(val)}')`;
 }
 
 /**
@@ -563,11 +823,17 @@ function buildToFilter(val) {
   if (type === 'domain') {
     const domain = val.startsWith('@') ? val : `@${val}`;
     // Use contains() — endswith() not supported on personal accounts
-    return `toRecipients/any(r: contains(r/emailAddress/address, '${domain.substring(1)}'))`;
+    return `toRecipients/any(r: contains(r/emailAddress/address, '${escapeODataString(
+      domain.substring(1)
+    )}'))`;
   } else if (type === 'email') {
-    return `toRecipients/any(r: r/emailAddress/address eq '${val}')`;
+    return `toRecipients/any(r: r/emailAddress/address eq '${escapeODataString(
+      val
+    )}')`;
   }
-  return `toRecipients/any(r: contains(r/emailAddress/name, '${val}'))`;
+  return `toRecipients/any(r: contains(r/emailAddress/name, '${escapeODataString(
+    val
+  )}'))`;
 }
 
 /**
@@ -621,6 +887,150 @@ function filterQueryClientSide(messages, queryText) {
   });
 }
 
+/** Relabel internal keys to the caller-facing param names. (#169) */
+const FILTER_LABELS = { kqlQuery: 'searchExpression' };
+
+/** Every filter key a caller can supply, including the terminal raw-KQL one. */
+const SEARCH_FILTER_KEYS = ['from', 'to', 'subject', 'query', 'kqlQuery'];
+
+/**
+ * The search terms a caller can supply, in ladder-priority order. `kqlQuery`
+ * is handled by the terminal raw-KQL branch and never mixes with these.
+ */
+const SEARCH_TERM_KEYS = ['from', 'to', 'subject', 'query'];
+
+/**
+ * Client-side matcher for a `from` value. Mirrors filterToClientSide, matching
+ * either the sender address or the display name. (#229)
+ * @param {Array} messages - Messages to filter
+ * @param {string} fromValue - The from filter value
+ * @returns {Array} - Matching messages
+ */
+function filterFromClientSide(messages, fromValue) {
+  // Mirror buildFromFilter branch for branch. A plain substring test over both
+  // address and name diverges from the server in both directions: it misses
+  // `@example.com` against `alerts@mail.example.com` (the server strips the
+  // leading @ and does contains), and it wrongly keeps `bbob@x.com` for
+  // `bob@x.com` (the server uses eq).
+  const type = classifyEmailFilter(fromValue);
+
+  if (type === 'domain') {
+    const domain = (
+      fromValue.startsWith('@') ? fromValue.slice(1) : fromValue
+    ).toLowerCase();
+    return messages.filter((m) =>
+      (m.from?.emailAddress?.address || '').toLowerCase().includes(domain)
+    );
+  }
+
+  if (type === 'email') {
+    const needle = fromValue.toLowerCase();
+    return messages.filter(
+      (m) => (m.from?.emailAddress?.address || '').toLowerCase() === needle
+    );
+  }
+
+  const needle = fromValue.toLowerCase();
+  return messages.filter((m) =>
+    (m.from?.emailAddress?.name || '').toLowerCase().includes(needle)
+  );
+}
+
+/**
+ * Client-side matcher for a `subject` value — the local equivalent of the
+ * server-side `contains(subject, '…')`. (#229)
+ * @param {Array} messages - Messages to filter
+ * @param {string} subjectValue - The subject filter value
+ * @returns {Array} - Matching messages
+ */
+function filterSubjectClientSide(messages, subjectValue) {
+  const needle = subjectValue.toLowerCase().trim();
+  if (!needle) return messages;
+  return messages.filter((m) =>
+    (m.subject || '').toLowerCase().includes(needle)
+  );
+}
+
+const CLIENT_SIDE_TERM_MATCHERS = {
+  from: filterFromClientSide,
+  to: filterToClientSide,
+  subject: filterSubjectClientSide,
+  query: filterQueryClientSide,
+};
+
+/**
+ * Narrow a result set by every supplied search term that the winning strategy
+ * did NOT apply server-side. (#229)
+ *
+ * Steps 2 and 3 of the ladder each satisfy at most one search term — step 2
+ * returns on the first single term that yields results, and step 3 applies
+ * only the boolean/date filters. Both used to return that set verbatim, so
+ * `from=X` + `subject=Y` handed back every email from X while
+ * `searchMetadata.filterApplied` still said `true`. For an AI caller asking
+ * "find the email from X about Y", a confident superset is strictly worse
+ * than returning nothing.
+ *
+ * Narrowing runs over the rows the winning strategy already fetched, so it can
+ * miss a match beyond that page; the ladder continues to the next strategy when
+ * it comes up empty, and `recordNarrowingMiss` records how much was examined so
+ * the no-results response can disclose it rather than implying the mailbox was
+ * exhausted.
+ *
+ * The local matchers mirror their server-side counterparts but are not
+ * identical to them — `filterQueryClientSide` searches the body preview, and a
+ * display-name match is a substring test either side — so a narrowed set is a
+ * close approximation of the combined filter, not a formal equivalent.
+ *
+ * @param {Array} messages - Messages returned by the winning strategy
+ * @param {object} searchTerms - All search terms the caller supplied
+ * @param {string|null} appliedTerm - The term already satisfied server-side
+ * @returns {{matched: Array, secondaryApplied: string[]}}
+ */
+/**
+ * Replace a response's rows with the narrowed subset, keeping the reported
+ * totals honest. `@odata.count` was set from the pre-narrowing page, so
+ * leaving it makes `_meta.totalAvailable` claim matches that do not exist and
+ * invites a caller to paginate for them. (#229)
+ *
+ * @param {object} response - The Graph response being narrowed in place
+ * @param {Array} matched - The rows that survived narrowing
+ */
+function narrowResponse(response, matched) {
+  const dropped = (response.value || []).length !== matched.length;
+  response.value = matched;
+  if (dropped) {
+    delete response['@odata.count'];
+    delete response['@odata.nextLink'];
+  }
+}
+
+/**
+ * Note that a narrowing pass examined rows and matched none of them, so the
+ * eventual no-results response can say how much was actually looked at rather
+ * than implying the mailbox was exhausted. (#229)
+ *
+ * @param {object} scanState - Side-channel carried to the no-results rung
+ * @param {number} examined - How many rows the narrowing pass saw
+ */
+function recordNarrowingMiss(scanState, examined) {
+  if (!scanState) return;
+  scanState.narrowedCandidates = Math.max(
+    scanState.narrowedCandidates || 0,
+    examined
+  );
+}
+
+function applySecondarySearchTerms(messages, searchTerms, appliedTerm) {
+  const secondary = SEARCH_TERM_KEYS.filter(
+    (t) => t !== appliedTerm && searchTerms[t]
+  );
+  let matched = messages;
+  for (const term of secondary) {
+    matched = CLIENT_SIDE_TERM_MATCHERS[term](matched, searchTerms[term]);
+  }
+  return { matched, secondaryApplied: secondary };
+}
+
 /**
  * Fetch a window of recent messages for the client-side filtering fallback.
  * Uses the 'search' field preset (includes toRecipients and bodyPreview).
@@ -734,7 +1144,14 @@ async function runClientSideFallback(
     kind === 'to'
       ? filterToClientSide(messages, searchTerms.to)
       : filterQueryClientSide(messages, searchTerms.query);
-  const matched = applyBooleanDateFilters(termMatched, filterTerms);
+  // The local matcher covers only `kind`; narrow by the caller's other search
+  // terms too, or this path returns the same superset step 2 used to. (#229)
+  const { matched: narrowed, secondaryApplied } = applySecondarySearchTerms(
+    termMatched,
+    searchTerms,
+    kind
+  );
+  const matched = applyBooleanDateFilters(narrowed, filterTerms);
   if (matched.length === 0) {
     return null;
   }
@@ -748,6 +1165,8 @@ async function runClientSideFallback(
       strategies: searchAttempts,
       originalTerms: searchTerms,
       filterTerms,
+      appliedTerms: [kind, ...secondaryApplied],
+      ...(secondaryApplied.length > 0 && { clientSideTerms: secondaryApplied }),
       candidatesScanned,
       scanLimit: CLIENT_SCAN_LIMIT,
       truncated,
@@ -785,7 +1204,7 @@ function buildSearchParams(searchTerms, filterTerms, count, selectFields) {
   // Use $filter for subject — $search silently fails on personal MS accounts
   if (searchTerms.subject) {
     filterConditions.push(
-      `contains(subject, '${searchTerms.subject.replace(/'/g, "''")}')`
+      `contains(subject, '${escapeODataString(searchTerms.subject)}')`
     );
   }
 
@@ -887,14 +1306,103 @@ function addBooleanFilters(params, filterTerms) {
   }
 }
 
+/**
+ * Build no-results guidance from what the caller actually supplied and what the
+ * progressive-search ladder actually attempted, rather than printing the same
+ * four lines on every empty search. (#231)
+ *
+ * The previous fixed list included "use `from` filter instead of `to` (more
+ * reliable on personal accounts)", which has been untrue since v3.7.1 added the
+ * client-side `to` fallback (#139 / PR #141). The tool was teaching its callers
+ * something false about itself.
+ *
+ * @param {object} searchInfo - The _searchInfo block from progressiveSearch
+ * @param {boolean} searchAllFolders - Whether the search already spanned all folders
+ * @returns {string[]} - Ordered suggestion lines, without the leading bullet
+ */
+function buildNoResultsSuggestions(searchInfo, searchAllFolders) {
+  const filters = searchInfo.originalTerms || {};
+  const strategies = searchInfo.strategies || [];
+  const suggestions = [];
+
+  // Scope — only worth suggesting when it isn't already what we just did.
+  if (searchAllFolders) {
+    suggestions.push(
+      'All folders were already searched, so no message in this mailbox matches these filters'
+    );
+  } else {
+    suggestions.push(
+      'Try `searchAllFolders: true` to search across all folders including Archive'
+    );
+    suggestions.push(
+      'Specify the correct folder if emails have been moved (use the `folders` tool to list folders)'
+    );
+  }
+
+  // Report the fallback the ladder actually took, instead of guessing at one.
+  const clientSide = strategies.filter((s) => s.startsWith('client-side-'));
+  if (clientSide.length > 0) {
+    const fields = clientSide
+      .map((s) => `\`${s.slice('client-side-'.length)}\``)
+      .join(', ');
+    let note = `${fields} was matched locally after the server-side filter came back empty`;
+    if (searchInfo.candidatesScanned) {
+      note += ` — ${searchInfo.candidatesScanned} recent messages examined`;
+      if (searchInfo.truncated) {
+        note += `, hitting the ${searchInfo.scanLimit} scan limit, so older matches were not seen (narrow with \`receivedAfter\`)`;
+      }
+    }
+    suggestions.push(note);
+  }
+
+  // A narrowing pass that matched nothing saw only the page the winning
+  // server-side filter returned — a much weaker basis for "none exists" than
+  // the bounded client-side scan, so say so rather than implying otherwise.
+  if (searchInfo.narrowedCandidates) {
+    suggestions.push(
+      `The other filters were applied locally to the ${searchInfo.narrowedCandidates} message${searchInfo.narrowedCandidates === 1 ? '' : 's'} the server-side filter returned, so a match beyond that page would not have been seen — raise \`count\`, or narrow with \`receivedAfter\``
+    );
+  }
+
+  if (filters.kqlQuery) {
+    suggestions.push(
+      'Structured filters (`from`, `to`, `subject`) reach messages that `searchExpression` cannot on personal accounts'
+    );
+  }
+
+  if (filters.query) {
+    suggestions.push(
+      'Free-text `query` falls back to a subject match on personal accounts — try `subject` directly, or fewer words'
+    );
+  }
+
+  if (filters.subject) {
+    suggestions.push(
+      '`subject` is a substring match — try a shorter, more distinctive fragment'
+    );
+  }
+
+  const applied = ['from', 'to', 'subject', 'query', 'kqlQuery'].filter(
+    (k) => filters[k]
+  );
+  if (applied.length > 1) {
+    suggestions.push(
+      `All ${applied.length} filters must match the same message — try removing one`
+    );
+  }
+
+  return suggestions;
+}
+
 /**
  * Format search results into Markdown using response-formatter utilities
  * @param {object} response - The API response object
  * @param {string} folder - Folder that was searched
  * @param {string} verbosity - Output verbosity level
+ * @param {boolean} [searchAllFolders] - Whether the search spanned all folders
  * @returns {object} - MCP response object
  */
-function formatSearchResults(response, folder, verbosity) {
+function formatSearchResults(response, folder, verbosity, searchAllFolders) {
   // Build metadata
   const meta = {
     returned: (response.value || []).length,
@@ -909,11 +1417,35 @@ function formatSearchResults(response, folder, verbosity) {
       response._searchInfo.strategies[
         response._searchInfo.strategies.length - 1
       ];
+    // Which supplied filters actually reached the result set, and which the
+    // winning strategy could not honour. `droppedFilters` is normally empty;
+    // a non-empty value means the response is a superset of what was asked
+    // for, and `filterApplied` must not claim otherwise. (#229)
+    const suppliedTerms = SEARCH_FILTER_KEYS.filter(
+      (k) => response._searchInfo.originalTerms?.[k]
+    );
+    const appliedTerms = response._searchInfo.appliedTerms ?? suppliedTerms;
+    const droppedFilters = suppliedTerms
+      .filter((k) => !appliedTerms.includes(k))
+      .map((k) => FILTER_LABELS[k] || k);
+
     meta.searchMetadata = {
       strategiesAttempted: response._searchInfo.strategies,
       finalStrategy: finalStrategy,
-      filterApplied: !response._searchInfo.noResults,
+      filterApplied:
+        !response._searchInfo.noResults && droppedFilters.length === 0,
+      droppedFilters,
+      ...(response._searchInfo.clientSideTerms && {
+        clientSideFilters: response._searchInfo.clientSideTerms,
+      }),
       originalFilters: response._searchInfo.originalTerms,
+      // A field-scoped `searchExpression` that personal accounts reject is
+      // retried as OData filters, which is a rewrite of what the caller asked
+      // for. Report the rewrite, so `raw-kql-translated` is inspectable rather
+      // than something the caller has to take on trust. (#217)
+      ...(response._searchInfo.kqlTranslatedTo && {
+        kqlTranslatedTo: response._searchInfo.kqlTranslatedTo,
+      }),
       // Surface client-side scan coverage so callers can tell when a fallback
       // result may be incomplete (older matches beyond the scan budget). (#169)
       ...(response._searchInfo.candidatesScanned !== undefined && {
@@ -929,8 +1461,6 @@ function formatSearchResults(response, folder, verbosity) {
     // Actionable guidance when filters were specified but matched nothing
     if (response._searchInfo?.noResults) {
       const filters = response._searchInfo.originalTerms || {};
-      // Relabel internal keys to the caller-facing param names. (#169)
-      const FILTER_LABELS = { kqlQuery: 'searchExpression' };
       const activeFilters = Object.entries(filters)
         .filter(([, v]) => v)
         .map(([k]) => FILTER_LABELS[k] || k);
@@ -939,13 +1469,13 @@ function formatSearchResults(response, folder, verbosity) {
           ? ` (filters: ${activeFilters.join(', ')})`
           : '';
 
-      const text =
-        `No emails found matching your filters in "${folder}"${filterDesc}.\n\n` +
-        '**Suggestions:**\n' +
-        '- Try `searchAllFolders: true` to search across all folders including Archive\n' +
-        '- Specify the correct folder if emails have been moved (use `folders` tool to list folders)\n' +
-        '- Use `from` filter instead of `to` (more reliable on personal accounts)\n' +
-        '- Use `searchExpression` with `searchAllFolders: true` for cross-folder search';
+      const suggestions = buildNoResultsSuggestions(
+        response._searchInfo,
+        searchAllFolders
+      );
+
+      const bullets = suggestions.map((line) => `- ${line}`).join('\n');
+      const text = `No emails found matching your filters in "${folder}"${filterDesc}.\n\n**Suggestions:**\n${bullets}`;
 
       return {
         content: [{ type: 'text', text }],
@@ -1029,7 +1559,7 @@ async function handleSearchByMessageId(args) {
 
     // Build filter - need to escape the Message-ID properly
     // Graph API expects: internetMessageId eq '<value>'
-    const escapedMessageId = messageId.replace(/'/g, "''");
+    const escapedMessageId = escapeODataString(messageId);
 
     const params = {
       $filter: `internetMessageId eq '${escapedMessageId}'`,
@@ -1112,4 +1642,6 @@ module.exports = {
   classifyEmailFilter,
   filterToClientSide,
   filterQueryClientSide,
+  filterFromClientSide,
+  filterSubjectClientSide,
 };

package/index.js

@@ -5,6 +5,65 @@
  * A Model Context Protocol server that provides access to
  * Microsoft Outlook through the Microsoft Graph API.
  */
+// CLI flag handling (#68).
+//
+// Deliberately the first thing that runs: it must complete before the SDK
+// imports, before the auth modules load, and before the startup banner below
+// writes to stderr — otherwise `--version` output is buried in server noise and
+// the process never exits (the SIGTERM handler below keeps it alive).
+//
+// `config.js` is required lazily here so this costs nothing on the normal
+// server path; it is the single source of truth for the version, which it
+// reads from package.json.
+const cliArgs = process.argv.slice(2);
+if (cliArgs.length > 0) {
+  const HELP_TEXT = `outlook-assistant — MCP server for Microsoft Outlook via the Microsoft Graph API.
+
+Usage:
+  outlook-assistant [options]
+
+Options:
+  -v, --version   Print the version and exit
+  -h, --help      Show this help and exit
+
+With no options the server starts and speaks the Model Context Protocol over
+stdio. It is normally launched by an MCP client (Claude Desktop, Claude Code)
+rather than run by hand — started from a terminal it will simply wait on stdin.
+
+Key environment variables:
+  OUTLOOK_CLIENT_ID                 Azure app registration client ID
+  OUTLOOK_CLIENT_SECRET             Client secret VALUE (not the Secret ID)
+  OUTLOOK_AUTH_METHOD               device-code (default) | browser
+  OUTLOOK_AUTH_AUDIENCE             common | consumers | organizations | <tenant-guid>
+  OUTLOOK_MAX_EMAILS_PER_SESSION    Cap on sends per session
+  OUTLOOK_ALLOWED_RECIPIENTS        Comma-separated recipient allowlist
+  USE_TEST_MODE                     Set to "true" to run against mock data
+
+Documentation: https://github.com/littlebearapps/outlook-assistant`;
+
+  const KNOWN_FLAGS = new Set(['--version', '-v', '--help', '-h']);
+
+  // Validate every argument before acting on any of them. Checking for a
+  // recognised flag first would let `--version --nope` succeed and silently
+  // swallow the typo — an unrecognised argument is a user error regardless of
+  // what else is on the command line.
+  const unknown = cliArgs.find((arg) => !KNOWN_FLAGS.has(arg));
+  if (unknown) {
+    console.error(
+      `outlook-assistant: unrecognised argument '${unknown}'\nRun 'outlook-assistant --help' for usage.`
+    );
+    process.exit(1);
+  }
+
+  if (cliArgs.includes('--version') || cliArgs.includes('-v')) {
+    console.log(require('./config').SERVER_VERSION);
+    process.exit(0);
+  }
+
+  console.log(HELP_TEXT);
+  process.exit(0);
+}
+
 const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
 const {
   StdioServerTransport,

package/llms-install.md

@@ -83,7 +83,7 @@ After authentication, test with:
 
 | Problem | Solution |
 |---------|----------|
-| "Invalid client secret" (AADSTS7000215) | Use the secret **Value**, not the Secret ID |
+| "Invalid client secret" (AADSTS7000215) | Use the secret **Value**, not the Secret ID. Also check it hasn't expired. v3.11.0+ appends an explanation to Microsoft's raw error |
 | Auth URL doesn't work | Start the auth server first |
 | "EADDRINUSE :3333" | Run `npx kill-port 3333` then restart auth server |
 | Empty API responses | Run `auth` tool with `action=status` to check token |

package/llms.txt

@@ -22,7 +22,7 @@ Built by [Little Bear Apps](https://littlebearapps.com).
 
 ## Key Differentiators
 
-- **Progressive search**: Automatically falls back through 4 search strategies when Microsoft's `$search` API is unavailable (personal accounts) — most Graph API wrappers fail silently. Explicit "no results" messaging instead of unfiltered fallback. Cross-folder search (`searchAllFolders`) reliably returns a superset of inbox results.
+- **Progressive search**: Automatically falls back through 4 search strategies when Microsoft's `$search` API is unavailable (personal accounts) — most Graph API wrappers fail silently. Explicit "no results" messaging instead of unfiltered fallback, and `_meta.searchMetadata` reports which strategy answered plus any filter that could not be honoured (`droppedFilters`), so a partially-applied search can never pass as a complete one. Field-scoped `$search` expressions (`from:`/`to:`/`subject:`), which personal accounts reject outright, are translated to equivalent OData filters and retried. Cross-folder search (`searchAllFolders`) reliably returns a superset of inbox results.
 - **Remote-friendly auth**: Device code flow (default) — no auth server, no port forwarding, no SSH tunnels. State persists across MCP server restarts. Works from Untether, mosh, SSH, and headless environments.
 - **Email forensics**: Built-in header analysis for DKIM, SPF, DMARC authentication, delivery chains, and spam scores — useful for phishing investigation and compliance
 - **Delta sync**: Incremental inbox monitoring — returns only new, modified, and deleted emails since last check, with tokens for continuous polling
@@ -79,6 +79,6 @@ Requires an Azure app registration with Microsoft Graph delegated permissions. S
 - [FAQ](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/faq/faq.md): Frequently asked questions — install, accounts, permissions, tokens, send safety, updates, uninstall (also at <https://littlebearapps.com/help/outlook-assistant/faq/>)
 - [CLAUDE.md](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CLAUDE.md): Quick reference for development
 - [CONTRIBUTING](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CONTRIBUTING.md): Contribution guidelines
-- [CHANGELOG](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CHANGELOG.md): Version history (current: v3.9.0 — nested folder addressing by path/ID (#216); reliable cross-folder search with `kqlQuery` renamed to `searchExpression` (#169); plus the v3.8.3 patch — security `overrides` clearing the audit gate (#215), `openWorldHint` on external-content tools (#92), canonical UTC ISO-8601 `list-events` times (#118))
-- [ROADMAP](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/ROADMAP.md): Active milestones (v3.7.5 polish, v3.8.x carry-over, v3.10.0+ new Graph APIs)
+- [CHANGELOG](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CHANGELOG.md): Version history (current: v3.11.0 — fixes & polish: `--version`/`--help` CLI flags, where previously any argument was ignored and the server booted and hung on stdin (#68); `AADSTS7000215` (the Secret ID vs Secret Value mistake) now explains itself instead of passing Microsoft's raw error through, via one shared AADSTS hint table (#69); token-refresh round trip covered end to end from disk to the `Authorization` header on the next Graph call (#72); all 17 development-dependency advisories cleared, so `npm audit` reports zero at every severity. Preceded by v3.10.0 — search correctness: field-scoped `searchExpression` translated to OData filters and retried on personal accounts (#217), two-filter searches no longer returning the single-filter superset with `searchMetadata.droppedFilters` reporting anything unhonoured (#229), `from`/`to` filter values OData-escaped (#230), no-results guidance derived from what was actually attempted (#231) — and v3.9.1, a packaging hotfix restoring `request-handler.js` in the published tarball (#223))
+- [ROADMAP](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/ROADMAP.md): Active milestones (v3.11.1 tool description audit, v3.8.x carry-over, v3.12.0+ new Graph APIs)
 - [SECURITY](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/SECURITY.md): Security policy, token handling, and MCP safety controls

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebearapps/outlook-assistant",
-  "version": "3.9.1",
+  "version": "3.11.0",
   "mcpName": "io.github.littlebearapps/outlook-assistant",
   "description": "Outlook Assistant — MCP server with 22 tools for email, calendar, contacts, and settings via Microsoft Graph API",
   "main": "index.js",
@@ -98,8 +98,11 @@
   },
   "overrides": {
     "minimatch": ">=3.1.3",
-    "hono": "^4.12.31",
-    "fast-uri": "^3.1.4",
+    "hono": "^4.13.7",
+    "@hono/node-server": "^1.19.17",
+    "fast-uri": "^3.1.7",
+    "ip-address": "^10.7.0",
+    "qs": "^6.16.0",
     "body-parser": "^2.3.0"
   }
 }