<!-- Generated by `just docs` from catalog/toolkits/microsoft_outlook.yaml, catalog/expansions/microsoft_outlook.yaml, catalog/evals/scorecard.json. Edit the source, not this file. -->

# Microsoft Outlook

Outlook mail on Microsoft 365. Search, read, send, reply to, file, and delete mail, and manage folders, rules, and contacts.

| Property | Value |
| --- | --- |
| Slug | `microsoft_outlook` |
| Definition version | `0.1.0` |
| Base URL | `https://graph.microsoft.com/v1.0` |
| Auth schemes | `oauth2` |
| Action tools | 37 |
| By class | 11 read, 19 write, 7 destructive |
| Triggers | 0 |
| Provider rate limit | not declared, so outbound calls are unpaced |

## Measured routing accuracy

57 golden cases replayed through the router over the whole index: measured over corpus `ea4f12ad2948` (65 toolkits, 2283 tools indexed and 13 declared uncallable), 37 cases written by hand and 20 cases from the paraphrase pass. A case counts as top-1 when its gold tool ranked first and top-8 when it reached the slate at all.

| Measure | Cases | Share |
| --- | --- | --- |
| top-1 | 36/57 | 63.2% |
| top-8 | 53/57 | 93.0% |

The sweep is offline: the reranker is a deterministic identity fake that returns candidates in the order retrieval produced them, so top-1 measures retrieval order rather than a reranked slate. `just eval-live` measures the same cases through the live reranker.

## Authentication

Connect an entity with `ConnectionsService.InitiateConnection`, naming this toolkit's slug. Credentials stay in the connections vault; callers hold connected-account ids only.

### `oauth2`

| Property | Value |
| --- | --- |
| Authorization URL | `https://login.microsoftonline.com/common/oauth2/v2.0/authorize` |
| Token URL | `https://login.microsoftonline.com/common/oauth2/v2.0/token` |
| Default scopes | `Mail.ReadWrite`, `Mail.Send`, `offline_access` |
| Refresh tokens | yes, the refresh daemon renews ahead of expiry |

## Tools

37 action tools. The catalog-wide slug is `microsoft_outlook.<tool>`, which is what `search_tools` returns and `call_tool` takes.

### `microsoft_outlook.search_messages`

Search or list emails in the Outlook or Microsoft 365 mailbox using a keyword search or an OData filter expression. Use when the user wants to find, look up, or check mail in Outlook, not Gmail. Returns message ids and previews, most recent first by default; read one in full with get_message.

Class `read` (reads only). Scopes `Mail.Read`. Calls `GET /me/messages`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `filter` | string | no | Raw OData $filter expression, e.g. "isRead eq false" or "parentFolderId eq 'AAMkAG...'". Cannot be combined with search in the same call; Graph does not support both together. |
| `order_by` | string | no | Raw OData $orderby expression, e.g. "receivedDateTime desc". Ignored when search is set. |
| `search` | string | no | Free-text keyword search over subject and body, e.g. "invoice from Acme". Omit to list without a keyword. |
| `skip` | integer | no | Number of results to skip, for simple pagination. |
| `top` | integer | no | Page size, default 25. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `@odata.nextLink` | string |  |
| `value` | array of object | May be empty when nothing matches. |
| `value[].bodyPreview` | string |  |
| `value[].from` | object |  |
| `value[].from.emailAddress` | object |  |
| `value[].hasAttachments` | boolean |  |
| `value[].id` | string |  |
| `value[].isRead` | boolean |  |
| `value[].parentFolderId` | string |  |
| `value[].receivedDateTime` | string |  |
| `value[].subject` | string |  |

Also retrieved by: "hunt down an email about something in Outlook", "dig through my Outlook inbox for a message", "see if I got anything from someone in my Microsoft mailbox", "pull up mail mentioning a topic in Outlook", "track down that old Exchange email".

### `microsoft_outlook.get_message`

Get one Outlook email's full content by message id: sender, recipients, subject, body, and attachment presence. Use after search_messages to read a specific message in full. For the file itself use list_attachments and get_attachment.

Class `read` (reads only). Scopes `Mail.Read`. Calls `GET /me/messages/{{params.message_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `message_id` | string | **yes** | Outlook message id from search_messages. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `body` | object |  |
| `body.content` | string |  |
| `body.contentType` | string |  |
| `bodyPreview` | string |  |
| `categories` | array of string |  |
| `ccRecipients` | array of object |  |
| `ccRecipients[].emailAddress` | object |  |
| `ccRecipients[].emailAddress.address` | string |  |
| `ccRecipients[].emailAddress.name` | string |  |
| `conversationId` | string |  |
| `from` | object |  |
| `from.emailAddress` | object |  |
| `from.emailAddress.address` | string |  |
| `from.emailAddress.name` | string |  |
| `hasAttachments` | boolean |  |
| `id` | string |  |
| `importance` | string |  |
| `isRead` | boolean |  |
| `parentFolderId` | string |  |
| `receivedDateTime` | string |  |
| `sentDateTime` | string |  |
| `subject` | string |  |
| `toRecipients` | array of object |  |
| `toRecipients[].emailAddress` | object |  |
| `toRecipients[].emailAddress.address` | string |  |
| `toRecipients[].emailAddress.name` | string |  |

Also retrieved by: "pull up that Outlook email and show me what it says", "open it up and let me see the whole thing", "show me everything that message contains".

### `microsoft_outlook.list_attachments`

List the attachments on one Outlook email by message id: name, type, and size, but not the file bytes. Use to see what is attached before downloading. Download one with get_attachment.

Class `read` (reads only). Scopes `Mail.Read`. Calls `GET /me/messages/{{params.message_id}}/attachments`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `message_id` | string | **yes** | Message holding the attachments. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `value` | array of object |  |
| `value[].contentType` | string |  |
| `value[].id` | string |  |
| `value[].isInline` | boolean |  |
| `value[].name` | string |  |
| `value[].size` | integer |  |

Also retrieved by: "what did they attach to that Outlook email", "see what files came with that message", "check if this one has anything attached".

### `microsoft_outlook.get_attachment`

Download one email attachment's file content by message id and attachment id. Use when the user wants the actual file, PDF, image, or invoice from an Outlook message. Attachment ids come from list_attachments. Returns base64-encoded bytes.

Class `read` (reads only). Scopes `Mail.Read`. Calls `GET /me/messages/{{params.message_id}}/attachments/{{params.attachment_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `attachment_id` | string | **yes** | Attachment id from list_attachments. |
| `message_id` | string | **yes** | Message holding the attachment. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `contentBytes` | string | Base64-encoded file bytes. |
| `contentType` | string |  |
| `name` | string |  |
| `size` | integer |  |

Also retrieved by: "grab the file they sent me in Outlook", "save that attachment to my computer", "pull down the PDF from that email", "fetch the file that was attached".

### `microsoft_outlook.send_mail`

Send a new Outlook email immediately to one or more recipients. Use when the user wants to email, message, or write to someone fresh, not reply to something existing. Irreversible once sent; confirm recipients first. To save without sending use create_draft; to answer an existing email use reply_to_message.

Class `write` (writes, no confirmation needed). Scopes `Mail.Send`. Calls `POST /me/sendMail`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `bcc_recipients` | array of object | no |  |
| `bcc_recipients[].emailAddress` | object | no |  |
| `bcc_recipients[].emailAddress.address` | string | no |  |
| `bcc_recipients[].emailAddress.name` | string | no |  |
| `body_content` | string | **yes** | The message body. |
| `body_content_type` | string, one of Text, HTML | no | Format of body_content. Default Text. |
| `cc_recipients` | array of object | no |  |
| `cc_recipients[].emailAddress` | object | no |  |
| `cc_recipients[].emailAddress.address` | string | no |  |
| `cc_recipients[].emailAddress.name` | string | no |  |
| `save_to_sent_items` | boolean | no | Keep a copy in Sent Items. Default true. |
| `subject` | string | **yes** | Email subject line. |
| `to_recipients` | array of object | **yes** | Recipients, shaped like Graph's own recipient object, e.g. [{"emailAddress": {"address": "amy@example.com"}}]. |
| `to_recipients[].emailAddress` | object | **yes** |  |
| `to_recipients[].emailAddress.address` | string | **yes** |  |
| `to_recipients[].emailAddress.name` | string | no |  |

Also retrieved by: "fire off a message to someone in Outlook", "shoot them a quick note through Microsoft mail", "get a message out to them with the details", "ping them over Outlook with an update", "drop them a line about something".

### `microsoft_outlook.create_draft`

Save a new Outlook email as a draft without sending it. Use when the user wants to compose, start, or stash a message for later. Returns a draft id for update_draft or send_draft. To send right away use send_mail instead.

Class `write` (writes, no confirmation needed). Scopes `Mail.ReadWrite`. Calls `POST /me/messages`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `body_content` | string | **yes** | The message body. |
| `body_content_type` | string, one of Text, HTML | no | Format of body_content. Default Text. |
| `cc_recipients` | array of object | no |  |
| `cc_recipients[].emailAddress` | object | no |  |
| `cc_recipients[].emailAddress.address` | string | no |  |
| `cc_recipients[].emailAddress.name` | string | no |  |
| `subject` | string | **yes** | Email subject line. |
| `to_recipients` | array of object | no |  |
| `to_recipients[].emailAddress` | object | no |  |
| `to_recipients[].emailAddress.address` | string | no |  |
| `to_recipients[].emailAddress.name` | string | no |  |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `conversationId` | string |  |
| `id` | string |  |
| `isDraft` | boolean |  |
| `subject` | string |  |
| `webLink` | string |  |

Also retrieved by: "start writing something in Outlook I'm not ready to send yet", "stash a message for later without sending it", "jot down a note I'll finish later", "put together something I can review first".

### `microsoft_outlook.update_draft`

Edit an existing Outlook draft's subject, body, or recipients by message id. Use when the user revises or fixes something they haven't sent yet. Only affects unsent drafts; a sent message cannot be edited this way.

Class `write` (writes, no confirmation needed). Scopes `Mail.ReadWrite`. Calls `PATCH /me/messages/{{params.message_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `body_content` | string | no | New message body, replacing the old one. |
| `body_content_type` | string, one of Text, HTML | no |  |
| `message_id` | string | **yes** | Draft to update. |
| `subject` | string | no | New subject line. |
| `to_recipients` | array of object | no |  |
| `to_recipients[].emailAddress` | object | no |  |
| `to_recipients[].emailAddress.address` | string | no |  |
| `to_recipients[].emailAddress.name` | string | no |  |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string |  |
| `isDraft` | boolean |  |
| `subject` | string |  |

Also retrieved by: "fix up that unsent Outlook message", "change what I wrote before I send it", "edit the note I haven't sent yet".

### `microsoft_outlook.send_draft`

Send an existing saved Outlook draft as-is by message id. Use when a draft is ready and the user says to go ahead and send it. Irreversible. If the draft is missing recipients, fix it first with update_draft.

Class `write` (writes, no confirmation needed). Scopes `Mail.Send`. Calls `POST /me/messages/{{params.message_id}}/send`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `message_id` | string | **yes** | Draft to send, as returned by create_draft. |

Also retrieved by: "go ahead and fire that off", "ship the message I saved earlier", "that one's ready, send it now", "push out the note I put together".

### `microsoft_outlook.reply_to_message`

Reply to the sender of one Outlook email, keeping it inside the same conversation. Use when the user wants to answer, respond, or write back to just the original sender. For everyone on the thread use reply_all_to_message; for a brand-new email use send_mail.

Class `write` (writes, no confirmation needed). Scopes `Mail.Send`. Calls `POST /me/messages/{{params.message_id}}/reply`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `comment` | string | **yes** | The reply text, added above the quoted original. |
| `message_id` | string | **yes** | Message to reply to. |

Also retrieved by: "write back to just the sender on this Outlook email", "answer them directly on this message", "respond to what they said, not the whole group", "get back to them on this one".

### `microsoft_outlook.reply_all_to_message`

Reply to everyone on an Outlook email, sender and all other recipients, inside the same conversation. Use when the user wants to answer the whole group, not just one person. For only the original sender use reply_to_message.

Class `write` (writes, no confirmation needed). Scopes `Mail.Send`. Calls `POST /me/messages/{{params.message_id}}/replyAll`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `comment` | string | **yes** | The reply text, added above the quoted original. |
| `message_id` | string | **yes** | Message to reply to. |

Also retrieved by: "answer everyone on this Outlook email", "respond to the whole group on this message", "write back to everyone included on this one", "get back to the entire group here".

### `microsoft_outlook.forward_message`

Forward an existing Outlook email to new recipients, optionally with a short note. Use when the user wants to pass a message, share it, or send it along to someone else. For a reply within the same conversation use reply_to_message.

Class `write` (writes, no confirmation needed). Scopes `Mail.Send`. Calls `POST /me/messages/{{params.message_id}}/forward`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `comment` | string | no | Short note added above the forwarded message. |
| `message_id` | string | **yes** | Message to forward. |
| `to_recipients` | array of object | **yes** | Recipients, shaped like Graph's own recipient object, e.g. [{"emailAddress": {"address": "amy@example.com"}}]. |
| `to_recipients[].emailAddress` | object | **yes** |  |
| `to_recipients[].emailAddress.address` | string | **yes** |  |
| `to_recipients[].emailAddress.name` | string | no |  |

Also retrieved by: "pass this Outlook email along to someone else", "share this message with another person", "send this one along with a quick note", "route this email to someone new".

### `microsoft_outlook.move_message`

Move an Outlook email into a different mail folder by id or well-known name (inbox, archive, junkemail, drafts, sentitems). Use when the user wants to file, sort, or relocate a message. To send an email to the trash specifically use trash_message.

Class `write` (writes, no confirmation needed). Scopes `Mail.ReadWrite`. Calls `POST /me/messages/{{params.message_id}}/move`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `destination_folder_id` | string | **yes** | Target folder id from list_mail_folders, or a well-known name such as "archive" or "junkemail". |
| `message_id` | string | **yes** | Message to move. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string | The message's new id in the destination folder. |
| `parentFolderId` | string |  |

Also retrieved by: "file this Outlook email into a different folder", "sort this message somewhere else", "relocate this email out of the inbox", "put this one into another folder".

### `microsoft_outlook.copy_message`

Copy an Outlook email into another mail folder, leaving the original in place. Use when the user wants a message filed in two places at once. For a one-way move use move_message instead.

Class `write` (writes, no confirmation needed). Scopes `Mail.ReadWrite`. Calls `POST /me/messages/{{params.message_id}}/copy`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `destination_folder_id` | string | **yes** | Target folder id from list_mail_folders, or a well-known name such as "archive" or "junkemail". |
| `message_id` | string | **yes** | Message to copy. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string | The new copy's id in the destination folder. |
| `parentFolderId` | string |  |

Also retrieved by: "duplicate this Outlook email into another folder", "keep a copy of this message somewhere else too", "file this in two places at once".

### `microsoft_outlook.trash_message`

Move an Outlook email to the Deleted Items folder. Use when the user wants to trash, bin, or get rid of a message. Recoverable from Deleted Items until it is emptied or purged; for a permanent, unrecoverable removal use delete_message.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `Mail.ReadWrite`. Calls `POST /me/messages/{{params.message_id}}/move`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `message_id` | string | **yes** | Message to move to Deleted Items. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string |  |
| `parentFolderId` | string |  |

Also retrieved by: "bin that Outlook email", "toss this message out", "chuck it in the Outlook trash", "send it to Deleted Items".

### `microsoft_outlook.delete_message`

Permanently remove an Outlook email, bypassing recovery through Deleted Items. Unrecoverable; prefer trash_message when the user might still want it back. Use only when the user explicitly asks for a message gone for good.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `Mail.ReadWrite`. Calls `DELETE /me/messages/{{params.message_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `message_id` | string | **yes** | Message to delete permanently. |

Also retrieved by: "wipe that Outlook email for good", "nuke this message completely", "scrub it from my mailbox entirely", "erase it permanently, no recovering it".

### `microsoft_outlook.delete_draft`

Permanently discard a saved Outlook draft by message id. Not recoverable; only removes unsent drafts, never sent or received mail. Verify the draft id before calling.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `Mail.ReadWrite`. Calls `DELETE /me/messages/{{params.message_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `message_id` | string | **yes** | Draft to discard. |

Also retrieved by: "toss that unsent Outlook message", "get rid of the one I started", "scrap what I was writing".

### `microsoft_outlook.mark_message_read`

Mark one Outlook email as read or unread by message id. Use when the user wants to flag something as seen, catch up on, or leave unread for later. For adding a follow-up flag use flag_message instead.

Class `write` (writes, no confirmation needed). Scopes `Mail.ReadWrite`. Calls `PATCH /me/messages/{{params.message_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `is_read` | boolean | **yes** | true to mark read, false to mark unread. |
| `message_id` | string | **yes** | Message to update. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string |  |
| `isRead` | boolean |  |

Also retrieved by: "flag this Outlook email as unread again", "I've already seen that one, take it off my unread list", "mark it as seen", "leave this one unread for later".

### `microsoft_outlook.flag_message`

Set, clear, or complete the follow-up flag on an Outlook email. Use when the user wants to flag, star, or mark a message as done. For read/unread status use mark_message_read.

Class `write` (writes, no confirmation needed). Scopes `Mail.ReadWrite`. Calls `PATCH /me/messages/{{params.message_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `flag_status` | string, one of notFlagged, flagged, complete | **yes** | Desired flag state. |
| `message_id` | string | **yes** | Message to flag. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `flag` | object |  |
| `flag.flagStatus` | string |  |
| `id` | string |  |

Also retrieved by: "put a follow-up flag on this Outlook email", "star this message so I remember it", "mark this one as done, take the flag off", "remind myself to come back to this".

### `microsoft_outlook.categorize_message`

Assign or clear the color categories on one Outlook email, replacing its full category list. Use when the user wants to color-code, tag, or label a message. Category names come from list_categories.

Class `write` (writes, no confirmation needed). Scopes `Mail.ReadWrite`. Calls `PATCH /me/messages/{{params.message_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `categories` | array of string | **yes** | Complete replacement list of category names, e.g. ["Red Category"]. Pass an empty array to clear all categories. |
| `message_id` | string | **yes** | Message to update. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `categories` | array of string |  |
| `id` | string |  |

Also retrieved by: "color-code this Outlook email", "tag this message with a category", "label this one so I can find it later", "clear the tags off this email".

### `microsoft_outlook.list_mail_folders`

List the top-level mail folders in the Outlook mailbox: inbox, sent items, drafts, and any custom folders, with unread and total counts. Use when the user asks what folders exist. Resolve a folder's id here before other folder tools.

Class `read` (reads only). Scopes `Mail.Read`. Calls `GET /me/mailFolders`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `top` | integer | no | Page size, default 25. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `value` | array of object |  |
| `value[].childFolderCount` | integer |  |
| `value[].displayName` | string |  |
| `value[].id` | string |  |
| `value[].parentFolderId` | string |  |
| `value[].totalItemCount` | integer |  |
| `value[].unreadItemCount` | integer |  |

Also retrieved by: "what folders do I have set up in Outlook", "show me my Outlook mailbox structure", "what are all my mail folders called".

### `microsoft_outlook.get_mail_folder`

Get one Outlook mail folder's details by folder id: name, parent, and message counts. Use list_mail_folders first to resolve the id.

Class `read` (reads only). Scopes `Mail.Read`. Calls `GET /me/mailFolders/{{params.folder_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `folder_id` | string | **yes** | Folder id from list_mail_folders. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `childFolderCount` | integer |  |
| `displayName` | string |  |
| `id` | string |  |
| `parentFolderId` | string |  |
| `totalItemCount` | integer |  |
| `unreadItemCount` | integer |  |

Also retrieved by: "how many unread messages are in that Outlook folder", "what's the count on this folder", "how many emails are filed under this one".

### `microsoft_outlook.create_mail_folder`

Create a new top-level mail folder in Outlook. Use when the user wants a new folder for organizing mail. Returns the folder id other tools need.

Class `write` (writes, no confirmation needed). Scopes `Mail.ReadWrite`. Calls `POST /me/mailFolders`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `display_name` | string | **yes** | Folder name, e.g. "Receipts". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `displayName` | string |  |
| `id` | string |  |

Also retrieved by: "set up a new folder for my Outlook mail", "make a new place to sort messages", "start a new mail folder".

### `microsoft_outlook.rename_mail_folder`

Rename an existing Outlook mail folder by folder id. Use when the user wants to rename or relabel a folder, not a category.

Class `write` (writes, no confirmation needed). Scopes `Mail.ReadWrite`. Calls `PATCH /me/mailFolders/{{params.folder_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `display_name` | string | **yes** | New folder name. |
| `folder_id` | string | **yes** | Folder to rename. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `displayName` | string |  |
| `id` | string |  |

Also retrieved by: "give that Outlook folder a new name", "change what this folder is called", "relabel this mail folder".

### `microsoft_outlook.delete_mail_folder`

Permanently delete an Outlook mail folder and every message inside it. Unrecoverable; the messages are removed along with the folder. Verify the folder id and its contents first.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `Mail.ReadWrite`. Calls `DELETE /me/mailFolders/{{params.folder_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `folder_id` | string | **yes** | Folder to delete. |

Also retrieved by: "get rid of that Outlook folder for good", "remove this mail folder, I don't need it anymore", "delete this folder entirely".

### `microsoft_outlook.list_inbox_rules`

List the automatic inbox rules configured on the Outlook mailbox: what each rule matches and what it does. Use when the user asks what rules or filters are set up.

Class `read` (reads only). Scopes `MailboxSettings.Read`. Calls `GET /me/mailFolders/inbox/messageRules`.

Takes no arguments.

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `value` | array of object |  |
| `value[].displayName` | string |  |
| `value[].id` | string |  |
| `value[].isEnabled` | boolean |  |
| `value[].sequence` | integer |  |

Also retrieved by: "what automatic mail rules do I have set up", "show me my Outlook filters", "what's set up to auto-sort my incoming mail".

### `microsoft_outlook.create_inbox_rule`

Create a new inbox rule that automatically moves, flags, or deletes incoming Outlook mail matching a condition. Use when the user wants mail sorted, filtered, or auto-processed as it arrives.

Class `write` (writes, no confirmation needed). Scopes `MailboxSettings.ReadWrite`. Calls `POST /me/mailFolders/inbox/messageRules`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `actions` | object | **yes** | Graph messageRule actions object, e.g. {"moveToFolder": "AAMkAG...", "markAsRead": true, "stopProcessingRules": true}. |
| `conditions` | object | **yes** | Graph messageRule conditions object, e.g. {"subjectContains": ["invoice"]} or {"fromAddresses": [{"emailAddress": {"address": "billing@vendor.com"}}]}. |
| `display_name` | string | **yes** | Name for the rule, e.g. "File newsletters". |
| `is_enabled` | boolean | no | Whether the rule is active. Default true. |
| `sequence` | integer | no | Run order relative to other rules. Lower runs first. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `displayName` | string |  |
| `id` | string |  |
| `isEnabled` | boolean |  |

Also retrieved by: "set up a filter for incoming Outlook mail", "make incoming messages sort themselves automatically", "build a rule to handle mail as it arrives".

### `microsoft_outlook.update_inbox_rule`

Change an existing Outlook inbox rule's conditions, actions, or enabled state by rule id. Use when the user wants to edit, fix, or turn off a mail rule.

Class `write` (writes, no confirmation needed). Scopes `MailboxSettings.ReadWrite`. Calls `PATCH /me/mailFolders/inbox/messageRules/{{params.rule_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `actions` | object | no | Replacement Graph messageRule actions object. |
| `conditions` | object | no | Replacement Graph messageRule conditions object. |
| `display_name` | string | no | New name for the rule. |
| `is_enabled` | boolean | no | Whether the rule stays active. |
| `rule_id` | string | **yes** | Rule to update, from list_inbox_rules. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `displayName` | string |  |
| `id` | string |  |
| `isEnabled` | boolean |  |

Also retrieved by: "fix that Outlook mail filter", "change what this automatic rule does", "turn off that mail sorting rule".

### `microsoft_outlook.delete_inbox_rule`

Permanently remove an Outlook inbox rule by rule id. Use when the user wants a mail rule gone; incoming mail stops being auto-processed by it.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `MailboxSettings.ReadWrite`. Calls `DELETE /me/mailFolders/inbox/messageRules/{{params.rule_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `rule_id` | string | **yes** | Rule to delete, from list_inbox_rules. |

Also retrieved by: "get rid of that automatic mail filter", "remove this incoming-mail rule for good", "stop this filter from running".

### `microsoft_outlook.list_categories`

List the master color category list for the Outlook mailbox: every category name and its color. Use when the user asks what tags or categories exist. Apply one to a message with categorize_message.

Class `read` (reads only). Scopes `MailboxSettings.Read`. Calls `GET /me/outlook/masterCategories`.

Takes no arguments.

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `value` | array of object |  |
| `value[].color` | string |  |
| `value[].displayName` | string |  |
| `value[].id` | string |  |

Also retrieved by: "what color tags do I have set up in Outlook", "show me my Outlook labels", "what categories exist in my mailbox".

### `microsoft_outlook.create_category`

Add a new color category to the Outlook master category list. Use when the user wants a new tag or label option before applying it to messages.

Class `write` (writes, no confirmation needed). Scopes `MailboxSettings.ReadWrite`. Calls `POST /me/outlook/masterCategories`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `color` | string | **yes** | Preset color id, e.g. "preset0" (red) through "preset24". |
| `display_name` | string | **yes** | Category name, e.g. "Follow Up". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `color` | string |  |
| `displayName` | string |  |
| `id` | string |  |

Also retrieved by: "set up a new color tag in Outlook", "make a new label option for messages", "start a new category for my mail".

### `microsoft_outlook.delete_category`

Permanently remove a color category from the Outlook master list, clearing it from every message that had it. Use when the user wants a category or tag gone for good.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `MailboxSettings.ReadWrite`. Calls `DELETE /me/outlook/masterCategories/{{params.category_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `category_id` | string | **yes** | Category to delete, from list_categories. |

Also retrieved by: "get rid of that Outlook tag for good", "remove this color label, I don't need it anymore", "delete this category entirely".

### `microsoft_outlook.list_contacts`

List or search people in the Outlook contacts list. Use when the user asks who is in their contacts or wants to find someone's saved details. Returns names and email addresses; get one in full with get_contact.

Class `read` (reads only). Scopes `Contacts.Read`. Calls `GET /me/contacts`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `search` | string | no | Free-text search over name, company, and email address, e.g. "Priya" or "acme.com". |
| `top` | integer | no | Page size, default 25. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `value` | array of object |  |
| `value[].companyName` | string |  |
| `value[].displayName` | string |  |
| `value[].emailAddresses` | array of object |  |
| `value[].emailAddresses[].address` | string |  |
| `value[].emailAddresses[].name` | string |  |
| `value[].id` | string |  |

Also retrieved by: "who is saved in my Outlook contacts", "look someone up in my address book", "find a saved email address in Outlook".

### `microsoft_outlook.get_contact`

Get one Outlook contact's full details by contact id: name, email addresses, phone numbers, and company. Use list_contacts first to resolve the id.

Class `read` (reads only). Scopes `Contacts.Read`. Calls `GET /me/contacts/{{params.contact_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `contact_id` | string | **yes** | Contact id from list_contacts. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `businessPhones` | array of string |  |
| `companyName` | string |  |
| `displayName` | string |  |
| `emailAddresses` | array of object |  |
| `emailAddresses[].address` | string |  |
| `emailAddresses[].name` | string |  |
| `id` | string |  |
| `mobilePhone` | string |  |

Also retrieved by: "pull up that person's full details in Outlook", "show me everything saved about this contact", "what's their phone number and company".

### `microsoft_outlook.create_contact`

Add a new person to the Outlook contacts list. Use when the user wants to save someone's email address or details for later.

Class `write` (writes, no confirmation needed). Scopes `Contacts.ReadWrite`. Calls `POST /me/contacts`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `business_phones` | array of string | no |  |
| `company_name` | string | no | Employer or organization. |
| `email_addresses` | array of object | no |  |
| `email_addresses[].address` | string | **yes** |  |
| `email_addresses[].name` | string | no |  |
| `given_name` | string | **yes** | First name. |
| `surname` | string | no | Last name. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `displayName` | string |  |
| `id` | string |  |

Also retrieved by: "save this person's email in Outlook", "add someone new to my address book", "keep this person's details on file".

### `microsoft_outlook.delete_contact`

Permanently remove a person from the Outlook contacts list by contact id. Unrecoverable; verify the contact id before calling.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `Contacts.ReadWrite`. Calls `DELETE /me/contacts/{{params.contact_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `contact_id` | string | **yes** | Contact to delete, from list_contacts. |

Also retrieved by: "remove that person from my Outlook contacts", "get rid of this saved contact for good", "take them out of my address book".

### `microsoft_outlook.get_automatic_replies_settings`

Check whether the Outlook automatic-reply (out-of-office) responder is currently on, and read its scheduled window and messages. Use when the user asks if they are set to out of office. To change it use set_automatic_replies.

Class `read` (reads only). Scopes `MailboxSettings.Read`. Calls `GET /me/mailboxSettings`.

Takes no arguments.

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `automaticRepliesSetting` | object |  |
| `automaticRepliesSetting.externalAudience` | string |  |
| `automaticRepliesSetting.externalReplyMessage` | string |  |
| `automaticRepliesSetting.internalReplyMessage` | string |  |
| `automaticRepliesSetting.scheduledEndDateTime` | object |  |
| `automaticRepliesSetting.scheduledEndDateTime.dateTime` | string |  |
| `automaticRepliesSetting.scheduledEndDateTime.timeZone` | string |  |
| `automaticRepliesSetting.scheduledStartDateTime` | object |  |
| `automaticRepliesSetting.scheduledStartDateTime.dateTime` | string |  |
| `automaticRepliesSetting.scheduledStartDateTime.timeZone` | string |  |
| `automaticRepliesSetting.status` | string |  |

Also retrieved by: "am I set to out of office right now", "check if my Outlook auto-reply is on", "is my vacation responder turned on".

### `microsoft_outlook.set_automatic_replies`

Turn Outlook's automatic-reply (out-of-office) responder on or off and set its scheduled window and reply text. Use when the user wants to set, schedule, or cancel an out-of-office message.

Class `write` (writes, no confirmation needed). Scopes `MailboxSettings.ReadWrite`. Calls `PATCH /me/mailboxSettings`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `external_audience` | string, one of none, contactsOnly, all | no | Who outside the org gets the external reply. |
| `external_reply_message` | string | no | Reply text shown to people outside the organization. |
| `internal_reply_message` | string | no | Reply text shown to people inside the organization. |
| `scheduled_end` | string | no | RFC 3339 end time. Required when status is scheduled. |
| `scheduled_start` | string | no | RFC 3339 start time. Required when status is scheduled. |
| `status` | string, one of disabled, alwaysEnabled, scheduled | **yes** | disabled turns the responder off; alwaysEnabled leaves it on indefinitely; scheduled uses the start and end times below. |
| `time_zone` | string | no | IANA time zone for scheduled_start/scheduled_end. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `automaticRepliesSetting` | object |  |
| `automaticRepliesSetting.externalAudience` | string |  |
| `automaticRepliesSetting.status` | string |  |

Also retrieved by: "turn on my out-of-office message", "schedule my vacation responder for next week", "turn off my automatic reply in Outlook".