# Microsoft Excel
**Version:** 0.2.0

Arcade.dev LLM tools for Microsoft Excel

## Overview

Microsoft Excel toolkit for Arcade.dev lets LLMs operate on Excel workbooks stored in OneDrive for Business via the Microsoft Graph API. It enables creating workbooks, managing worksheets, reading workbook and worksheet metadata, and reading/updating cells and ranges using sparse formats and pagination.

**Capabilities**
- Manage workbook and worksheet lifecycle (create, add, rename, delete) with session_id support to mitigate Graph propagation delays.
- Inspect workbook metadata and worksheet lists including visibility and positions.
- Read sparse cell data with pagination hints and update single cells or sparse ranges (strings, numbers, booleans, formulas).
- Handle consistency and retry patterns around short propagation windows.

**OAuth**
Provider: microsoft
Scopes: Files.Read, Files.ReadWrite, User.Read

## Authentication

**Type:** OAuth 2.0
**Provider:** microsoft

**Required scopes:**
- `Files.Read`
- `Files.ReadWrite`
- `User.Read`

## Tools

This toolkit provides **9 tools**:

### Quick Reference

- [`MicrosoftExcel.AddWorksheet`](#microsoftexceladdworksheet) — Add a new worksheet to the workbook.
- [`MicrosoftExcel.CreateWorkbook`](#microsoftexcelcreateworkbook) — Create a new Excel workbook (.xlsx) in OneDrive for Business.
- [`MicrosoftExcel.DeleteWorksheet`](#microsoftexceldeleteworksheet) — Delete a worksheet from the workbook.
- [`MicrosoftExcel.GetWorkbookMetadata`](#microsoftexcelgetworkbookmetadata) — Get metadata about an Excel workbook including worksheet list.
- [`MicrosoftExcel.GetWorksheetData`](#microsoftexcelgetworksheetdata) — Read cell values from a worksheet.
- [`MicrosoftExcel.RenameWorksheet`](#microsoftexcelrenameworksheet) — Rename an existing worksheet in the workbook.
- [`MicrosoftExcel.UpdateCell`](#microsoftexcelupdatecell) — Update a single cell value in an Excel workbook.
- [`MicrosoftExcel.UpdateRange`](#microsoftexcelupdaterange) — Update multiple cells in a worksheet using sparse dict format.
- [`MicrosoftExcel.WhoAmI`](#microsoftexcelwhoami) — Get information about the current user and their Microsoft Excel environment.

---

## Tool Details

### MicrosoftExcel.AddWorksheet

**Version:** 0.2.0

Add a new worksheet to the workbook.

Note: The new worksheet name may not be immediately visible to other
tools due to a brief Graph API propagation delay (up to ~10 s). Pass
the returned ``session_id`` to subsequent calls that reference the new
worksheet to mitigate this.

**Parameters:**

- `item_id`: `string` *(required)*
  - The ID of the Excel workbook.
- `name`: `string` *(optional)*
  - Name for the new worksheet. If omitted, Excel generates a default name.
- `drive_id`: `string` *(optional)*
  - Optional drive ID for shared items. If omitted, uses the user's default OneDrive.
- `session_id`: `string` *(optional)*
  - Optional session ID from a previous operation for better performance.

**OAuth Scopes:**
- `Files.ReadWrite`

**Output:** `json`
- The created worksheet info.

**Example:**

```json
{
  "tool": "MicrosoftExcel.AddWorksheet",
  "parameters": {
    "item_id": "01T5ABCDEF123456789!123",
    "name": "Quarterly Report Q2 2026",
    "drive_id": "b!a1B2c3D4e5F6g7H8I9J0",
    "session_id": "b4f5c6d7-89ab-4cde-0123-456789abcdef"
  },
  "requires_auth": true,
  "auth_provider": "microsoft",
  "scopes": [
    "Files.ReadWrite"
  ]
}
```

---

### MicrosoftExcel.CreateWorkbook

**Version:** 0.2.0

Create a new Excel workbook (.xlsx) in OneDrive for Business.

Only .xlsx files are supported. OneDrive Consumer (personal accounts) is NOT supported.

**Parameters:**

- `filename`: `string` *(required)*
  - File name for the new workbook. The .xlsx extension is added automatically if not provided.
- `parent_folder_id`: `string` *(optional)*
  - Parent folder ID. If omitted, the workbook is created in the root of OneDrive.
- `initial_data`: `string` *(optional)*
  - Optional JSON string for initial data in the first worksheet. Format: data[ROW][COL] = VALUE where ROW is a row number as string, COL is a column letter (uppercase), VALUE is string/number/boolean/null. Type: dict[str, dict[str, str | int | float | bool | None]].

**OAuth Scopes:**
- `Files.ReadWrite`

**Output:** `json`
- The created Excel workbook metadata with session ID.

**Example:**

```json
{
  "tool": "MicrosoftExcel.CreateWorkbook",
  "parameters": {
    "filename": "Q1_2026_Report",
    "parent_folder_id": "01ABCDXYZ123!456",
    "initial_data": "{\"1\":{\"A\":\"Region\",\"B\":\"Sales\",\"C\":\"Growth\"},\"2\":{\"A\":\"North\",\"B\":120000.5,\"C\":0.05},\"3\":{\"A\":\"South\",\"B\":95000,\"C\":-0.02},\"4\":{\"A\":\"Total\",\"B\":215000.5,\"C\":null}}"
  },
  "requires_auth": true,
  "auth_provider": "microsoft",
  "scopes": [
    "Files.ReadWrite"
  ]
}
```

---

### MicrosoftExcel.DeleteWorksheet

**Version:** 0.2.0

Delete a worksheet from the workbook.

Cannot delete the last worksheet in a workbook.

Note: If referencing a recently added or renamed worksheet, pass the
``session_id`` from that operation. A brief Graph API propagation delay
(up to ~10 s) may cause a WorksheetNotFoundError; retry with the
``session_id`` if this occurs.

**Parameters:**

- `item_id`: `string` *(required)*
  - The ID of the Excel workbook.
- `worksheet`: `string` *(required)*
  - Name of the worksheet to delete.
- `drive_id`: `string` *(optional)*
  - Optional drive ID for shared items. If omitted, uses the user's default OneDrive.
- `session_id`: `string` *(optional)*
  - Optional session ID from a previous operation for better performance.

**OAuth Scopes:**
- `Files.ReadWrite`

**Output:** `json`
- Confirmation of the worksheet deletion.

**Example:**

```json
{
  "tool": "MicrosoftExcel.DeleteWorksheet",
  "parameters": {
    "item_id": "01ABCD2EFGHIJKL3456789!101",
    "worksheet": "Expenses 2026",
    "drive_id": "b!a1b2c3d4e5f6g7h8i9j0k",
    "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "requires_auth": true,
  "auth_provider": "microsoft",
  "scopes": [
    "Files.ReadWrite"
  ]
}
```

---

### MicrosoftExcel.GetWorkbookMetadata

**Version:** 0.2.0

Get metadata about an Excel workbook including worksheet list.

Returns workbook name, URL, and all worksheets with their names, positions, and visibility.

**Parameters:**

- `item_id`: `string` *(required)*
  - The ID of the Excel workbook.
- `drive_id`: `string` *(optional)*
  - Optional drive ID for shared items. If omitted, uses the user's default OneDrive.
- `session_id`: `string` *(optional)*
  - Optional session ID from a previous operation for better performance.

**OAuth Scopes:**
- `Files.Read`

**Output:** `json`
- Workbook metadata including worksheet list.

**Example:**

```json
{
  "tool": "MicrosoftExcel.GetWorkbookMetadata",
  "parameters": {
    "item_id": "01A2B3C4D5E6F7G8!123",
    "drive_id": "b!xYzAbCdEfGhIjKlMnOp",
    "session_id": "session_9f8e7d6c5b4a3"
  },
  "requires_auth": true,
  "auth_provider": "microsoft",
  "scopes": [
    "Files.Read"
  ]
}
```

---

### MicrosoftExcel.GetWorksheetData

**Version:** 0.2.0

Read cell values from a worksheet.

Returns data in sparse dict format where data[ROW][COL] has userEnteredValue
and formattedValue for each non-empty cell. Includes pagination hints if more
data exists beyond the requested range.

Note: If referencing a recently added or renamed worksheet, pass the
``session_id`` from that operation. A brief Graph API propagation delay
(up to ~10 s) may cause a WorksheetNotFoundError; retry with the
``session_id`` if this occurs.

**Parameters:**

- `item_id`: `string` *(required)*
  - The ID of the Excel workbook.
- `worksheet`: `string` *(optional)*
  - Worksheet name to read from. If omitted, reads from the first worksheet.
- `start_row`: `integer` *(optional)*
  - Starting row number (1-indexed). Defaults to 1.
- `start_col`: `string` *(optional)*
  - Starting column letter. Defaults to A.
- `max_rows`: `integer` *(optional)*
  - Maximum rows to return. Defaults to 1000, maximum allowed is 1000.
- `max_cols`: `integer` *(optional)*
  - Maximum columns to return. Defaults to 100, maximum allowed is 100.
- `drive_id`: `string` *(optional)*
  - Optional drive ID for shared items. If omitted, uses the user's default OneDrive.
- `session_id`: `string` *(optional)*
  - Optional session ID from a previous operation for better performance.

**OAuth Scopes:**
- `Files.Read`

**Output:** `json`
- Worksheet data in sparse dict format with pagination.

**Example:**

```json
{
  "tool": "MicrosoftExcel.GetWorksheetData",
  "parameters": {
    "item_id": "01ABCDabcd2345EF!678",
    "worksheet": "Sales Q1",
    "start_row": 2,
    "start_col": "B",
    "max_rows": 250,
    "max_cols": 10,
    "drive_id": "b!2aB3cD4EfGhIjK",
    "session_id": "3f7a9b2c-4d1e-11ee-8c99-0242ac120002"
  },
  "requires_auth": true,
  "auth_provider": "microsoft",
  "scopes": [
    "Files.Read"
  ]
}
```

---

### MicrosoftExcel.RenameWorksheet

**Version:** 0.2.0

Rename an existing worksheet in the workbook.

Note: The new name may not be immediately visible to other tools due
to a brief Graph API propagation delay (up to ~10 s). Pass the returned
``session_id`` to subsequent calls that reference the renamed worksheet
to mitigate this. If referencing a recently added worksheet as the source,
the same delay applies; retry with the ``session_id`` if a
WorksheetNotFoundError occurs.

**Parameters:**

- `item_id`: `string` *(required)*
  - The ID of the Excel workbook.
- `worksheet`: `string` *(required)*
  - Current name of the worksheet to rename.
- `new_name`: `string` *(required)*
  - New name for the worksheet.
- `drive_id`: `string` *(optional)*
  - Optional drive ID for shared items. If omitted, uses the user's default OneDrive.
- `session_id`: `string` *(optional)*
  - Optional session ID from a previous operation for better performance.

**OAuth Scopes:**
- `Files.ReadWrite`

**Output:** `json`
- The renamed worksheet info.

**Example:**

```json
{
  "tool": "MicrosoftExcel.RenameWorksheet",
  "parameters": {
    "item_id": "01234567-89ab-cdef-0123-456789abcdef",
    "worksheet": "Sheet1",
    "new_name": "Summary Q1 2026",
    "drive_id": "b!A1B2C3D4E5F6G7H8I9J0K",
    "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "requires_auth": true,
  "auth_provider": "microsoft",
  "scopes": [
    "Files.ReadWrite"
  ]
}
```

---

### MicrosoftExcel.UpdateCell

**Version:** 0.2.0

Update a single cell value in an Excel workbook.

Supports strings, numbers, booleans, and formulas (values starting with '=').

Note: If referencing a recently added or renamed worksheet, pass the
``session_id`` from that operation. A brief Graph API propagation delay
(up to ~10 s) may cause a WorksheetNotFoundError; retry with the
``session_id`` if this occurs.

**Parameters:**

- `item_id`: `string` *(required)*
  - The ID of the Excel workbook.
- `column`: `string` *(required)*
  - Column letter or letters (e.g., 'A', 'BC').
- `row`: `integer` *(required)*
  - Row number (1-indexed).
- `value`: `string` *(required)*
  - The value to set. Supports strings, numbers, booleans, and formulas (e.g., '=SUM(A1:A10)').
- `worksheet`: `string` *(optional)*
  - Worksheet name to update. If omitted, updates the first worksheet.
- `drive_id`: `string` *(optional)*
  - Optional drive ID for shared items. If omitted, uses the user's default OneDrive.
- `session_id`: `string` *(optional)*
  - Optional session ID from a previous operation for better performance.

**OAuth Scopes:**
- `Files.ReadWrite`

**Output:** `json`
- Confirmation of the cell update.

**Example:**

```json
{
  "tool": "MicrosoftExcel.UpdateCell",
  "parameters": {
    "item_id": "01234567-89ab-cdef-0123-456789abcdef",
    "column": "C",
    "row": 5,
    "value": "=SUM(C1:C10)",
    "worksheet": "Quarterly Budget",
    "drive_id": "b!a1B2c3D4e5F6g7H8",
    "session_id": "session-123e4567-e89b-12d3-a456-426614174000"
  },
  "requires_auth": true,
  "auth_provider": "microsoft",
  "scopes": [
    "Files.ReadWrite"
  ]
}
```

---

### MicrosoftExcel.UpdateRange

**Version:** 0.2.0

Update multiple cells in a worksheet using sparse dict format.

Only specified cells are updated; unspecified cells remain unchanged.
The data format is the same as Google Sheets update_cells.

Internally, a single PATCH request is sent covering the bounding box
of all specified cells.  Cells within the box that are not in the
input are sent as ``null``, which the Graph API treats as "skip".

Note: If referencing a recently added or renamed worksheet, pass the
``session_id`` from that operation. A brief Graph API propagation delay
(up to ~10 s) may cause a WorksheetNotFoundError; retry with the
``session_id`` if this occurs.

**Parameters:**

- `item_id`: `string` *(required)*
  - The ID of the Excel workbook.
- `data`: `string` *(required)*
  - JSON string where data[ROW][COL] = VALUE. ROW is a row number as string, COL is a column letter (uppercase), VALUE is string/number/boolean/null. Type: dict[str, dict[str, str | int | float | bool | None]].
- `worksheet`: `string` *(optional)*
  - Worksheet name to update. If omitted, updates the first worksheet.
- `drive_id`: `string` *(optional)*
  - Optional drive ID for shared items. If omitted, uses the user's default OneDrive.
- `session_id`: `string` *(optional)*
  - Optional session ID from a previous operation for better performance.

**OAuth Scopes:**
- `Files.ReadWrite`

**Output:** `json`
- Confirmation of the range update with cell count.

**Example:**

```json
{
  "tool": "MicrosoftExcel.UpdateRange",
  "parameters": {
    "item_id": "01234567-89ab-cdef-0123-456789abcdef",
    "data": "{\"1\":{\"A\":\"Name\",\"B\":\"Amount\"},\"2\":{\"A\":\"Alice\",\"B\":1234.56,\"C\":true},\"3\":{\"A\":\"Bob\",\"B\":null,\"C\":false},\"10\":{\"D\":\"Note\"}}",
    "worksheet": "Expenses",
    "drive_id": "b!aBcD_ExampleDriveId123",
    "session_id": "session_01ab23"
  },
  "requires_auth": true,
  "auth_provider": "microsoft",
  "scopes": [
    "Files.ReadWrite"
  ]
}
```

---

### MicrosoftExcel.WhoAmI

**Version:** 0.2.0

Get information about the current user and their Microsoft Excel environment.

**Parameters:** None

**OAuth Scopes:**
- `User.Read`

**Output:** `json`
- Get comprehensive user profile and Microsoft Excel environment information.

**Example:**

```json
{
  "tool": "MicrosoftExcel.WhoAmI",
  "parameters": {},
  "requires_auth": true,
  "auth_provider": "microsoft",
  "scopes": [
    "User.Read"
  ]
}
```

---


*Documentation generated: 2026-02-25T11:25:44.381Z*