Microsoft 365 MCP Server

create-contact-folder

create-contact-folder

Destructive

Creates a new contact folder under the default contacts folder or a specified parent folder to organize contacts.

Instructions

Create a new contactFolder under the user's default contacts folder. You can also create a new contactfolder as a child of any specified contact folder.

💡 TIP: Creates a new contact folder under the user's mailbox root. Body: { displayName: 'Family' }. Returns the created contactFolder with its id. To create a sub-folder under an existing folder, use create-contact-child-folder.

Input Schema

Name	Required	Description
`body`	Yes
`confirm`	No	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.
`includeHeaders`	No	Include response headers (including ETag) in the response metadata
`excludeResponse`	No	Exclude the full response body and only return success or failure indication

Schema Changelog

Changes observed during successful MCP inspections.

Changed44 schema fields changedv0.176.1Oct 29, 2026

changedInput schema / $defs / def0 / properties / multiValueExtendedProperties / items / $ref
```
Previous value: -"#/$defs/def3"New value: +"#/$defs/def5"
```

removedInput schema / $defs / def1 / properties / birthday / description

Removed value: -"The contact's birthday. The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z"

changedInput schema / $defs / def1 / properties / businessAddress / $ref
```
Previous value: -"#/$defs/def2"New value: +"#/$defs/def8"
```
addedInput schema / $defs / def1 / properties / businessPhones / items / $ref
```
Added value: +"#/$defs/def9"
```
removedInput schema / $defs / def1 / properties / businessPhones / items / type
```
Removed value: -[
-  "string",
-  "null"
-]
```
addedInput schema / $defs / def1 / properties / categories / items / $ref
```
Added value: +"#/$defs/def7"
```
removedInput schema / $defs / def1 / properties / categories / items / type
```
Removed value: -[
-  "string",
-  "null"
-]
```
addedInput schema / $defs / def1 / properties / children / items / $ref
```
Added value: +"#/$defs/def10"
```
removedInput schema / $defs / def1 / properties / children / items / type
```
Removed value: -[
-  "string",
-  "null"
-]
```

removedInput schema / $defs / def1 / properties / createdDateTime / description

Removed value: -"The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z"

addedInput schema / $defs / def1 / properties / emailAddresses / items / $ref
```
Added value: +"#/$defs/def11"
```
removedInput schema / $defs / def1 / properties / emailAddresses / items / additionalProperties
```
Removed value: -true
```

removedInput schema / $defs / def1 / properties / emailAddresses / items / properties

Removed value: -{
-  "address": {
-    "description": "The email address of the person or entity.",
-    "type": [
-      "string",
-      "null"
-    ]
-  },
-  "name": {
-    "description": "The display name of the person or entity.",
-    "type": [
-      "string",
-      "null"
-    ]
-  }
-}

removedInput schema / $defs / def1 / properties / emailAddresses / items / type
```
Removed value: -"object"
```
changedInput schema / $defs / def1 / properties / homeAddress / $ref
```
Previous value: -"#/$defs/def2"New value: +"#/$defs/def8"
```
addedInput schema / $defs / def1 / properties / homePhones / items / $ref
```
Added value: +"#/$defs/def2"
```
removedInput schema / $defs / def1 / properties / homePhones / items / type
```
Removed value: -[
-  "string",
-  "null"
-]
```
addedInput schema / $defs / def1 / properties / imAddresses / items / $ref
```
Added value: +"#/$defs/def3"
```
removedInput schema / $defs / def1 / properties / imAddresses / items / type
```
Removed value: -[
-  "string",
-  "null"
-]
```

removedInput schema / $defs / def1 / properties / lastModifiedDateTime / description

Removed value: -"The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z"

changedInput schema / $defs / def1 / properties / multiValueExtendedProperties / items / $ref
```
Previous value: -"#/$defs/def3"New value: +"#/$defs/def5"
```

addedInput schema / $defs / def10

Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedInput schema / $defs / def11

Added value: +{
+  "additionalProperties": true,
+  "properties": {
+    "address": {
+      "description": "The email address of the person or entity.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "name": {
+      "description": "The display name of the person or entity.",
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "type": "object"
+}

addedInput schema / $defs / def12
```
Added value: +{
+  "type": "boolean"
+}
```
addedInput schema / $defs / def13
```
Added value: +{
+  "type": "boolean"
+}
```
addedInput schema / $defs / def14
```
Added value: +{
+  "type": "boolean"
+}
```
removedInput schema / $defs / def2 / additionalProperties
```
Removed value: -true
```

removedInput schema / $defs / def2 / properties

Removed value: -{
-  "city": {
-    "description": "The city.",
-    "type": [
-      "string",
-      "null"
-    ]
-  },
-  "countryOrRegion": {
-    "description": "The country or region. It's a free-format string value, for example, 'United States'.",
-    "type": [
-      "string",
-      "null"
-    ]
-  },
-  "postalCode": {
-    "description": "The postal code.",
-    "type": [
-      "string",
-      "null"
-    ]
-  },
-  "state": {
-    "description": "The state.",
-    "type": [
-      "string",
-      "null"
-    ]
-  },
-  "street": {
-    "description": "The street.",
-    "type": [
-      "string",
-      "null"
-    ]
-  }
-}

changedInput schema / $defs / def2 / type

Previous value: -"object"New value: +[
+  "string",
+  "null"
+]

removedInput schema / $defs / def3 / additionalProperties
```
Removed value: -true
```

removedInput schema / $defs / def3 / properties

Removed value: -{
-  "id": {
-    "description": "The unique identifier for an entity. Read-only.",
-    "type": "string"
-  },
-  "value": {
-    "description": "A collection of property values.",
-    "items": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "type": "array"
-  }
-}

changedInput schema / $defs / def3 / type

Previous value: -"object"New value: +[
+  "string",
+  "null"
+]

addedInput schema / $defs / def5

Added value: +{
+  "additionalProperties": true,
+  "properties": {
+    "id": {
+      "description": "The unique identifier for an entity. Read-only.",
+      "type": "string"
+    },
+    "value": {
+      "description": "A collection of property values.",
+      "items": {
+        "$ref": "#/$defs/def6"
+      },
+      "type": "array"
+    }
+  },
+  "type": "object"
+}

addedInput schema / $defs / def6

Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedInput schema / $defs / def7

Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedInput schema / $defs / def8

Added value: +{
+  "additionalProperties": true,
+  "properties": {
+    "city": {
+      "description": "The city.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "countryOrRegion": {
+      "description": "The country or region. It's a free-format string value, for example, 'United States'.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "postalCode": {
+      "description": "The postal code.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "state": {
+      "description": "The state.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "street": {
+      "description": "The street.",
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "type": "object"
+}

addedInput schema / $defs / def9

Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}

changedInput schema / properties / body / properties / multiValueExtendedProperties / items / $ref
```
Previous value: -"#/$defs/def3"New value: +"#/$defs/def5"
```

addedInput schema / properties / confirm / allOf

Added value: +[
+  {
+    "$ref": "#/$defs/def12"
+  }
+]

removedInput schema / properties / confirm / type
```
Removed value: -"boolean"
```

addedInput schema / properties / excludeResponse / allOf

Added value: +[
+  {
+    "$ref": "#/$defs/def13"
+  }
+]

removedInput schema / properties / excludeResponse / type
```
Removed value: -"boolean"
```

addedInput schema / properties / includeHeaders / allOf

Added value: +[
+  {
+    "$ref": "#/$defs/def14"
+  }
+]

removedInput schema / properties / includeHeaders / type
```
Removed value: -"boolean"
```

Addedv0.134.4Jul 28, 2026
Removedv0.131.2Jul 18, 2026

Changed1 schema field changedv0.131.1Jul 11, 2026

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"
+}

Addedv0.114.0May 28, 2026
Removedv0.112.2May 22, 2026
Addedv0.110.0May 18, 2026
Removedv0.108.0May 15, 2026
Addedv0.105.0May 8, 2026

TDQS

A3.9/5.0

Behavior3/5

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

Annotations already flag destructiveHint=true and openWorldHint=true, so the description's remaining job is to explain the consequences of that flag. It does state the return value (the created contactFolder with its id) and the request body shape, but never mentions the confirm gate that the schema says guards destructive operations, nor permission requirements.

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?

The description restates the same fact three times: default contacts folder, mailbox root, and the TIP's opening line. The routing hint and body example earn their place; the repetition does not.

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?

No output schema exists, and the description does cover the return value, which is good. But for a tool flagged destructive with openWorldHint, the absence of any note about the confirmation gate or the contradiction between 'any specified contact folder' and the sibling pointer leaves material ambiguity.

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 coverage is 75%, so a baseline of 3 applies, but the description goes beyond it by showing a concrete body payload ({ displayName: 'Family' }) and noting the returned id. It omits parentFolderId even while discussing child-folder creation, leaving a gap on the one parameter that would drive that path.

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

Purpose5/5

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

States a specific verb and resource (create a contactFolder) and scopes the default case to the user's default contacts folder. The sibling create-contact-child-folder is named explicitly, so an agent can distinguish the two without reading either schema.

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

Usage Guidelines4/5

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

The TIP gives explicit routing: use create-contact-child-folder for sub-folders, and a concrete body example for the default case. However, the opening line also claims you can create a folder as a child of any specified folder, which muddies the rule the TIP just established.

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

Deploy Server

create-contact-folder

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools