Work IQ MCP tool reference

The Work IQ MCP server exposes 10 tools through the Model Context Protocol (MCP). This article provides a reference for each tool, including its purpose, parameters, and usage examples.

Work IQ MCP uses Microsoft Entra authentication and the signed-in user's Microsoft 365 permissions when its tools access Microsoft Graph resource paths. A separate tenant policy layer evaluates each tool request and blocks mutation operations by default. Administrators can enable supported create, update, delete, and action requests through tenant policy. For details, see Policy governance for Work IQ MCP.

Entity tools

Entity tools provide CRUD operations and actions on Microsoft 365 resources. These tools operate on relative resource paths that map to Microsoft Graph endpoints.

fetch

Reads one or more entities by resource path. Supports fetching multiple paths in parallel.

Parameters

Response

A successful response contains a results property that is an array of objects with the following properties. There's one object for each resource path in the entityUrls parameter of the request.

Example

Request

{
  "method": "tools/call",
  "params": {
    "name": "fetch",
    "arguments": {
      "entityUrls": [
        "/me/messages"
      ]
    }
  }
}

Response

{
  "results": [
    {
      "data": {
        "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('0c6bc4a2-337b-4672-9bcd-6aa53af1b02a')/messages(id,subject,from,receivedDateTime,isRead,importance)",
        "value": [
          {
            "@odata.etag": "W/\"CQAAABYAAADltuSvpI1YRKDFG38ihSmWAABepTg8\"",
            "id": "AAMkADk0...",
            "receivedDateTime": "2026-05-31T15:40:44Z",
            "subject": "Your weekly PIM digest for Contoso",
            "importance": "normal",
            "isRead": false,
            "from": {
              "emailAddress": {
                "name": "Microsoft Security",
                "address": "MSSecurity-noreply@microsoft.com"
              }
            }
          },
          {
            "@odata.etag": "W/\"CQAAABYAAADltuSvpI1YRKDFG38ihSmWAAA/eZg0\"",
            "id": "AAMkADk0...",
            "receivedDateTime": "2026-05-26T07:39:09Z",
            "subject": "Microsoft Entra ID Protection Weekly Digest",
            "importance": "normal",
            "isRead": false,
            "from": {
              "emailAddress": {
                "name": "Microsoft Security",
                "address": "MSSecurity-noreply@microsoft.com"
              }
            }
          }
        ],
        "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/messages?%24select=id%2csubject%2cfrom%2creceivedDateTime%2cisRead%2cimportance&%24top=10&%24skip=10"
      },
      "statusCode": 200
    }
  ]
}

fetch_blob

Fetches binary content, such as documents, images, and Office files from a relative Work IQ path. The content is returned as a Base64-encoded string with metadata.

Parameters

Response

A successful response exposes the following properties through the MCP structuredContent field.

Example

Request

{
  "method": "tools/call",
  "params": {
    "name": "fetch_blob",
    "arguments": {
      "path": "/me/drive/items/01ABCDEF/content"
    }
  }
}

Response

{
  "structuredContent": {
    "statusCode": 200,
    "contentType": "text/plain",
    "blobName": "notes.txt",
    "sizeBytes": 14,
    "base64Content": "SGVsbG8sIFdvcmtJUSE="
  }
}

create_entity

Creates a new entity in a collection.

Parameters

Response

A successful response contains an object in the structuredContent property with the following properties.

Example

Request

{
  "method": "tools/call",
  "params": {
    "name": "create_entity",
    "arguments": {
      "parentUrl": "/me/messages",
      "jsonBody": "{ \"subject\": \"Hello world!\" }"
    }
  }
}

Response

{
  "statusCode": 201,
  "data": {
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('0c6bc4a2-337b-4672-9bcd-6aa53af1b02a')/messages/$entity",
    "@odata.etag": "W/\"CQAAABYAAADltuSvpI1YRKDFG38ihSmWAABlFT7g\"",
    "id": "AAMkADk0...",
    "createdDateTime": "2026-06-01T17:32:39Z",
    "lastModifiedDateTime": "2026-06-01T17:32:39Z",
    "changeKey": "CQAAABYAAADltuSvpI1YRKDFG38ihSmWAABlFT7g",
    "categories": [],
    "receivedDateTime": "2026-06-01T17:32:39Z",
    "sentDateTime": "2026-06-01T17:32:39Z",
    "hasAttachments": false,
    "internetMessageId": "<CH7PR03MB79063B75F29F929523CCC68FAE152@CH7PR03MB7906.namprd03.prod.outlook.com>",
    "subject": "Hello world!",
    "bodyPreview": "",
    "importance": "normal",
    "parentFolderId": "AQMkADk0...",
    "conversationId": "AAQkADk0...",
    "conversationIndex": "AQHc8eykdVXKjf4ytUio+dQPqWG95A==",
    "isDeliveryReceiptRequested": false,
    "isReadReceiptRequested": false,
    "isRead": true,
    "isDraft": true,
    "inferenceClassification": "focused",
    "body": {
      "contentType": "text",
      "content": ""
    },
    "toRecipients": [],
    "ccRecipients": [],
    "bccRecipients": [],
    "replyTo": [],
    "flag": {
      "flagStatus": "notFlagged"
    }
  }
}

update_entity

Updates an existing entity.

Parameters

Response

A successful response contains an object in the structuredContent property with the following properties.

Example

Request

{
  "method": "tools/call",
  "params": {
    "name": "update_entity",
    "arguments": {
      "entityUrl": "/me/messages/AAMkADk0...",
      "jsonBody": "{ \"subject\": \"Updated: Hello world!\" }"
    }
  }
}

Response

{
  "statusCode": 200,
  "data": {
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('0c6bc4a2-337b-4672-9bcd-6aa53af1b02a')/messages/$entity",
    "@odata.etag": "W/\"CQAAABYAAADltuSvpI1YRKDFG38ihSmWAABlFT7g\"",
    "id": "AAMkADk0...",
    "createdDateTime": "2026-06-01T17:32:39Z",
    "lastModifiedDateTime": "2026-06-01T17:32:39Z",
    "changeKey": "CQAAABYAAADltuSvpI1YRKDFG38ihSmWAABlFT7g",
    "categories": [],
    "receivedDateTime": "2026-06-01T17:32:39Z",
    "sentDateTime": "2026-06-01T17:32:39Z",
    "hasAttachments": false,
    "internetMessageId": "<CH7PR03MB79063B75F29F929523CCC68FAE152@CH7PR03MB7906.namprd03.prod.outlook.com>",
    "subject": "Updated: Hello world!",
    "bodyPreview": "",
    "importance": "normal",
    "parentFolderId": "AQMkADk0...",
    "conversationId": "AAQkADk0...",
    "conversationIndex": "AQHc8eykdVXKjf4ytUio+dQPqWG95A==",
    "isDeliveryReceiptRequested": false,
    "isReadReceiptRequested": false,
    "isRead": true,
    "isDraft": true,
    "inferenceClassification": "focused",
    "body": {
      "contentType": "text",
      "content": ""
    },
    "toRecipients": [],
    "ccRecipients": [],
    "bccRecipients": [],
    "replyTo": [],
    "flag": {
      "flagStatus": "notFlagged"
    }
  }
}

delete_entity

Deletes an entity.

Parameters

Response

A successful response contains a statusCode property set to 204 in the structuredContent field.

Example

Request

{
  "method": "tools/call",
  "params": {
    "name": "delete_entity",
    "arguments": {
      "entityUrl": "/me/messages/AAMkADk0MDkyMzM3LTlmNzAtNDhmM...."
    }
  }
}

Response

{
  "statusCode": 204
}

do_action

Executes a side-effect action such as sending mail, copying, or moving items.

Parameters

Response

A successful response contains an object in the structuredContent property with the following properties.

Example

Request

{
  "method": "tools/call",
  "params": {
    "name": "do_action",
    "arguments": {
      "actionUrl": "/me/messages/AAMkADk0.../send"
    }
  }
}

Response

{
  "statusCode": 202
}

call_function

Calls a Microsoft Graph function to compute derived data such as schedules, deltas, or search results.

Parameters

Response

A successful response contains an object in the structuredContent property with the following properties.

Example

Request

{
  "method": "tools/call",
  "params": {
    "name": "call_function",
    "arguments": {
      "parentUrl": "/me/calendarView?startdatetime=2026-06-01T17:51:49.607Z&enddatetime=2026-06-08T17:51:49.607Z"
    }
  }
}

Response

{
  "data": {
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('0c6bc4a2-337b-4672-9bcd-6aa53af1b02a')/calendarView(id,subject,start,end,location,organizer,isAllDay)",
    "value": [
      {
        "@odata.etag": "W/\"5bbkr6SNWESgxRt/IoUplgAAKcCTsQ==\"",
        "id": "AAMkADk0...",
        "subject": "Sales and Marketing Sync",
        "isAllDay": false,
        "start": {
          "dateTime": "2026-06-08T12:30:00.0000000",
          "timeZone": "UTC"
        },
        "end": {
          "dateTime": "2026-06-08T13:00:00.0000000",
          "timeZone": "UTC"
        },
        "location": {
          "displayName": "Sales and Marketing / General",
          "locationType": "default",
          "uniqueId": "Sales and Marketing / General",
          "uniqueIdType": "private"
        },
        "organizer": {
          "emailAddress": {
            "name": "Sales and Marketing",
            "address": "SalesandMarketing@contoso.com"
          }
        }
      }
    ],
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/calendarView?startdatetime=2026-06-01T17%3a51%3a49.607Z&enddatetime=2026-06-08T17%3a51%3a49.607Z&%24select=id%2csubject%2cstart%2cend%2clocation%2corganizer%2cisAllDay&%24top=10&%24skip=10"
  },
  "statusCode": 200
}

Copilot tools

Copilot tools provide natural-language intelligence by invoking Microsoft 365 Copilot and discovering available agents.

ask

Asks Microsoft 365 Copilot (or a specific agent) a natural-language question about the user's data. When you provide an agentId, the request goes to that specific agent. When you omit it, the request goes to the built-in Microsoft 365 Copilot agent.

Parameters

Response

A successful response contains a JSON string in the text property of a TextContent object. The string includes the following properties.

Example

Request

▶ Try it in the Interactive Demo

{
  "method": "tools/call",
  "params": {
    "name": "ask",
    "arguments": {
      "question": "Do I have any meetings today?"
    }
  }
}

Response

{
  "response": "You have **4 meetings scheduled today**. Here\\u2019s a clear view of your day:...",
  "conversationId": "cc7d6f5202cb4c5b814b120440e48ede"
}

list_agents

Lists available agents that you can use with the ask tool. Returns a JSON array of available agents, and the built-in Microsoft 365 Copilot agent is always included.

Parameters

This tool takes no parameters.

Response

A successful response contains a JSON string in the text property of a TextContent object. The string includes the following properties.

Example

Request

{
  "method": "tools/call",
  "params": {
    "name": "list_agent",
    "arguments": {}
  }
}

Response

[
  {
    "agentId": "bizchat-as-gpt-scenario",
    "name": "Microsoft Copilot",
    "provider": "Microsoft"
  }
]

Schema tools

Schema tools enable runtime discovery of available API paths and their OpenAPI schemas. These tools allow agents to discover what operations are available without loading large schema definitions into context upfront.

get_schema

Retrieves the OpenAPI schema for a specific operation, identified by path and operation type.

Parameters

Response

A successful response contains the JSON schema or TypeScript definitions in the text property of a TextContent object.

Example

Request

{
  "method": "tools/call",
  "params": {
    "name": "get_schema",
    "arguments": {
      "path": "/me/messages",
      "operationType": "fetch"
    }
  }
}

Response

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "microsoft.graph.messageCollectionResponse",
  "type": "object",
  "properties": {
    "value": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/microsoft.graph.message"
      }
    }
  },
  "$defs": {
    ...
  }
}

search_paths

Searches available API paths by prefix or regex filter. Use this tool to discover which resource paths are available before calling other tools.

Parameters

Response

A successful response contains a paths property in the structuredContent field. This property is an array of objects with the following properties.

Example

Request

{
  "method": "tools/call",
  "params": {
    "name": "search_paths",
    "arguments": {
      "filter": "messages"
    }
  }
}

Response

{
  "paths": [
    {
      "path": "/admin/serviceAnnouncement/messages",
      "operations": [
        "fetch",
        "create"
      ]
    },
    {
      "path": "/admin/serviceAnnouncement/messages/{serviceUpdateMessage-id}",
      "operations": [
        "fetch",
        "create",
        "update"
      ]
    },
    ...
  ]
}

Allowed resource paths

Entity tools work with relative resource paths. By default, the following path prefixes are allowed:

• /me/
• /users/
• /sites/

The following path segments are blocked:

• /authentication/
• /servicePrincipals/

Error handling

When a tool call fails, the Work IQ MCP server returns errors with the following information:

• HTTP status code from the downstream service
• Retry-After headers for throttling responses (passed through from Microsoft Graph)
• Request correlation IDs for troubleshooting

The server doesn't perform automatic retries. The MCP client receives errors and makes client-side retry decisions.

Related content

• Work IQ MCP overview
• Work IQ API overview
• Work IQ API permissions reference