# Outlook Semantic MCP - Tools

The Outlook Semantic MCP Server exposes tools whose availability depends on the deployment mode (`MCP_BACKEND`) and debug settings.

**Mode A (**

`verify_inbox_connection`, `reconnect_inbox`, `delete_inbox_data`, and `sync_progress` are **only available when `MCP_BACKEND=microsoft_graph_and_unique_api`**. They are not registered in `microsoft_graph` mode.

**Debug-Mode Tools**

`run_full_sync`, `pause_full_sync`, `resume_full_sync`, and `restart_full_sync` are **only available when `MCP_BACKEND=microsoft_graph_and_unique_api` AND `MCP_DEBUG_MODE=enabled`**. They do not appear for standard deployments or in `microsoft_graph` mode. **Note:** Debug mode exposes these tools to **all** connected MCP users, not just operators. Do not leave enabled in production.

## Tool Overview

| Tool | Category | Mutating | Mode |
| --- | --- | --- | --- |
| [`search_emails`](https://docs.unique.ai/it-operators/integrations-connectors/outlook-semantic-mcp/outlook-semantic-mcp-technical-reference/outlook-semantic-mcp-tools#search_emails) | Email Search | No | Both |
| [`open_email`](https://docs.unique.ai/it-operators/integrations-connectors/outlook-semantic-mcp/outlook-semantic-mcp-technical-reference/outlook-semantic-mcp-tools#open_email) | Email Search | No | Both |
| [`create_draft_email`](https://docs.unique.ai/it-operators/integrations-connectors/outlook-semantic-mcp/outlook-semantic-mcp-technical-reference/outlook-semantic-mcp-tools#create_draft_email) | Draft Creation | Yes | Both |
| [`lookup_contacts`](https://docs.unique.ai/it-operators/integrations-connectors/outlook-semantic-mcp/outlook-semantic-mcp-technical-reference/outlook-semantic-mcp-tools#lookup_contacts) | Contact Lookup | No | Both |
| [`list_categories`](https://docs.unique.ai/it-operators/integrations-connectors/outlook-semantic-mcp/outlook-semantic-mcp-technical-reference/outlook-semantic-mcp-tools#list_categories) | Mailbox Utilities | No | Both |
| [`list_mailboxes_and_directories`](https://docs.unique.ai/it-operators/integrations-connectors/outlook-semantic-mcp/outlook-semantic-mcp-technical-reference/outlook-semantic-mcp-tools#list_mailboxes_and_directories) | Mailbox Utilities | Yes | Both |
| [`verify_inbox_connection`](https://docs.unique.ai/it-operators/integrations-connectors/outlook-semantic-mcp/outlook-semantic-mcp-technical-reference/outlook-semantic-mcp-tools#verify_inbox_connection) | Subscription Management | No | Mode A only |
| [`reconnect_inbox`](https://docs.unique.ai/it-operators/integrations-connectors/outlook-semantic-mcp/outlook-semantic-mcp-technical-reference/outlook-semantic-mcp-tools#reconnect_inbox) | Subscription Management | Yes | Mode A only |
| [`delete_inbox_data`](https://docs.unique.ai/it-operators/integrations-connectors/outlook-semantic-mcp/outlook-semantic-mcp-technical-reference/outlook-semantic-mcp-tools#delete_inbox_data) | Subscription Management | Yes | Mode A only |
| [`sync_progress`](https://docs.unique.ai/it-operators/integrations-connectors/outlook-semantic-mcp/outlook-semantic-mcp-technical-reference/outlook-semantic-mcp-tools#sync_progress) | Sync Monitoring | No | Mode A only |
| [`run_full_sync`](https://docs.unique.ai/it-operators/integrations-connectors/outlook-semantic-mcp/outlook-semantic-mcp-technical-reference/outlook-semantic-mcp-tools#run_full_sync) | Full Sync Control (debug only) | Yes | Mode A only |
| [`pause_full_sync`](https://docs.unique.ai/it-operators/integrations-connectors/outlook-semantic-mcp/outlook-semantic-mcp-technical-reference/outlook-semantic-mcp-tools#pause_full_sync) | Full Sync Control (debug only) | Yes | Mode A only |
| [`resume_full_sync`](https://docs.unique.ai/it-operators/integrations-connectors/outlook-semantic-mcp/outlook-semantic-mcp-technical-reference/outlook-semantic-mcp-tools#resume_full_sync) | Full Sync Control (debug only) | Yes | Mode A only |
| [`restart_full_sync`](https://docs.unique.ai/it-operators/integrations-connectors/outlook-semantic-mcp/outlook-semantic-mcp-technical-reference/outlook-semantic-mcp-tools#restart_full_sync) | Full Sync Control (debug only) | Yes | Mode A only |

**Mutating** means the tool writes data to at least one of the following:

- **Outlook mailbox** — creates or modifies data in Microsoft Graph (e.g. a draft email or a webhook subscription)

- **Internal database** — persists or removes state managed by this server (e.g. subscription records, sync state, folder cache)

- **Unique knowledge base** — indexes or removes email content from the knowledge base used for search

| Tool | What it mutates |
| --- | --- |
| `create_draft_email` | Creates a draft message in the user's Outlook mailbox via Microsoft Graph |
| `list_mailboxes_and_directories` | Refreshes the folder cache in the internal database by re-fetching the folder tree from Microsoft Graph |
| `reconnect_inbox` | Creates or renews the Microsoft Graph webhook subscription and writes the subscription record to the internal database |
| `delete_inbox_data` | Cancels the Microsoft Graph webhook subscription and deletes the subscription record, folder cache, root scope, and all ingested email content from the Unique knowledge base |
| `run_full_sync` | Triggers ingestion of all mailbox emails into the Unique knowledge base and updates sync state in the internal database |
| `pause_full_sync` | Updates the sync state to `paused` in the internal database |
| `resume_full_sync` | Updates the sync state to resume ingestion in the internal database |
| `restart_full_sync` | Resets sync state in the internal database and re-triggers full ingestion into the Unique knowledge base |

## Email Search

### `search_emails`

Search emails and return matched passages. The tool behaviour and input schema differ by deployment mode.

**Available in:** Both modes

#### Mode A: `microsoft_graph_and_unique_api`

Runs two searches in parallel — semantic search against the Unique knowledge base and a KQL keyword search against Microsoft Graph — then merges and deduplicates the results. Both query arrays are required and must address the same user question.

**Input parameters:**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `uniqueSemanticSearchQueries` | array (1–10) | Yes | Semantic searches. Compose 2–4 parallel entries that approach the question from different angles. |
| `msGraphKeywordSearchQueries` | array (1–10) | Yes | KQL keyword searches addressing the same question. |

#### Example (Mode A):

```json
{
  "uniqueSemanticSearchQueries": [
    {
      "search": "quarterly report from Alice",
      "conditions": [
        {
          "fromSenders": { "value": "alice@example.com", "operator": "equals" },
          "dateFrom": { "value": "2024-01-01T00:00:00Z", "operator": "greaterThanOrEqual" }
        }
      ],
      "limit": 100
    },
    {
      "search": "Q1 budget summary",
      "conditions": [
        {
          "fromSenders": { "value": "alice@example.com", "operator": "equals" }
        }
      ],
      "limit": 100
    }
  ],
  "msGraphKeywordSearchQueries": [
    {
      "kqlQuery": "from:alice@example.com subject:\"quarterly report\" received>=2024-01-01",
      "limit": 100
    }
  ]
}
```

### Mode B: `microsoft_graph`

Calls the Microsoft Graph Search API directly with KQL queries. No semantic search is performed. Only `msGraphKeywordSearchQueries` is accepted.

**Return shape:**

```typescript
{
  success: boolean;
  message?: string;
  status?: string;
  results?: Array<{
    uniqueContentId?: string;
    msGraphMessageId?: string;
    backend: "Unique" | "MsGraph";
    folderId: string;
    title: string;
    from: string;
    receivedDateTime?: string | null;
    text: string;
    outlookWebLink: string;
    sourceMailbox?: string | null;
    openEmailParams: {
      id: string;
      idType: "Unique" | "MsGraph";
      mailbox?: string;
      parentFolderId?: string;
      idIsImmutable?: boolean;
    };
  }>; // Required fields
}
```}

### `open_email`

Retrieve the full content of an email by its ID returned from `search_emails`.

**Input parameters:**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Email identifier. Use `openEmailParams.id` from a `search_emails` result. |
| `idType` | `