Skip to main content
Glama
Microsoft 365 MCP Server

Microsoft 365 MCP Server

by Softeria

update-mailbox-settings

update-mailbox-settings
Destructive

Configure Microsoft 365 mailbox settings, including out-of-office replies, time zones, date/time formats, and working hours. Enable, schedule, or disable automatic replies as needed.

Instructions

Enable, configure, or disable one or more of the following settings as part of a user's mailboxSettings: When updating the preferred date or time format for a user, specify it in respectively, the short date or short time format. When updating the preferred time zone for a user, specify it in the Windows or Internet Assigned Numbers Authority (IANA) time zone (also known as Olson time zone) format. You can also further customize the time zone as shown in example 2 below.

šŸ’” TIP: Updates mailbox settings. Common use: configure Out-of-Office (automatic replies). Body example: { automaticRepliesSetting: { status: 'scheduled', scheduledStartDateTime: { dateTime: '2026-03-28T17:00:00', timeZone: 'Eastern Standard Time' }, scheduledEndDateTime: { dateTime: '2026-04-01T08:00:00', timeZone: 'Eastern Standard Time' }, internalReplyMessage: 'I am OOO.', externalReplyMessage: 'I am out of office.' } }. Status values: disabled, alwaysEnabled, scheduled.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "body": "<body>"
    },
    "name": "update-mailbox-settings"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyYes
confirmNoFor destructive operations when the confirm gate is enabled (MS365_MCP_REQUIRE_CONFIRM=true; off by default). Set to true only after the user has explicitly approved this action. When the gate is on, calls without confirm: true return { error: "confirmation_required" } without touching user data.
includeHeadersNoInclude response headers (including ETag) in the response metadata
excludeResponseNoExclude the full response body and only return success or failure indication

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.176.1
    • removedInput schema / properties / body / properties / workingHours / properties / endTime / description
      Removed value: -"The time of the day that the user stops working."
    • removedInput schema / properties / body / properties / workingHours / properties / startTime / description
      Removed value: -"The time of the day that the user starts working."
  2. Changed9 schema fields changedv0.145.2
    • removedInput schema / $defs
      Removed value: -{
      -  "def0": {
      -    "additionalProperties": true,
      -    "properties": {
      -      "dateTime": {
      -        "description": "A single point of time in a combined date and time representation ({date}T{time}; for example, 2017-08-29T04:00:00.0000000).",
      -        "type": "string"
      -      },
      -      "timeZone": {
      -        "description": "Represents a time zone, for example, 'Pacific Standard Time'. See below for more possible values.",
      -        "type": [
      -          "string",
      -          "null"
      -        ]
      -      }
      -    },
      -    "type": "object"
      -  }
      -}
    • removedInput schema / properties / body / properties / automaticRepliesSetting / properties / scheduledEndDateTime / $ref
      Removed value: -"#/$defs/def0"
    • addedInput schema / properties / body / properties / automaticRepliesSetting / properties / scheduledEndDateTime / additionalProperties
      Added value: +true
    • addedInput schema / properties / body / properties / automaticRepliesSetting / properties / scheduledEndDateTime / properties
      Added value: +{
      +  "dateTime": {
      +    "description": "A single point of time in a combined date and time representation ({date}T{time}; for example, 2017-08-29T04:00:00.0000000).",
      +    "type": "string"
      +  },
      +  "timeZone": {
      +    "description": "Represents a time zone, for example, 'Pacific Standard Time'. See below for more possible values.",
      +    "type": [
      +      "string",
      +      "null"
      +    ]
      +  }
      +}
    • addedInput schema / properties / body / properties / automaticRepliesSetting / properties / scheduledEndDateTime / type
      Added value: +"object"
    • removedInput schema / properties / body / properties / automaticRepliesSetting / properties / scheduledStartDateTime / $ref
      Removed value: -"#/$defs/def0"
    • addedInput schema / properties / body / properties / automaticRepliesSetting / properties / scheduledStartDateTime / additionalProperties
      Added value: +true
    • addedInput schema / properties / body / properties / automaticRepliesSetting / properties / scheduledStartDateTime / properties
      Added value: +{
      +  "dateTime": {
      +    "description": "A single point of time in a combined date and time representation ({date}T{time}; for example, 2017-08-29T04:00:00.0000000).",
      +    "type": "string"
      +  },
      +  "timeZone": {
      +    "description": "Represents a time zone, for example, 'Pacific Standard Time'. See below for more possible values.",
      +    "type": [
      +      "string",
      +      "null"
      +    ]
      +  }
      +}
    • addedInput schema / properties / body / properties / automaticRepliesSetting / properties / scheduledStartDateTime / type
      Added value: +"object"
  3. Addedv0.134.4
  4. Removedv0.131.2
  5. Changed1 schema field changedv0.131.1
    • addedInput schema / properties / confirm
      Added value: +{
      +  "description": "For destructive operations when the confirm gate is enabled (MS365_MCP_REQUIRE_CONFIRM=true; off by default). Set to true only after the user has explicitly approved this action. When the gate is on, calls without confirm: true return { error: \"confirmation_required\" } without touching user data.",
      +  "type": "boolean"
      +}
  6. Addedv0.114.0
  7. Removedv0.112.2
  8. Addedv0.110.0
  9. Removedv0.108.0
  10. Addedv0.96.0

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered structurally. The description adds format constraints and enum-visible status values but does not disclose the critical PATCH semantics (whether omitted fields like workingHours or language are preserved or cleared) or which mailbox is targeted — no user identifier exists in the schema, yet the text says "a user's mailboxSettings" ambiguously.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Length is reasonable (~110 words) and the OOO example is the most useful part, but structure is poor: the first sentence ends in a colon with no list, and the TIP restates the purpose already given. The date/time-format sentences read as paste from external docs and sit awkwardly before the actionable example.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, deeply nested settings updater with no output schema, the definition should explain update/merge behavior, target mailbox scope, and that the confirm gate may be required. It covers the headline use case and field formats well, but those behavioral gaps leave an agent unable to predict the effect of a partial body.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 75%, which sets a baseline of 3, and the description genuinely adds above that: it specifies that dateFormat/timeFormat use short date/short time formats, that timeZone accepts Windows or IANA/Olson names, and it supplies a full automaticRepliesSetting body example with nested dateTime/timeZone structure. The value is slightly undercut by the garbled "specify it in respectively, the short date or short time format" phrasing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening states a specific verb set ("Enable, configure, or disable") against a named resource ("mailboxSettings"), and the TIP reinforces it as "Updates mailbox settings." It never distinguishes itself from the sibling get-mailbox-settings (read vs. write), and the trailing colon leaves the promised settings list empty, so the purpose is clear but not fully sharpened against siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The TIP gives one concrete common use (configuring Out-of-Office with a scheduled window) and the prose gives format expectations for dateFormat, timeFormat and timeZone. There is no guidance on when not to use it, no instruction to read current values first via get-mailbox-settings, and no mention of the sibling list-supported-time-zones for valid time-zone names.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools