> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Word

> Build, upload, parse, convert, version, and manage Microsoft Word documents stored in OneDrive or SharePoint

<img src="https://mintcdn.com/prismeai/WjDT59WIWxvSlSk1/images/connectors/word.jpg?fit=max&auto=format&n=WjDT59WIWxvSlSk1&q=85&s=4303f17934ebe55c9e55f1f996ebc2e8" alt="Word" width="96" height="96" noZoom style={{ float: "left", marginRight: "1.25rem", marginBottom: "0.5rem" }} data-path="images/connectors/word.jpg" />

The Word connector provides Microsoft Word document operations through the Microsoft Graph API. It can be used as a Builder app for deterministic document workflows or as an MCP server for AI agents that need to create, inspect, convert, update, version, and manage `.docx` files stored in OneDrive or SharePoint.

<CardGroup cols={3}>
  <Card title="Document Operations" icon="file-word">
    Read metadata, download content, upload DOCX bytes, convert files, and delete documents
  </Card>

  <Card title="Structured Authoring" icon="pen-to-square">
    Build valid Word documents from a JSON specification with headings, paragraphs, tables, lists, images, and formatting
  </Card>

  <Card title="Governance & Lifecycle" icon="clock-rotate-left">
    Search files, inspect document structure, manage versions, checkout locks, following, and analytics
  </Card>
</CardGroup>

## Prerequisites

* A **Microsoft Entra ID / Azure AD application** registered in your tenant
* A **client secret** for that application
* Microsoft Graph permissions granted with admin consent:
  * `Files.Read.All` for read-only document access
  * `Files.ReadWrite.All` for upload, update, delete, checkout, check-in, restore, and follow operations
  * `Sites.Read.All` or `Sites.ReadWrite.All` when accessing SharePoint-hosted documents
* Your **Directory (tenant) ID** and **Application (client) ID**
* Optional **SharePoint Site ID** when the default target is a SharePoint site instead of the user's OneDrive

***

<Tabs>
  <Tab title="Usage as App">
    ## Usage as App

    ## Installation

    1. Go to **Apps** in your workspace
    2. Search for **Word** and install it
    3. Open the app instance configuration and fill in the required Microsoft Graph credentials

    ## Configuration

    | Field                   | Description                                                                  |
    | ----------------------- | ---------------------------------------------------------------------------- |
    | **Azure Client ID**     | Microsoft Entra application (client) ID used to call Microsoft Graph         |
    | **Azure Client Secret** | Microsoft Entra application client secret, stored as a workspace secret      |
    | **Azure Tenant ID**     | Microsoft Entra directory (tenant) ID                                        |
    | **SharePoint Site ID**  | Optional default SharePoint site ID for SharePoint-based document operations |

    ## File Access

    Word operations target Microsoft Graph drive items. For OneDrive files, pass an `itemId` or `path` and optionally a `driveId`. For SharePoint files, also pass `siteId` or configure a default SharePoint Site ID on the app instance.

    ```yaml theme={null}
    - Word.getDocument:
        itemId: '{{documentItemId}}'
        driveId: '{{driveId}}'
        output: document
    ```

    ```yaml theme={null}
    - Word.getDocumentByPath:
        path: Documents/Quarterly Report.docx
        siteId: '{{sharePointSiteId}}'
        driveId: '{{driveId}}'
        output: document
    ```

    ## Available Instructions

    Every instruction resolves Microsoft Graph credentials through the workspace configuration. Most operations accept `driveId` and `siteId` to override the configured default target.

    ### Document Lookup & Search

    | Instruction            | Arguments                                                             |
    | ---------------------- | --------------------------------------------------------------------- |
    | `getDocument`          | `itemId`\*, `select`, `expand`, `driveId`, `siteId`                   |
    | `getDocumentByPath`    | `path`\*, `select`, `expand`, `driveId`, `siteId`                     |
    | `searchDocuments`      | `query`\*, `top`, `driveId`, `siteId`                                 |
    | `getDocumentStructure` | `itemId`\*, `includeContent`, `maxContentLength`, `driveId`, `siteId` |

    ### Content Transfer & Creation

    | Instruction              | Arguments                                                 |
    | ------------------------ | --------------------------------------------------------- |
    | `downloadDocument`       | `itemId`\*, `driveId`, `siteId`                           |
    | `downloadDocumentByPath` | `path`\*, `driveId`, `siteId`                             |
    | `uploadDocument`         | `itemId`*, `content`*, `contentType`, `driveId`, `siteId` |
    | `uploadDocumentByPath`   | `path`*, `content`*, `contentType`, `driveId`, `siteId`   |
    | `buildDocument`          | `itemId` or `path`, `spec`\*, `driveId`, `siteId`         |
    | `convertDocument`        | `itemId`*, `format`*, `driveId`, `siteId`                 |

    ### Metadata & Lifecycle

    | Instruction      | Arguments                                              |
    | ---------------- | ------------------------------------------------------ |
    | `updateDocument` | `itemId`\*, `name`, `description`, `driveId`, `siteId` |
    | `deleteDocument` | `itemId`\*, `driveId`, `siteId`                        |

    ### Versions

    | Instruction              | Arguments                                    |
    | ------------------------ | -------------------------------------------- |
    | `listVersions`           | `itemId`\*, `driveId`, `siteId`              |
    | `getVersion`             | `itemId`*, `versionId`*, `driveId`, `siteId` |
    | `downloadVersionContent` | `itemId`*, `versionId`*, `driveId`, `siteId` |
    | `restoreVersion`         | `itemId`*, `versionId`*, `driveId`, `siteId` |

    ### Checkout

    | Instruction        | Arguments                                  |
    | ------------------ | ------------------------------------------ |
    | `checkoutDocument` | `itemId`\*, `driveId`, `siteId`            |
    | `checkinDocument`  | `itemId`\*, `comment`, `driveId`, `siteId` |
    | `discardCheckout`  | `itemId`\*, `driveId`, `siteId`            |

    ### Collaboration & Analytics

    | Instruction        | Arguments                       |
    | ------------------ | ------------------------------- |
    | `followDocument`   | `itemId`\*, `driveId`, `siteId` |
    | `unfollowDocument` | `itemId`\*, `driveId`, `siteId` |
    | `getAnalytics`     | `itemId`\*, `driveId`, `siteId` |

    <Note>
      Arguments flagged with `*` are required. `buildDocument` requires `spec` and either `itemId` for rewrite mode or `path` for create mode.
    </Note>

    ## DSUL Examples

    ### Search for Word Documents

    ```yaml theme={null}
    - Word.searchDocuments:
        query: contract
        top: 10
        driveId: '{{driveId}}'
        output: documents
    ```

    ### Build a New Word Document

    ```yaml theme={null}
    - Word.buildDocument:
        path: Reports/generated-summary.docx
        driveId: '{{driveId}}'
        spec:
          properties:
            title: Generated Summary
            author: Prisme.ai
          sections:
            - content:
                - type: heading
                  level: 1
                  text: Quarterly Summary
                - type: paragraph
                  text: This document was generated from a Prisme.ai workflow.
                - type: table
                  headers:
                    - Metric
                    - Value
                  rows:
                    - - Revenue
                      - '{{revenue}}'
                    - - Active customers
                      - '{{customerCount}}'
        output: builtDocument
    ```

    ### Inspect and Convert a Document

    ```yaml theme={null}
    - Word.getDocumentStructure:
        itemId: '{{documentItemId}}'
        includeContent: true
        output: structure
    - Word.convertDocument:
        itemId: '{{documentItemId}}'
        format: pdf
        output: pdfContent
    ```

    ### Restore a Previous Version

    ```yaml theme={null}
    - Word.listVersions:
        itemId: '{{documentItemId}}'
        output: versions
    - Word.restoreVersion:
        itemId: '{{documentItemId}}'
        versionId: '{{versions.value[0].id}}'
        output: restored
    ```
  </Tab>

  <Tab title="Usage as MCP">
    ## Usage as MCP

    The Word MCP workspace exposes the same document operations as JSON-RPC tools. The MCP endpoint receives the `mcp-api-key` header, routes `tools/call` requests through `routeToolCall`, and delegates each operation to the Word app workspace, where Microsoft Graph authentication and Graph URL construction are handled.

    ## MCP Configuration

    | Field           | Description                                                                                           |
    | --------------- | ----------------------------------------------------------------------------------------------------- |
    | **MCP API Key** | Configured on the Word MCP workspace and sent through the `mcp-api-key` header for MCP endpoint calls |

    ## Plug into an Agent Creator capability

    Agents consume MCP servers directly through **Agent Creator** capabilities. This is the preferred way to expose Word tools to an agent.

    <Steps>
      <Step title="Create or open a workspace">
        From the Prisme.ai console, create a new workspace or open the workspace that will host the connector.
      </Step>

      <Step title="Install and configure the Word app">
        Install **Word** and configure the Microsoft Graph credentials from the *Usage as App* tab.
      </Step>

      <Step title="Copy the MCP endpoint and API key">
        Open the Word MCP app instance configuration and copy the **MCP Endpoint** and **MCP API Key** values.
      </Step>

      <Step title="Open Agent Creator">
        Open the agent you want to extend and add a capability.
      </Step>

      <Step title="Add the MCP capability">
        Select a dedicated Word capability if one exists. Otherwise, use the generic `custom_mcp` capability, paste the MCP endpoint as the server URL, then add this header:

        ```json theme={null}
        {
          "mcp-api-key": "your-mcp-api-key"
        }
        ```
      </Step>

      <Step title="Brief the agent">
        Tell the agent when to use Word tools, which document locations it may access, and when to ask for confirmation before destructive actions such as deleting files, overwriting content, restoring versions, or discarding checkout changes.
      </Step>
    </Steps>

    ## Legacy MCP Install (Advanced > Tools)

    Use this flow to plug the Word MCP into an AI Knowledge agent that does not yet support the native Agent Creator capability picker.

    <Steps>
      <Step title="Install the Word app">
        Install and configure the Word app in the same workspace as your agent.
      </Step>

      <Step title="Copy the MCP credentials">
        Open the MCP app instance configuration and copy the **MCP Endpoint** and **MCP API Key**.
      </Step>

      <Step title="Open your AI Knowledge project">
        Navigate to **Advanced > Tools**.
      </Step>

      <Step title="Add an MCP tool">
        Click **Add**, select the **MCP** tab, and paste the MCP endpoint URL.
      </Step>

      <Step title="Add the auth header">
        Add the signed API key in the headers field:

        ```json theme={null}
        {
          "mcp-api-key": "your-mcp-api-key"
        }
        ```
      </Step>

      <Step title="Save">
        The agent can now list and call the Word MCP tools.
      </Step>
    </Steps>

    ## Output Formats

    Every tool accepts an `outputFormat` parameter that controls the MCP response shape:

    * **`verbose`** (default) - human-readable text for LLM consumption
    * **`structured`** - machine-readable JSON returned as text and in `structuredContent`
    * **`both`** - currently returns JSON text and `structuredContent`, matching `structured` output

    ## Available Tools

    ### Document Lookup & Search

    | Tool                   | Description                                 |
    | ---------------------- | ------------------------------------------- |
    | `getDocument`          | Get Word document metadata by ID            |
    | `getDocumentByPath`    | Get Word document metadata by path          |
    | `searchDocuments`      | Search for Word documents in a drive        |
    | `getDocumentStructure` | Parse Word document and return element tree |

    ### Content Transfer & Creation

    | Tool                     | Description                                                                  |
    | ------------------------ | ---------------------------------------------------------------------------- |
    | `downloadDocument`       | Download Word document content by ID                                         |
    | `downloadDocumentByPath` | Download Word document content by path                                       |
    | `uploadDocument`         | Upload or replace a Word document from base64-encoded DOCX bytes, up to 4 MB |
    | `uploadDocumentByPath`   | Upload a Word document to a path from base64-encoded DOCX bytes              |
    | `buildDocument`          | Create a valid Word `.docx` from a JSON spec and upload it                   |
    | `convertDocument`        | Convert a Word document to PDF or HTML format                                |

    ### Metadata & Lifecycle

    | Tool             | Description                                          |
    | ---------------- | ---------------------------------------------------- |
    | `updateDocument` | Update document metadata such as name or description |
    | `deleteDocument` | Delete a document by moving it to the recycle bin    |

    ### Versions

    | Tool                     | Description                                     |
    | ------------------------ | ----------------------------------------------- |
    | `listVersions`           | List all versions of a Word document            |
    | `getVersion`             | Get metadata for a specific document version    |
    | `downloadVersionContent` | Download content of a specific document version |
    | `restoreVersion`         | Restore a document to a previous version        |

    ### Checkout

    | Tool               | Description                                                |
    | ------------------ | ---------------------------------------------------------- |
    | `checkoutDocument` | Check out a document to lock it for exclusive editing      |
    | `checkinDocument`  | Check in a document to release the lock and save changes   |
    | `discardCheckout`  | Discard checkout and revert to the last checked-in version |

    ### Collaboration & Analytics

    | Tool               | Description                                                                          |
    | ------------------ | ------------------------------------------------------------------------------------ |
    | `followDocument`   | Follow a document to receive notifications                                           |
    | `unfollowDocument` | Stop following a document                                                            |
    | `getAnalytics`     | Get document analytics such as views and viewers when available from Microsoft Graph |

    ## Tool Details

    ### `buildDocument`

    Creates or rewrites a Word document from a JSON document specification.

    ```json theme={null}
    {
      "name": "buildDocument",
      "arguments": {
        "path": "Reports/generated-summary.docx",
        "driveId": "b!drive-id",
        "spec": {
          "properties": {
            "title": "Generated Summary",
            "author": "Prisme.ai"
          },
          "sections": [
            {
              "content": [
                { "type": "heading", "level": 1, "text": "Quarterly Summary" },
                { "type": "paragraph", "text": "Generated by an AI agent." },
                {
                  "type": "table",
                  "headers": ["Metric", "Value"],
                  "rows": [["Revenue", "$120k"], ["Customers", "42"]]
                }
              ]
            }
          ]
        },
        "outputFormat": "structured"
      }
    }
    ```

    | Parameter | Required | Description                                                               |
    | --------- | -------- | ------------------------------------------------------------------------- |
    | `spec`    | Yes      | JSON specification with `sections` and document content elements          |
    | `itemId`  | No       | Existing document item ID for rewrite mode                                |
    | `path`    | No       | File path for create mode; required when `itemId` is omitted              |
    | `driveId` | No       | Drive ID; defaults to the configured OneDrive or SharePoint drive context |
    | `siteId`  | No       | SharePoint site ID override                                               |

    ### `getDocumentStructure`

    Downloads a DOCX file and parses it into a structured element tree that agents can inspect before rewriting or summarizing content.

    ```json theme={null}
    {
      "name": "getDocumentStructure",
      "arguments": {
        "itemId": "01ABCDEF2345",
        "includeContent": true,
        "maxContentLength": 2000,
        "outputFormat": "structured"
      }
    }
    ```

    | Parameter          | Required | Description                                 |
    | ------------------ | -------- | ------------------------------------------- |
    | `itemId`           | Yes      | Document drive item ID                      |
    | `includeContent`   | No       | Include text content in parsed elements     |
    | `maxContentLength` | No       | Maximum content length returned per element |
    | `driveId`          | No       | Drive ID override                           |
    | `siteId`           | No       | SharePoint site ID override                 |

    ### `uploadDocumentByPath`

    Uploads a base64-encoded DOCX file to a drive path.

    ```json theme={null}
    {
      "name": "uploadDocumentByPath",
      "arguments": {
        "path": "Templates/template.docx",
        "content": "UEsDBBQAAAA...",
        "contentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
      }
    }
    ```

    | Parameter     | Required | Description                           |
    | ------------- | -------- | ------------------------------------- |
    | `path`        | Yes      | Target path in the drive              |
    | `content`     | Yes      | Base64-encoded DOCX bytes, up to 4 MB |
    | `contentType` | No       | MIME type; defaults to Word `.docx`   |
    | `driveId`     | No       | Drive ID override                     |
    | `siteId`      | No       | SharePoint site ID override           |

    ### `searchDocuments`

    Searches for Word documents in the configured drive context.

    ```json theme={null}
    {
      "name": "searchDocuments",
      "arguments": {
        "query": "contract",
        "top": 10,
        "outputFormat": "both"
      }
    }
    ```

    | Parameter | Required | Description                         |
    | --------- | -------- | ----------------------------------- |
    | `query`   | Yes      | Search query text                   |
    | `top`     | No       | Maximum number of results to return |
    | `driveId` | No       | Drive ID override                   |
    | `siteId`  | No       | SharePoint site ID override         |

    ### `convertDocument`

    Converts a Word document to another format supported by Microsoft Graph download conversion.

    ```json theme={null}
    {
      "name": "convertDocument",
      "arguments": {
        "itemId": "01ABCDEF2345",
        "format": "pdf",
        "outputFormat": "structured"
      }
    }
    ```

    | Parameter | Required | Description                              |
    | --------- | -------- | ---------------------------------------- |
    | `itemId`  | Yes      | Document drive item ID                   |
    | `format`  | Yes      | Target format, typically `pdf` or `html` |
    | `driveId` | No       | Drive ID override                        |
    | `siteId`  | No       | SharePoint site ID override              |

    ### `restoreVersion`

    Restores a document to a previous version.

    ```json theme={null}
    {
      "name": "restoreVersion",
      "arguments": {
        "itemId": "01ABCDEF2345",
        "versionId": "2.0",
        "outputFormat": "verbose"
      }
    }
    ```

    | Parameter   | Required | Description                           |
    | ----------- | -------- | ------------------------------------- |
    | `itemId`    | Yes      | Document drive item ID                |
    | `versionId` | Yes      | Version ID returned by `listVersions` |
    | `driveId`   | No       | Drive ID override                     |
    | `siteId`    | No       | SharePoint site ID override           |
  </Tab>
</Tabs>

***

## Error Handling

| HTTP Status | Error                                             | Solution                                                                             |
| ----------- | ------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `400`       | Invalid request, path, format, or document spec   | Check required arguments, Graph path syntax, and `spec.sections` for `buildDocument` |
| `401`       | Authentication failed                             | Verify Azure Client ID, Client Secret, Tenant ID, and token permissions              |
| `403`       | Insufficient Microsoft Graph permissions          | Grant admin consent for the required Files and Sites permissions                     |
| `404`       | Document, drive, site, or version not found       | Verify `itemId`, `path`, `driveId`, `siteId`, and `versionId`                        |
| `409`       | Conflict or checkout state prevents the operation | Check the document checkout status or retry after releasing the lock                 |
| `413`       | Generated or uploaded content is too large        | Keep base64 DOCX uploads under the 4 MB connector limit                              |
| `429`       | Microsoft Graph throttling                        | Retry later or reduce request volume                                                 |
| `500`       | Microsoft Graph or connector runtime error        | Inspect the tool response and workspace execution logs                               |

### Common Issues

**"Authentication failed"** - The Microsoft Graph credentials are missing, expired, or lack admin consent. Confirm the configured Azure app can acquire a token for Microsoft Graph.

**"Either itemId or path must be provided"** - `buildDocument` supports rewrite mode with `itemId` or create mode with `path`. Provide one of them with a valid `spec`.

**Upload exceeds 4 MB** - `uploadDocument`, `uploadDocumentByPath`, and generated `buildDocument` uploads use the small-file Microsoft Graph upload path. Reduce the document size before retrying.

**SharePoint document not found** - SharePoint operations usually need the correct `siteId` and `driveId`. Configure a default SharePoint Site ID or pass these arguments per call.

## External Resources

<CardGroup cols={2}>
  <Card title="Microsoft Graph DriveItem API" icon="microsoft" href="https://learn.microsoft.com/en-us/graph/api/resources/driveitem">
    Reference for OneDrive and SharePoint file metadata, content, versions, and lifecycle operations.
  </Card>

  <Card title="Tool Agents" icon="robot" href="/products/agent-factory/capabilities">
    Learn how to expose connector tools to AI agents through Prisme.ai capabilities.
  </Card>
</CardGroup>