Work IQ MCP tool reference

The Work IQ MCP server exposes 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

▶ Open this example in the Interactive Demo

{
  "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

▶ Open this example in the Interactive Demo

{
  "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

▶ Open this example in the Interactive Demo

{
  "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

▶ Open this example in the Interactive Demo

{
  "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

▶ Open this example in the Interactive Demo

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

Response

{
  "statusCode": 204
}

do_action

Runs 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

▶ Open this example in the Interactive Demo

{
  "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

▶ Open this example in the Interactive Demo

{
  "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 your 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

▶ Open this example 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"
}

retrieve

Searches Microsoft 365 data and connected enterprise sources that the signed-in user can access. The tool returns model-friendly grounding Markdown with inline citations and structured metadata for each cited source. The grounding strategy is the default.

Parameters

Dataverse and Power BI are roadmap sources, not currently supported retrieval sources. Although the schema includes a Dataverse capability name, Dataverse needs further evaluation before it can be described as supported, and it isn't a near-term priority. No delivery timeline is committed.

Response

The authoritative response payload is in the application/vnd.ms-workiq.retrieval property of structuredContent.

For request examples, capability-specific scoping, SharePoint Embedded support, response-processing guidance, and error handling, see Use the retrieve tool in Work IQ MCP.

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

▶ Open this example in the Interactive Demo

{
  "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. By using these tools, agents can 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

▶ Open this example in the Interactive Demo

{
  "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

▶ Open this example in the Interactive Demo

{
  "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
• Use the retrieve tool in Work IQ MCP
• Migrate agentic retrieval workflows to Work IQ MCP
• Work IQ API overview
• Work IQ API permissions reference