# Smartsheet MCP server tools

The Smartsheet Model Context Protocol (MCP) server provides a way to leverage Smartsheet’s public API via AI clients, allowing you to interact with your data using natural language. The MCP server's underlying **tools** (operations) interact with your Smartsheet data (with your permission) to respond to your prompts. The following sections describe the key tools available to your AI client once [connected](/ai-mcp/smartsheet/install-the-smartsheet-mcp-server) to the Smartsheet MCP server.

**Required plan:**  Business, Enterprise, or Advanced Work Management

To execute any tool, your AI client requires specific OAuth access scopes. Each tool lists its Access scopes below its name.

For starters, explore the discovery and navigation tools.

*Tokens* are the basic units that AI language models use to process text. They're chunks of text that can be individual words, parts of words, or even punctuation marks. Both your input and the AI's responses are measured in tokens. This matters because:

- Models have maximum token limits (context windows)
- Processing speed decreases with increasing token count


The tools are subject to Smartsheet API [rate limiting](/api/smartsheet/guides/advanced-topics/scalability-options#rate-limiting) and [standard limitations](/api/smartsheet/guides/basics/limitations).

## Discovery and navigation

### search

**Access scopes:** `READ_SHEETS`

The **search** tool is a discovery tool that lets you search across all accessible Smartsheet assets to find resources by name or content.

This tool is particularly useful as a starting point when you need to find an asset ID before using other Smartsheet tools like `browse_workspace`, `browse_folder`, or `get_sheet_summary`.

**Basic Parameters**

- **`query`** (required): The search term to look for. Use specific terms like "Q4 Budget" for better results. You can use double-quotes for exact matches (e.g., `"Q4 Budget 2024"`).
- **`scopes`** (optional): Narrow your search to specific asset types. Available scopes include:
  - `sheetNames` — Search in sheet names
  - `reportNames` — Search in report names
  - `sightNames` — Search in dashboard names
  - `folderNames` — Search in folder names
  - `workspaceNames` — Search in workspace names
  - `cellData` — Search within cell contents
  - `comments` — Search in comments
  - `attachments` — Search in file attachments
  - `summaryFields` — Search in summary fields
  - `templateNames` — Search in template names
- **`modified_since`** (optional): Filter results by modification date using ISO 8601 timestamp format to find resources changed after a specific date.


**Key Features**

- **Fuzzy Matching**: Supports approximate matching, so you don't need exact names.
- **Results Context**: Returns asset names, types, parent folder/workspace context, match excerpts, and favorite indicators.
- **Maximum Results**: Returns up to 100 results (no pagination available).
- **Wide Coverage**: Can search across sheets, reports, dashboards, folders, workspaces, and more in one call.


**Limitations**

- Eventually consistent (new items may take a few minutes to appear in search results).
- First-time API users may experience a 24-hour data provisioning delay.
- Returns maximum 100 results with no pagination options.


**Use Cases**

- **Discover assets**: Find sheets, reports, or dashboards when you don't know exact IDs or locations.
- **Locate by content**: Search for specific text within sheets or comments.
- **Browse by modification date**: Find recently updated assets.
- **Find attachments**: Locate files attached to sheets or discussions.


## Workspaces and folders

### browse_workspace

**Access scopes:** `READ_SHEETS`

The **browse_workspace** tool lets you explore all the contents of a workspace, discovering the top-level sheets, reports, dashboards, and folders it contains. Here's the breakdown:

**Basic Parameters**

- **`workspace_id`** (required): The ID of the workspace to browse. Obtain this from `list_workspaces` or the `search` tool.
- **`asset_types`** (optional): Filter results by specific resource types:
  - `folders` — Nested folders
  - `sheets` — Individual sheets
  - `reports` — Reports
  - `sights` — Dashboards
  - `templates` - Templates
If not specified, returns all asset types.
- **`max_item`** (optional): Control page size (1–1000 items per page; defaults to 100).
- **`last_key`** (optional): Token for pagination. Use the `last_key` from a previous response to fetch the next page of results.


**Key Features**

- **Top-Level Only**: Returns direct children of the workspace (not recursively nested contents within folders).
- **Token-Based Pagination**: Supports pagination via `last_key` for workspaces with more than 100 items.
- **Server-Side Filtering**: Filter by asset type during the request, not after retrieving results.
- **Asset Information**: Returns names, IDs, types, creation/modification dates, and favorite status for each asset.


**Limitations**

- Returns only top-level workspace contents (doesn't drill into nested folder structures).
- Maximum 1000 items per page.
- Requires a valid workspace ID.


**Use Cases**

- **Discover workspace structure**: See all sheets, reports, and dashboards at the workspace root level.
- **Find assets by type**: List only sheets or only dashboards in a workspace.
- **Navigate hierarchically**: Get folder IDs to use with `browse_folder` for deeper exploration.
- **Inventory assets**: Audit what's in a workspace without searching.


### browse_folder

**Access scopes:** `READ_SHEETS`

The `browse_folder` tool navigates and explores the contents of a specific folder within Smartsheet. It retrieves all direct children of a folder—including nested folders, sheets, reports, and dashboards—making it essential for hierarchical folder navigation. This tool helps users discover and access assets organized within folder structures without needing to know exact resource IDs in advance.

**Basic Parameters**

- `folder_id` - The unique identifier of the folder to browse (positive integer; obtain from search results, `browse_workspace` results, or parent folder responses).
- `asset_types` - (Optional) Filter results by resource type; acceptable values are "folders", "sheets", "reports", "sights" (dashboards) or "templates". Pass as an array to filter for multiple types, or omit to return all asset types.
- `last_key` - (Optional) Pagination token from a previous response used to fetch the next page of results; leave empty for the first page.
- `max_item` - (Optional) Number of items to return per page, ranging from 1 to 1000; defaults to 100.


**Key Features**

- **Hierarchical Navigation** - Returns only direct children of the specified folder, allowing step-by-step exploration of nested folder structures.
- **Asset Type Filtering** - Efficiently narrow results to specific resource types (folders, sheets, reports, dashboards) to surface only the resources you need.
- **Pagination Support** - Handles large folder contents through token-based pagination; use the `last_key` parameter to retrieve subsequent pages when more than 100 items exist.
- **Complete Asset Details** - Provides metadata for each child resource, including IDs, names, permalinks, and ownership information needed for downstream operations.


**Limitations**

- Returns only direct children, not a recursive tree of all nested contents.
- Maximum of 1000 items returned per page; folders with more than 100 children require pagination.
- Does not include folder content counts or summary statistics for performance reasons.


**Use Cases**

- **Folder Content Exploration** - Browse the contents of a folder to discover sheets, reports, dashboards, and subfolders without knowing their exact IDs.
- **Asset Filtering** - Filter results to show only sheets or only reports within a folder for focused navigation.
- **Hierarchical Traversal** - Use folder_id values returned from browse_folder results to navigate deeper into nested folder structures.
- **Pagination Through Large Folders** - Systematically retrieve all contents of folders with more than 100 items using token-based pagination.
- **Asset Inventory** - Build a complete map of folder structure and contents for administrative or archival purposes.


### list_workspaces

**Access scopes:** `READ_SHEETS`

Retrieves a list of workspaces from Smartsheet with pagination support. This tool is essential for discovering and managing all workspaces within a Smartsheet account, allowing you to browse the organization's workspace structure without nested content exploration.

**Best Practices**

- Use pagination parameters (`last_key` and `max_item`) when working with large numbers of workspaces to avoid overwhelming API responses.
- Store workspace IDs after retrieval for use in subsequent operations like creating sheets, folders, or browsing workspace contents.
- Cache workspace lists locally if you perform frequent lookups to reduce API calls.
- Set `max_item` appropriately based on your needs; smaller values reduce response size while larger values (up to 1000) retrieve more results in a single call.


**Basic Parameters**

- `last_key` (optional string): Token used for server-side pagination to retrieve the next page of workspaces. Leave empty for the first request.
- `max_item` (optional integer, default 100): Maximum number of workspace items to return per page. Range: 1–100.


**Key Features**

- **Pagination support**: Retrieve workspaces in manageable batches using `last_key` for cursor-based pagination across large workspace lists.
- **Flexible page sizing**: Control result set size with `max_item` to balance between API efficiency and result count.
- **Workspace discovery**: Get a comprehensive list of all accessible workspaces in your Smartsheet account with a single call.
- **Token-based navigation**: Use returned `last_key` values to traverse large result sets without offset limitations.


**Limitations**

- Maximum 1000 items returned per request (enforced by `max_item` parameter cap).
- Returns top-level workspace list only; does not include workspace contents.
- Requires valid Smartsheet authentication; cannot list workspaces from other accounts.
- No filtering by workspace type or attributes available; returns all accessible workspaces.


**Use Cases**

- **Initial workspace discovery**: Retrieve all workspaces to present users with a selection menu or dashboard.
- **Workspace enumeration**: Build a complete inventory of workspaces for auditing or reporting purposes.
- **Paginated browsing**: Handle accounts with hundreds of workspaces by iterating through pages with pagination tokens.
- **Workspace ID lookup**: Obtain workspace IDs needed as prerequisites for creating sheets, folders, or accessing workspace contents.


### create_workspace

**Access scopes:** `ADMIN_WORKSPACES`

`create_workspace` creates a new workspace with a name. A workspace is a top-level container that organizes sheets, reports, dashboards, and folders within your Smartsheet environment. This tool enables you to establish a new organizational structure for your projects and data management.

**Best Practices**

- Use descriptive and meaningful workspace names that reflect the purpose or team associated with the workspace.
- Consider naming conventions that align with your organization's standards for consistency across multiple workspaces.


**Basic Parameters**

- `name` - The name to assign to the new workspace.


**Key Features**

- **Workspace creation** - Establishes a new top-level container for organizing Smartsheet assets.
- **Foundation for hierarchy** - Serves as the parent container for folders, sheets, reports, and dashboards.


**Limitations**

- Workspace names that are empty or whitespace-only are rejected at validation time.
- Workspace names that are longer than 50 characters are rejected at validation time.


**Use Cases**

- **Team-based organization** - Create separate workspaces for different teams or departments to maintain clear separation of work and resources.
- **Project management** - Establish a workspace dedicated to a specific project to house all related sheets, reports, and tracking documents.
- **Department structuring** - Set up workspaces for different functional areas such as Finance, Marketing, or Operations to organize departmental assets centrally.


### create_folder

**Access scopes:** `ADMIN_WORKSPACES`

`create_folder` creates a new folder within a specified workspace or parent folder, enabling hierarchical folder organization within Smartsheet.

**Best Practices**

- Establish a clear naming convention before creating folders to maintain consistency across workspaces and nested folder structures.
- Use the `browse_workspace` tool or the `browse_folder` tool to verify the container ID and type before calling this tool.
- Verify you have `ADMIN` permissions on the target container before attempting to create folders.


**Basic Parameters**

- `parent_id`: The ID of the workspace or parent folder in which to create the new folder. Obtain this value from the `list_workspaces` tool, the `browse_workspace` tool, or the `browse_folder` tool. This parameter is required.
- `parent_type`: The type of container receiving the new folder. Accepted values are `WORKSPACE` and `FOLDER`. This parameter is required.
- `folder`: A folder object containing the `name` property, which specifies the folder's display name. The name must be non-empty and unique within the parent container. This parameter is required.


**Key Features**

- **Unified container support**: Creates folders in either a workspace or a parent folder through a single tool, replacing two separate tools.
- **Hierarchical organization**: Supports building multi-level folder structures by targeting either a top-level workspace or an existing folder as the parent container.
- **Unique naming enforcement**: Enforces unique folder names within each parent container to maintain organization clarity.
- **Folder details returned**: Returns the created folder's ID and permalink for reference and use in further operations.
- **Deep nesting support**: Smartsheet supports deep folder nesting, allowing you to create complex organizational hierarchies.


**Limitations**

- User must have `ADMIN` permissions on the target container (workspace or folder) to create folders.
- Folder names must be unique within the parent container.
- Folder names that are empty or whitespace-only are rejected at validation time.
- Folder names that are longer than 50 characters are rejected at validation time.


**Use Cases**

- **Project organization**: Create separate folders for different projects or departments directly within a workspace or nested inside an existing folder.
- **Asset categorization**: Organize sheets by team, function, or business unit at any level of the folder hierarchy.
- **Workspace setup**: Establish the initial top-level folder structure when building out a new workspace.
- **Client management**: Build hierarchical folder structures to separate different clients and their associated sheets, reports, and dashboards.
- **Template libraries**: Organize template sheets in nested folders by category or purpose for easy discovery and reuse.
- **Archive structure**: Create dated or categorized sub-folders within an archive folder to maintain historical records in an organized manner.


## Solutions

### create_workspace_assets

**Access scopes:** `ADMIN_WORKSPACES`, `ADMIN_SHEETS`, `CREATE_SHEETS`, `WRITE_SHEETS`, `CREATE_SIGHTS`

**Toolset:** `ai_solutions`

The `create_workspace_assets` tool is an AI agent that builds comprehensive, end-to-end Smartsheet solutions from natural language descriptions. It can create any combination of workspaces, sheets, dashboards, workflows, reports, forms, portfolios, projects, and blueprints in a single call. The caller can describe what to build explicitly or describe a problem, and the agent designs and generates an appropriate solution autonomously. This tool is optimized for multi-asset, integrated solutions and is not intended for creating a single asset in isolation.

This tool is unavailable for the Microsoft 365 Copilot Connector (the Copilot Studio connector for Copilot Chat)

**Basic Parameters**

- **`message`** (required): Natural language description of what to create or the problem to solve. Maximum 1000 characters.


**Key Features**

- **End-to-end solution generation**: Creates a complete, integrated Smartsheet solution in one call, handling workspace setup through individual asset creation automatically.
- **Multi-asset output**: Returns summaries for all created assets — sheets, dashboards, automations, reports, forms, portfolios, projects, and blueprints — each with their ID and permalink.
- **Problem-driven design**: Accepts either an explicit specification or a problem description, and the AI determines the appropriate solution architecture.
- **Progress reporting**: Reports progress as work proceeds during multi-step creation operations.


**Limitations**

- Creation time varies with complexity; typical completion is 1–2 minutes, and complex multi-asset solutions may take longer.
- The AI makes best-effort interpretations of ambiguous requirements; vague descriptions may produce incomplete or unexpected results.
- Not intended for creating a single asset — use individual tools for single-asset operations.
- In rare cases, a needed asset type may not be created; check the returned summary and fall back to individual creation tools as needed.


**Use Cases**

- **Project tracking workspace**: Build a complete project tracking solution with intake sheets, status dashboards, automated notifications, and summary reports from a single description.
- **Problem-driven setup**: Describe a business problem (for example, "I need to track vendor onboarding") and let the AI design and provision the full Smartsheet solution.
- **Portfolio initialization**: Stand up a portfolio with project templates, a project list sheet, and portfolio-level dashboards in one request.
- **Data collection pipeline**: Create an end-to-end solution that includes a form for data collection, a backing sheet, automated row routing, and an executive dashboard.
- **Cross-functional workspace**: Generate a workspace spanning multiple teams with sheets, shared reports, and role-appropriate dashboards from a natural language brief.


## Sheets

### get_sheet_path

**Access scopes:** `READ_SHEETS`

`get_sheet_path` gets the full hierarchical path of a sheet within the Smartsheet workspace, including a UNIX-style path and a direct permalink, without loading the sheet itself.

**Best Practices**

The following items are best practices for using the `get_sheet_path` tool:

- Provide at least one of `sheet_id` or `url`. The tool requires at least one value to locate the sheet.
- If providing both `sheet_id` and `url`, ensure they refer to the same sheet. Mismatched values result in an error.
- Use this tool instead of the `get_sheet_summary` tool when only the sheet's location or permalink is needed, since it avoids loading sheet content.


**Basic Parameters**

The `get_sheet_path` tool has the following parameters:

- `sheet_id`: The numeric ID of the target sheet. The `sheet_id` parameter defaults to `null`.
- `url`: The URL of the target sheet. The `url` parameter defaults to `null`.


**Key Features**

The `get_sheet_path` tool has the following key features:

- **Hierarchical path**: Returns the full folder structure from the workspace root to the sheet as a UNIX-style path, making it easy to understand where the sheet resides.
- **Direct permalink**: Returns a shareable permalink to the sheet without requiring the sheet's content to be loaded.
- **Lightweight lookup**: Retrieves location metadata only, without loading sheet rows, columns, or other content.
- **Flexible input**: Accepts either a sheet ID or a sheet URL as input, accommodating different starting points.


**Limitations**

The `get_sheet_path` tool has the following limitations:

- At least one of `sheet_id` or `url` must be provided. If both are provided, they must refer to the same sheet.
- Requires workspace-level access to the sheet. If the user does not have this access, the API returns a 404 error.
- The returned path reflects only the folder structure up to the sheet and does not include any sheet content.


**Use Cases**

The following items describe use cases for the `get_sheet_path` tool:

- **Locating a sheet**: Determine where a sheet lives within the workspace hierarchy without loading the sheet itself.
- **Generating a shareable link**: Retrieve a direct permalink to a sheet for sharing with collaborators.
- **Workspace navigation**: Quickly identify the folder path of a sheet as part of a broader workspace audit or inventory task.
- **Lightweight sheet lookup**: Use in place of the `get_sheet_summary` tool when only location metadata is needed, reducing unnecessary data retrieval.


### get_sheet_summary

**Access scopes:** `READ_SHEETS`

Retrieves sheet data with optional multi-column filtering, sorting, and column selection. This tool lets you analyze, summarize, or work with Smartsheet data flexibly by narrowing results to exactly what you need.

**Best Practices**

- **Call `get_columns` first** when using filters, sorting, or column selection parameters to get exact case-sensitive column names—guessing column names results in validation errors.
- Provide either a Smartsheet URL or a `sheet_id`, but not both (if both are provided, they must match).
- Apply filters and column selection to minimize data transfer and improve performance.
- Use filters to narrow results down to specific records.
- Remember that column names are case-sensitive.


**Basic Parameters**

- `url` (optional) — Smartsheet URL for the sheet.
- `sheet_id` (optional) — Numeric ID of the sheet.
- `filters` (optional) — Array of column filters with AND logic (requires column name, operator, and value).
- `sorting` (optional) — Array of sort criteria specifying column name and direction (ASCENDING or DESCENDING).
- `columns` (optional) — List of specific column names to fetch (narrows returned data).


**Key Features**

- **Multi-column filtering** — Apply multiple filters using AND logic with operators like EQUAL, NOT_EQUAL, LESS_THAN, GREATER_THAN, and comparison variants.
- **Flexible sorting** — Sort results by one or more columns in ascending or descending order.
- **Column selection** — Specify only the columns you need to reduce payload size.
- **Data exploration** — Returns available columns metadata for subsequent use when called without filters.
- **High-capacity data access** — Handles large sheets with intelligent sampling when data exceeds token limits.


**Limitations**

- Data is limited to approximately 8,000 tokens, so very large sheets may return sampled rows.
- Filters use AND logic only (no OR conditions).
- Column names are case-sensitive; validation errors occur if names don't match exactly.
- Sorting falls back to Modified Date DESC or primary column ASC if not explicitly specified.
- Must provide either a URL or sheet ID (at least one is required)


**Use Cases**

- **Data analysis and reporting** — Summarize sheet contents, extract key metrics, or prepare data for external reporting.
- **Filtered data retrieval** — Pull only rows matching specific criteria (e.g., all tasks with status "In Progress").
- **Sorted data views** — Organize results by priority, date, or other columns for quick review.
- **Column-focused queries** — Fetch specific columns to reduce noise and focus on relevant information.
- **Pre-deletion verification** — Review sheet data before using destructive operations like row deletion.
- **Dynamic dashboarding** — Feed filtered, sorted data into dashboards or external applications.


### get_sheet_version

**Access scopes:** `READ_SHEETS`

The `get_sheet_version` tool retrieves the current version number of a Smartsheet without loading the entire sheet. Version numbers increment on any modification to the sheet, making this a lightweight change detection mechanism.

**Best Practices**

- Use version polling to determine if a full sheet refresh is needed before calling resource-intensive tools like `get_sheet_summary`.
- Store the version number locally and compare it on subsequent calls to track changes efficiently.
- Combine with other tools: call `get_sheet_version` first to check if the sheet has changed since your last retrieval.
- Provide either a Smartsheet URL or a sheet_id, but not both (if both are provided, they must match).


**Basic Parameters**

- `sheet_id`: The numeric identifier for the sheet (optional if URL is provided).
- `url`: The Smartsheet URL for the sheet (optional if sheet_id is provided).


**Key Features**

- **Minimal Payload**: Returns only the version number without any row, column, or metadata content.
- **Change Detection**: Version increments automatically on cell value changes, comments, row modifications, attachments, and formatting updates.
- **Monotonic Versioning**: Version numbers are strictly increasing integers that start at zero.


**Limitations**

- Returns only a version number with no historical data or change details.
- Cannot retrieve previous version numbers or version history.
- Does not indicate what changed, only that a change occurred.


**Use Cases**

- **Caching Strategy**: Implement efficient caching by storing the version number and re-fetching full data only when the version changes.
- **Lightweight Monitoring**: Continuously monitor sheets for modifications without the overhead of loading entire datasets.
- **Conditional Updates**: Determine whether other tools need to be called based on whether the sheet version has incremented.


### find_in_sheet

**Access scopes:** `READ_SHEETS`

The `find_in_sheet` tool searches for text within a specific Smartsheet sheet. It returns matching cells with row and column IDs, display values, and character offsets for each match. It supports case-sensitive search, column-scoped filtering, formula-based filtering, sorting, and pagination.

**Best Practices**

- Restrict the search to specific columns using the `columns` parameter when you know where the target data lives, to improve performance and reduce noise.
- Use the `filter` parameter with a formula (for example, `=OR([Status]@row = "Active")`) to pre-filter rows before the search term is applied, narrowing results to relevant data.
- Use pagination (`limit` and `offset`) when working with large sheets to manage result set size.


**Basic Parameters**

- `sheet_id` — The integer ID of the target sheet to search within.
- `request.term` — The search term to look for, between 1 and 250 characters.
- `request.caseSensitive` — Boolean flag indicating whether the search is case-sensitive. It defaults to `false`.
- `request.columns` — An optional array of column IDs that restricts the search to only those columns.
- `request.filter` — An optional formula string (must begin with `=`) applied to filter rows before searching.
- `request.sort` — An optional array of up to three sort criteria, each specifying a column name and sort direction (`ASC` or `DESC`).
- `limit` — The maximum number of results to return per page. Accepts values from 1 to 20,000. It dßefaults to 100.
- `offset` — The zero-based pagination offset for retrieving subsequent pages of results.


**Key Features**

- **Cell-level results** — Returns matches at the individual cell level, including the row ID, column ID, display value, and character offset of the match within the cell.
- **Column scoping** — Restricts the search to a specified subset of columns, reducing irrelevant matches.
- **Formula filtering** — Applies a Smartsheet formula as a pre-search row filter, enabling logic-based scoping before the term is evaluated.
- **Case sensitivity control** — Toggles case-sensitive matching on or off to suit the precision requirements of the search.
- **Multi-column sorting** — Sorts the result set by up to three columns, each with an independent direction.
- **Pagination support** — Supports high-volume result sets with configurable page size (up to 20,000 results) and offset-based paging.


**Use Cases**

- **Data auditing** — Locate all cells containing a specific value, such as a vendor name or status code, across an entire sheet for review or correction.
- **Targeted column search** — Scope a search to one or more specific columns to find entries like duplicate email addresses or incorrectly-formatted dates without scanning irrelevant data.
- **Conditional data lookup** — Combine a formula filter with a search term to find matching cells only within rows that meet a business condition, such as only active projects or open tickets.


### create_sheet

The `create_sheet` tool creates a new sheet within a specified Smartsheet folder or workspace.

The tool supports two creation modes:

- Building a blank sheet from scratch with fully custom column definitions
- Instantiating a sheet from an existing template


The `create_sheet` tool serves as the primary entry point for adding new structured data grids to an organization's Smartsheet environment.

**Access scopes:** `CREATE_SHEETS`

**Best Practices**

The following items are best practices for using the `create_sheet` tool:

- Always designate exactly one column as the primary column (using `primary: true`) when creating a blank sheet, and ensure that column is of type `TEXT_NUMBER`.
- When creating from a template, use the `include` parameter to selectively copy only the elements you need (such as `data`, `attachments`, or `rules`) to avoid unnecessary duplication.
- Verify the target container ID and type before calling this tool, using the `browse_folder` or `browse_workspace` tool to confirm the destination exists and that you have edit permissions on it.
- Choose column types carefully at creation time, as restructuring columns after rows have been added is more disruptive.


**Basic Parameters**

The `create_sheet` tool has the following parameters:

- `container_id` — The integer ID of the folder or workspace in which to create the sheet.
- `container_type` — The type of container, either `FOLDER` or `WORKSPACE`.
- `sheet` — The sheet definition object. Pass a `CreateSheet` object (with a `name` and `columns` array) for a blank sheet, or a `CreateSheetFromTemplate` object (with a `name` and `fromId`) when creating from a template.
- `include` — An optional list of elements to copy from the template when using `CreateSheetFromTemplate`. Valid values are `attachments`, `cellLinks`, `data`, `discussions`, `filters`, `forms`, `ruleRecipients`, and `rules`. This parameter is ignored when creating a blank sheet.


**Key Features**

The `create_sheet` tool has the following key features:

- **Blank sheet creation** — Accepts a fully custom column schema, allowing you to define column titles, types, options, formulas, formatting, and system column types (such as `AUTO_NUMBER`, `CREATED_DATE`, or `MODIFIED_BY`) at creation time.
- **Template-based creation** — Creates a new sheet pre-populated with the structure (and optionally the content) of any accessible template by referencing its ID via `fromId`.
- **Selective template element copying** — When creating from a template, the `include` parameter lets you choose exactly which elements (data, attachments, discussions, filters, forms, rules, etc.) to copy into the new sheet.
- **Flexible container targeting** — Supports placing the new sheet in either a folder or a workspace by specifying the `container_type` and `container_id`.
- **Project and Gantt configuration** — Accepts optional `ganttEnabled`, `dependenciesEnabled`, `resourceManagementEnabled`, and `projectSettings` fields to configure the sheet as a project sheet at creation time.
- **Rich column typing** — Supports a full range of column types including `TEXT_NUMBER`, `DATE`, `DATETIME`, `CHECKBOX`, `CONTACT_LIST`, `MULTI_CONTACT_LIST`, `PICKLIST`, `MULTI_PICKLIST`, `PREDECESSOR`, `DURATION`, and `ABSTRACT_DATETIME`.


**Limitations**

The `create_sheet` tool has the following limitations:

- The sheet name must be unique within the target container; duplicate names in the same folder or workspace are not allowed.
- The user must have edit permissions on the parent container (folder or workspace).
- When creating from a template, the template must be accessible to the authenticated user.
- Exactly one column must be designated as the primary column when creating a blank sheet, and it must be of type `TEXT_NUMBER`.
- Column titles must remain unique within the sheet; duplicates cause the operation to fail.
- Column titles are limited to 50 characters.


**Use cases**

The following items describe use cases for the `create_sheet` tool:

- **Standardized project intake** — Create a new project tracking sheet from a pre-approved template, copying filters and rules so every project sheet starts with consistent structure and automation.
- **Dynamic report scaffolding** — Programmatically generate a blank sheet with a specific set of columns to serve as a data destination for an automated reporting workflow.
- **Team onboarding** — Spin up a personal task sheet for each new team member inside a shared workspace, using a template that includes standard columns and pre-filled data rows.
- **Gantt project initialization** — Create a sheet with `ganttEnabled` and `dependenciesEnabled` set to `true` and pre-tagged `GANTT_START_DATE`, `GANTT_END_DATE`, and `GANTT_PREDECESSOR` columns to immediately support dependency-driven scheduling.
- **Audit trail sheets** — Create a sheet that includes `CREATED_BY`, `CREATED_DATE`, `MODIFIED_BY`, and `MODIFIED_DATE` system columns to automatically capture row-level audit information.


## Columns

### get_columns

**Access scopes:** `READ_SHEETS`

The `get_columns` tool retrieves detailed column metadata from a Smartsheet, allowing you to discover all available columns in a sheet along with their properties and types.

**Basic Parameters**

- `sheet_id` (optional): The numeric identifier of the sheet to retrieve columns from.
- `url` (optional): A valid Smartsheet URL to retrieve columns from (you must provide at least one of sheet_id or url).


**Key Features**

- **Complete metadata discovery**: Returns all columns in a sheet with their IDs, names, types, and properties.
- **Column type information**: Identifies column types such as TEXT_NUMBER, DATE, PICKLIST, CHECKBOX, CONTACT_LIST, and more.
- **Preparation for other operations**: Essential to run before using filters, sorting, or column selection in other tools since column names are case-sensitive.
- **Property inspection**: Shows column-specific properties like options for picklists, auto-number formats, and system column designations.


**Limitations**

- This tool returns metadata only and does not retrieve row data itself.


**Use Cases**

- **Discovering available columns**: Explore the complete structure of a sheet before writing filters or retrieving data.
- **Validating column names**: Confirm exact case-sensitive column names before using them in filters, sorting, or column selection parameters.
- **Planning data operations**: Understand column types and properties to design appropriate filtering and sorting strategies.
- **Column reference**: Obtain column IDs needed for other operations like updating columns, deleting columns, or retrieving cell history.


### add_columns

**Access scopes:** `ADMIN_SHEETS`

The `add_columns` tool adds one or more new columns to a specified Smartsheet with customizable properties such as type, position, formula, and validation rules.

**Best Practices**

- Use a common index value as the starting point when creating multiple columns at once; subsequent columns automatically increment their index positions.
- Ensure column titles are unique within the sheet to avoid naming conflicts.
- Define appropriate column types upfront to enable proper data validation and formatting.
- Use formulas for computed columns to maintain data consistency across your sheet.


**Basic Parameters**

- `sheet_id` - The numeric identifier of the sheet where columns is to be added.
- `columns` - An array of column objects, each containing required and optional properties that define the column structure.
  - `title` - The display name for the column, which must be unique within the sheet. The maximum length is 50 characters.
  - `type` - The column type that determines how data is stored and displayed (e.g., TEXT_NUMBER, DATE, CONTACT_LIST, PICKLIST, CHECKBOX, DURATION, MULTI_CONTACT_LIST, MULTI_PICKLIST, DATETIME, ABSTRACT_DATETIME, PREDECESSOR).
  - `index` - A zero-based position indicating where the column is to be placed in the sheet layout.
  - `description` - An optional text field for documenting the column's purpose.
  - `formula` - An optional expression for computed columns that automatically calculate values.
  - `hidden` - An optional boolean to hide the column from the default view.
  - `locked` - An optional boolean to prevent editing of the column.
  - `format` - An optional display format string for customizing how data appears.
  - `options` - An array of predefined values for PICKLIST columns.
  - `primary` - An optional boolean flag to designate this as the primary column (only TEXT_NUMBER columns can be primary).
  - `symbol` - An optional symbol set name for enhanced visual representation.
  - `width` - An optional pixel value to set the column width.
  - `validation` - An optional boolean to enable validation rules for the column.
  - `autoNumberFormat` - An optional configuration object for auto-numbering systems with prefix, suffix, fill padding, and starting number.
  - `contactOptions` - An optional array of contact configurations for CONTACT_LIST columns, specifying name and email.
  - `systemColumnType` - An optional system-managed column type (AUTO_NUMBER, CREATED_BY, CREATED_DATE, MODIFIED_BY, MODIFIED_DATE).
  - `tags` - An optional array of column tags for special functionality (GANTT, CALENDAR, CARD, and BASELINE tags).


**Key Features**

- **Multiple column creation** - Add several columns in a single API call by providing an array of column definitions.
- **Flexible positioning** - Control exactly where columns appear using zero-based index values.
- **Type variety** - Support for text, numbers, dates, checkboxes, contacts, dropdowns, durations, and predecessors.
- **Formulas and automation** - Include formulas for dynamic, calculated values without manual updates.
- **Primary column designation** - Mark a TEXT_NUMBER column as primary to establish the sheet's main reference column.
- **Validation and locking** - Protect data integrity through optional validation rules and column locks.
- **System columns** - Create auto-populated columns that track creation/modification dates and users.
- **Advanced formatting** - Apply custom display formats, auto-numbering sequences, and symbol sets.
- **Column tagging** - Assign tags for Gantt charts, calendars, card views, and baseline tracking.
- **AI columns** - Use AISUMMARIZE, AITRANSLATE, or AISENTIMENT in a column formula. These functions make summaries, translations, and sentiment categories from other columns.


**Limitations**

- Multiple columns created in a single call must share the same starting index; individual index values cannot be specified for each column in the array.
- Primary columns are restricted to TEXT_NUMBER type only.
- Column titles must remain unique within the sheet; duplicates cause the operation to fail.
- Column titles are limited to 50 characters.
- The column id field is system-assigned and cannot be specified during creation.
- Auto-number fill padding is limited to a maximum of ten "0" characters.


**Use Cases**

- **Project tracking setup** - Create standard columns like Task Name (primary), Status, Assignee, and Due Date when initializing a new project sheet.
- **Budget tracking** - Add columns for budget categories, actual spend, variance calculations using formulas, and approval status.
- **Contact management** - Set up CONTACT_LIST columns for team members, stakeholders, and resource assignment tracking.
- **Gantt chart preparation** - Define date, duration, and predecessor columns with appropriate tags for timeline-based project visualization.
- **Inventory management** - Add columns for item codes (auto-numbered), descriptions, quantities, and unit prices with validation rules.
- **Status reporting** - Create picklist columns for status states, multi-select columns for feature tags, and checkbox columns for completion tracking.
- **AI columns** - Add columns with AISUMMARIZE, AITRANSLATE, or AISENTIMENT formulas for summaries, translations, or sentiment categories.


### update_column

**Access scopes:** `ADMIN_SHEETS`

`update_column` modifies the properties of an existing column in a Smartsheet. You can change the column's title, type, position, visibility, and other metadata to customize how your data is organized and displayed. (⚠️ destructive, irreversible)

**Best Practices**

- Always verify the correct column ID before updating.
- Be extremely cautious when changing column types, as this may cause data loss or unexpected conversions.
- Understand the impact on all rows when modifying column properties.
- Consider dependencies like formulas, automations, and reports that reference the column.
- Remember that there is no automatic undo for this operation.


**Basic Parameters**

- `sheet_id` – The identifier of the sheet containing the column.
- `column_id` – The identifier of the column to update.
- `column` – An object containing the properties you want to modify.


**Key Features**

- **Rename columns** – Change the column title without affecting data.
- **Reposition columns** – Use the index parameter to move a column to a different position in the sheet.
- **Modify visibility** – Hide or show columns using the hidden flag.
- **Update descriptions** – Add or change descriptive text for a column.
- **Adjust width** – Set a custom column width in pixels.
- **Change formulas** – Update formula expressions in calculated columns.
- **Lock columns** – Prevent accidental modifications by locking a column.
- **Update picklist options** – Modify the available options in a picklist or multi-picklist column.
- **Configure auto-numbering** – Set prefix, suffix, starting number, and padding for auto-number columns.
- **Adjust validation** – Enable or disable validation rules for a column.


**Limitations**

- You cannot change the type of a Primary column.
- System columns (such as Created Date or Modified Date) may have restricted modification options.
- Column titles must remain unique within the sheet; duplicates cause the operation to fail.
- Column titles are limited to 50 characters.


**Use Cases**

- **Reorganize sheet layouts** – Reorder columns to improve readability and workflow efficiency.
- **Maintain data structure** – Update column titles and descriptions as requirements change.
- **Enhance usability** – Hide internal columns or adjust column widths to optimize the interface.
- **Expand picklist options** – Add new choices to dropdown fields as your process evolves.
- **Configure formulas** – Modify calculated columns to reflect new business logic.


### delete_column

**Access scopes:** `ADMIN_SHEETS`

Permanently removes a column from a Smartsheet and all associated data within that column. This operation cannot be undone and affects all rows in the sheet. (⚠️ destructive, irreversible)

**Best Practices**

- Verify the column ID before deletion to ensure you're removing the correct column.
- Consider archiving or backing up the sheet before performing bulk column deletions.
- Double-check dependent formulas or reports that may reference the column being deleted.
- Inform team members before deleting columns that are actively in use.


**Basic Parameters**

- Sheet ID: The unique identifier for the Smartsheet containing the column.
- Column ID: The unique identifier of the column to be deleted.


**Key Features**

- **Permanent removal**: Completely eliminates the column and all its data from the sheet.
- **Full row impact**: Affects all rows in the sheet by removing values from that column.


**Limitations**

- No rollback capability after execution.
- Cannot selectively delete data from a column without deleting the entire column structure.
- Deletion affects all users and any reports or dashboards that depend on the column.


**Use Cases**

- **Cleanup**: Removing obsolete or unused columns from an active sheet.
- **Restructuring**: Eliminating columns during a sheet redesign or reorganization.
- **Data management**: Removing columns containing sensitive or deprecated information.


## Rows

### add_rows

**Access scopes:** `WRITE_SHEETS`

The `add_rows` tool adds one or more new rows to the specified sheet with optional positioning control for each row.

**Best Practices**

- Verify the sheet ID before adding rows to ensure you are adding to the correct sheet.
- Use location specifiers carefully to ensure rows are inserted in the intended position.
- Include only the columns you want to populate, leaving other columns empty as needed.
- When adding large batches, keep in mind the 500 row per API call limit.
- Populate cell values using either simple primitives (strings, numbers, booleans) or formulas depending on your data structure.


**Basic Parameters**

- `rows`: An array of row objects to add to the sheet. Each row object can contain cells and optional location specifiers to control insertion position.
- `sheet_id`: The ID of the sheet where rows are to be added. This parameter is required and must be a valid sheet ID.


**Key Features**

- **Flexible positioning**: Control where new rows are inserted using location specifiers such as toTop, toBottom, parentId, siblingId, above, indent, and outdent.
- **Cell data**: Populate cells with values, formulas, or formulas depending on the column type.
- **Batch operations**: Add multiple rows in a single API call for efficiency.
- **Hierarchical placement**: Use parentId and indent to create parent-child row relationships and multi-level hierarchies.


**Limitations**

- Images cannot be added directly to cells during row creation. You must upload images to cells after the row exists in the sheet.
- Maximum of 500 rows can be added in a single API call.
- Cell values larger than 4000 characters are silently truncated.


**Use Cases**

- **Bulk data import**: Add multiple rows at once when importing data from external sources.
- **Task creation**: Add new task rows to a project tracking sheet with default values and formulas.
- **Hierarchical organization**: Insert rows as children of parent rows to build project hierarchies or organizational structures.
- **Timeline expansion**: Add rows at specific positions to insert milestones or subtasks between existing rows.
- **Form responses**: Automatically add new rows to a sheet from form submissions or API webhooks.


### update_rows

**Access scopes:** `WRITE_SHEETS`

The `update_rows` tool modifies existing row data in Smartsheet. Updates are permanent and cannot be automatically undone. Verify row IDs and cell values before executing. (⚠️ destructive, irreversible)

**Best Practices**

- Always verify the correct row IDs before updating.
- Review the BulkItemResult.failed_items for any errors.
- Consider the impact on formulas and linked cells.
- Remember: There is no automatic undo for this operation.


**Basic Parameters**

- `rows`: An array of row objects to update, where each row includes an ID field to identify which row to update and optional fields for cell values and row positioning.
- `sheet_id`: The integer ID of the sheet containing the rows to update.


**Key Features**

- **Cell value updates**: Modify the values in one or more cells across multiple rows in a single operation.
- **Partial updates**: Only include the fields you want to change, leaving others unchanged.
- **Row repositioning**: Move rows while updating them, supporting various location specifiers (toTop, toBottom, parentId, siblingId).
- **Indent and outdent**: Adjust row hierarchy by indenting or outdenting rows relative to their siblings.
- **Partial success support**: If some rows fail to update, the operation continues and returns details about which rows succeeded and which failed, allowing for retry or user notification.


**Limitations**

- This operation does not add rows with cells that have images. However, you can upload an image to a cell after the cell exists in a sheet.
- When adding or updating rows, there is a 500 row limit for each API call.


**Use Cases**

- **Bulk cell updates**: Change values in multiple cells across several rows at once.
- **Status tracking**: Update project status fields, completion percentages, or assignment columns across multiple tasks.
- **Data corrections**: Modify incorrect data in existing rows without affecting other columns.
- **Hierarchy reorganization**: Move rows to different levels in a sheet hierarchy while simultaneously updating their data.
- **Batch operations**: Process multiple row updates in a single API call for efficiency.


### delete_rows

**Access scopes:** `WRITE_SHEETS`

`delete_rows` permanently removes one or more rows from a Smartsheet. This operation is irreversible and all data contained in the deleted rows is lost forever. (⚠️ destructive, irreversible)

**Best Practices**

- Always verify row IDs are correct before deletion.
- Consider backing up critical data before deletion.
- Use `get_sheet_summary` or other retrieval tools to confirm row contents first.
- Delete in small batches, with a maximum of 10 rows per request.
- Remember that there is no undo for this operation.
- Double-check you have the correct `sheet_id`.


**Basic Parameters**

- `sheet_id`: The ID of the sheet containing the rows to delete.
- `row_ids`: An array of row IDs to delete, with a maximum of 10 rows per request.


**Key Features**

- **Batch deletion**: Remove multiple rows in a single operation, up to 10 rows at a time.
- **Permanent removal**: Rows are completely and irreversibly deleted from the sheet.
- **All data lost**: Every cell value in deleted rows is permanently removed.


**Limitations**

- Maximum of 10 rows can be deleted in a single request.
- No undo or recovery is possible after deletion.
- All data in the affected rows is permanently lost.


**Use Cases**

- **Clean up obsolete records**: Remove outdated rows from project trackers or status sheets.
- **Archive management**: Delete rows that have been migrated to archive sheets.
- **Data maintenance**: Remove duplicate or erroneous entries from large datasets.
- **Workflow completion**: Delete rows representing tasks or items that are no longer needed.


### get_cell_history

**Access scopes:** `READ_SHEETS`

`get_cell_history` retrieves the complete modification history for a specific cell in a Smartsheet. This tool returns timestamped changes with old and new values and user attribution so you can track how a specific cell's value evolves over time.

**Best Practices**

- Use pagination for cells with extensive history and check the total count in the response.
- Monitor the rate limit of 30 requests per minute when querying multiple cells.
- Use `get_sheet_summary` first to identify the row ID and column ID for cells of interest.
- Consider using `get_sheet_version` to check if a sheet has changed before fetching history.


**Basic Parameters**

- `sheet_id`: The sheet containing the cell (required).
- `row_id`: The row containing the cell (required).
- `column_id`: The column containing the cell (required).
- `include_column_type`: Boolean to include column type information in results (optional, defaults to false).
- `page`: The page number for pagination (optional, defaults to 1).
- `page_size`: Number of history entries per page, maximum 100 (optional, defaults to 50).


**Key Features**

- **Timestamped tracking**: Each history entry includes the time of the change and which user made it.
- **Value comparison**: Old and new values are returned for each modification.
- **Pagination support**: History entries handle pagination for cells with extensive change records.
- **User attribution**: Changes are credited to the user who modified the cell.


**Limitations**

- Rate limited to 30 requests per minute per API token (resource-intensive operation).
- Requires exact cell location with sheet ID, row ID, and column ID.
- Does not support bulk history retrieval for multiple cells in a single request.
- History entries are paginated with a maximum of 100 entries per page.
- Cannot retrieve history for an entire sheet at once (cell-level only).


**Use Cases**

- **Audit trails**: Track all changes to critical cells for compliance or accountability purposes.
- **Debugging changes**: Identify when and by whom a cell value changed to troubleshoot issues.
- **Version comparison**: Review the evolution of a cell's value over time to understand data patterns.
- **User accountability**: Determine which users have modified specific cells.


## Attachments

### list_attachments

**Access scopes:** `READ_SHEETS`

`list_attachments` retrieves a paginated list of attachments associated with a sheet, a specific row, or a specific discussion. It returns files, links, and cloud storage integrations at whichever level the `target_type` parameter specifies.

**Best Practices**

- Use the `target_type` parameter to scope results to the appropriate level (sheet, row, or discussion) rather than retrieving all sheet attachments and filtering client-side.
- Use pagination parameters to efficiently handle large numbers of attachments.
- Check the `totalPages` value in the response to determine if additional pages exist before making subsequent requests.
- Start with the default page size of 100 to maximize efficiency and minimize the number of API calls needed.
- Combine with the `get_attachment` tool to retrieve download URLs after discovering attachment IDs.


**Basic Parameters**

- `sheet_id`: The ID of the sheet from which to list attachments. This parameter is required for all target types.
- `target_type`: The scope of the attachment listing. Accepted values are `SHEET`, `ROW`, and `DISCUSSION`. The `target_type` parameter defaults to `SHEET`.
- `target_id`: The ID of the specific row or discussion whose attachments are listed. Required when `target_type` is `ROW` or `DISCUSSION`; omit when `target_type` is `SHEET`.
- `page`: Page number for pagination, using 1-based indexing. The `page` parameter defaults to `1`.
- `page_size`: Number of attachments to retrieve per page, with a maximum of 100. The `page_size` parameter defaults to `100`.


**Key Features**

- **Multi-level targeting**: Retrieves attachments at the sheet, row, or discussion level using a single tool, eliminating the need for separate tools per scope.
- **Comprehensive attachment discovery**: Returns attachments of all types, including files, Google Drive links, OneDrive links, Box links, Dropbox links, and other cloud storage integrations.
- **Efficient pagination**: Supports paginated results to handle large numbers of attachments without overwhelming the response.
- **Permission-aware retrieval**: Returns only attachments the authenticated user has permission to view.


**Limitations**

- Returns only attachments the authenticated user has permission to view.
- When `target_type` is `ROW` or `DISCUSSION`, `target_id` is required; omitting it returns an error.
- Returns attachments from all comments in a discussion without filtering by individual comment.


**Use Cases**

- **Attachment inventory**: Audit all files and links attached to a sheet to understand what resources are associated with a project.
- **Row document discovery**: Find all files attached to a specific task or item row to access supporting documentation.
- **Discussion attachment review**: Review all files and links shared during a discussion to ensure nothing is missing.
- **File management**: Discover and reference all attachments before cleaning up or organizing sheet resources.
- **Integration workflows**: Retrieve attachment metadata to sync sheet references with external documentation systems or archives.
- **Link validation**: Check all external links and cloud storage references attached to a discussion for availability.


### get_attachment

**Access scopes:** `READ_SHEETS`

`get_attachment` retrieves attachment metadata by ID including name, type, URL, size, and timestamps. This tool provides download URLs and details for files attached to sheets, rows, or comments.

**Basic Parameters**

- `attachment_id` - The ID of the attachment to retrieve.
- `sheet_id` - The ID of the sheet containing the attachment.


**Key Features**

- **Metadata retrieval** - Returns comprehensive attachment information including name, type, size, creation date, and modification date.
- **Download URLs** - Provides temporary download links for accessing the attached file.


**Limitations**

- Returns metadata only, not file contents.
- Download URLs expire after a period specified in the response (urlExpiresInMillis).


**Use Cases**

- **File access** - Get download URLs for attached files without needing to browse the entire sheet.
- **Metadata tracking** - Retrieve attachment details to audit file changes, sizes, or timestamps.
- **Attachment verification** - Confirm that specific attachments exist and are accessible before attempting to use them.


### attach_url

The `attach_url` tool attaches a URL to a Smartsheet sheet, row, or comment, linking to external resources such as Google Drive files, Box documents, Dropbox links, OneDrive files, or any generic web URL.

**Access scopes:** `WRITE_SHEETS`

**Best Practices**

The following items are best practices for using the `attach_url` tool:

- Use the most specific `attachmentType` value that matches the source service rather than defaulting to `LINK`, as this allows Smartsheet to render the attachment with the appropriate service icon and metadata.
- When attaching Google Drive items, also supply the `attachmentSubType` parameter to indicate whether the item is a document, spreadsheet, presentation, PDF, drawing, or folder, so Smartsheet can display the correct file-type context.
- Use the `attach_url` tool in conjunction with the `get_sheet_summary` tool to verify the attachment was created as expected.


**Basic Parameters**

The `attach_url` tool has the following parameters:

- `sheet_id` — The integer ID of the sheet to which the attachment belongs. This is required for all target types.
- `target_type` — The type of object receiving the attachment. Valid values are `SHEET`, `ROW`, or `COMMENT`.
- `target_id` — The integer ID of the row or comment receiving the attachment. This parameter is required when `target_type` is `ROW` or `COMMENT`, and is omitted when `target_type` is `SHEET`.
- `attachment.url` — The URL string to attach, such as a Google Drive link, Dropbox link, or any generic web URL.
- `attachment.attachmentType` — The service category of the URL. Valid values are `LINK`, `GOOGLE_DRIVE`, `BOX_COM`, `DROPBOX`, `EVERNOTE`, `EGNYTE`, and `ONEDRIVE`. Note that Dropbox, Egnyte, and Evernote are not supported for Smartsheet.gov accounts.
- `attachment.attachmentSubType` — An optional sub-classification of the attachment, used only with `GOOGLE_DRIVE` or `EGNYTE` attachment types. Valid values are `DOCUMENT`, `SPREADSHEET`, `PRESENTATION`, `PDF`, `DRAWING`, and `FOLDER`. The `FOLDER` sub-type applies only to `EGNYTE`; all other sub-types apply to `GOOGLE_DRIVE`. The `attachment.attachmentSubType` parameter defaults to `null`.


**Key Features**

The `attach_url` tool has the following key features:

- **Multi-target support** — A URL can be attached to a sheet, a specific row, or a specific comment, providing flexible linking at different levels of granularity.
- **Cloud service integration** — Explicit attachment types for Google Drive, Box, Dropbox, OneDrive, Egnyte, and Evernote allow Smartsheet to render service-appropriate icons and metadata alongside the link.
- **Google Drive sub-type classification** — An optional `attachmentSubType` parameter enables further classification of Google Drive items by file type (document, spreadsheet, presentation, PDF, drawing) or folder type for Egnyte.
- **Generic URL support** — The `LINK` attachment type accommodates any web URL that does not belong to a supported cloud storage service.


**Limitations**

The `attach_url` tool has the following limitations:

- Attachments cannot be moved between targets after creation; if the wrong target is specified, the attachment must be deleted and re-created.
- Dropbox, Egnyte, and Evernote attachment types are not supported on Smartsheet.gov accounts.
- There is no built-in validation of the URL itself; the tool accepts any string passed as the URL without confirming the link is reachable or valid.


**Use Cases**

The following items describe use cases for the `attach_url` tool:

- **Linking supporting documents** — Attach a Google Drive document or OneDrive file to a sheet row so that team members can access reference materials directly from the relevant row in context.
- **Connecting cloud storage folders** — Attach an Egnyte or Google Drive folder link at the sheet level to give collaborators quick access to a shared file repository related to the entire project.
- **Adding external references to comments** — Attach a URL to a specific comment to provide a direct source or citation alongside a discussion point on a row.
- **Surfacing generic web resources** — Use the `LINK` attachment type to associate any public web page, dashboard, or web application URL with a sheet, row, or comment.


### delete_attachment

**Access scopes:** `WRITE_SHEETS`

`delete_attachment` removes an attachment from a Smartsheet sheet. (⚠️ destructive, irreversible)

**Best Practices**

- Verify the attachment ID is correct before deletion.
- Double-check the sheet ID to ensure you are deleting from the correct sheet.
- Consider confirming the attachment exists using `get_attachment` before deletion.


**Basic Parameters**

- `attachment_id`: The ID of the attachment to delete.
- `sheet_id`: The ID of the sheet containing the attachment.


**Key Features**

- **Permanent removal**: Deletes an attachment completely and cannot be recovered.


**Limitations**

- Cannot delete attachments for which you lack modification permissions.
- Deleted attachments cannot be recovered through the API.


**Use Cases**

- **Clean up**: Remove obsolete or redundant attachments from a sheet.
- **Privacy management**: Delete sensitive files that should no longer be stored in Smartsheet.
- **Storage optimization**: Remove large files to reduce sheet storage usage.


## Discussions and comments

### list_discussions

**Access scopes:** `READ_SHEETS`

**Toolset:** `discussions`

`list_discussions` retrieves discussions associated with a Smartsheet sheet, returning either all discussions across the entire sheet or only those attached to a specific row, depending on whether a `row_id` is provided.

**Best Practices**

- Provide a `row_id` when you need discussions for a specific row to improve performance and avoid retrieving unrelated discussions.
- Set `include_comments` to `true` when you need the full discussion thread content, not just discussion metadata.
- Combine `include_comments` with `include_attachments` to retrieve files or links added to discussions in a single request.
- Use pagination parameters (`page` and `page_size`) when a sheet or row has many discussions to manage large result sets efficiently.
- Reference returned discussion ID values when you add comments with the `add_comment` tool or delete discussions with the `delete_discussion` tool.


**Basic Parameters**

- `sheet_id`: The ID of the sheet from which to retrieve discussions. This parameter is required.
- `row_id`: The ID of a specific row. When provided, only discussions attached to that row are returned. When omitted, all discussions across the sheet are returned. This parameter is optional.
- `include_comments`: A boolean flag that includes all comments within each discussion when set to `true`. The `include_comments` parameter defaults to `false`.
- `include_attachments`: A boolean flag that includes attachments associated with discussions when set to `true`. The `include_attachments` parameter defaults to `false`.
- `page`: The page number for pagination results. The `page` parameter defaults to `1`.
- `page_size`: The number of discussions to return per page, with a maximum of 100. The `page_size` parameter defaults to `100`.


**Key Features**

- **Flexible scope**: Returns all sheet discussions or only row-specific discussions depending on whether `row_id` is provided, replacing two separate tools with one.
- **Selective content loading**: Optionally includes comments and attachments to control response size and data retrieval.
- **Pagination support**: Handles large discussion sets across multiple pages so you can process discussions in manageable batches.
- **Collaboration tracking**: Enables audit trails and review of all collaborative conversations on a sheet or a specific row.


**Limitations**

- Paginated results return a maximum of 100 discussions per page.
- Comments and attachments are only included in the response when explicitly requested via their respective parameters.
- When no `row_id` is provided, both sheet-level and row-level discussions are returned without scope filtering, requiring client-side logic to separate them if needed.


**Use Cases**

- **Collaboration auditing**: Retrieve all discussions to review the history of collaboration, feedback, and decision-making on a sheet.
- **Row feedback review**: Provide a `row_id` to review all discussion threads on a specific work item, task, or record.
- **Comment analysis**: Gather all comments across the sheet to identify action items, approvals, or outstanding questions.
- **Approval workflow monitoring**: Check discussions on rows to track approvals, sign-offs, or status updates in collaborative workflows.
- **Data export**: Extract complete discussion records including comments and attachments for external documentation or archival purposes.
- **Discussion cleanup**: Identify outdated or resolved discussions to keep the sheet organized and focused.


### get_discussion

**Access scopes:** `READ_SHEETS`

**Toolset:** `discussions`

`get_discussion` retrieves a single discussion by ID with full details including comments and attachments. This tool is useful when you have a specific discussion ID and need to access complete information about that discussion thread.

**Basic Parameters**

- `discussion_id` — The ID of the discussion to retrieve.
- `sheet_id` — The ID of the sheet containing the discussion.


**Key Features**

- **Complete details** — Returns all information about the discussion including its metadata and content.
- **Automatic inclusion** — Comments and attachments are automatically included in the response without requiring additional parameters.


**Use Cases**

- **View discussion thread** — Retrieve a complete discussion thread when you have its ID to see all comments and context.
- **Check discussion details** — Access full information about a specific discussion before taking action like adding a comment or deleting it.
- **Extract discussion content** — Get all discussion data including comments and attachments for analysis or export purposes.


### create_discussion

**Access scopes:** `WRITE_SHEETS`

**Toolset:** `discussions`

`create_discussion` starts a new discussion thread on a Smartsheet sheet or on a specific row within a sheet. The discussion title generates automatically from the first 100 characters of the initial comment text.

**Best Practices**

- Include clear, descriptive comment text when starting a discussion so the auto-generated title effectively captures the discussion topic.
- Use `target_type` set to `ROW` for row-specific conversations and `SHEET` for broader topics that affect the entire sheet.
- Reference the discussion ID from the response when adding follow-up comments using the `add_comment` tool.
- Verify the sheet ID and, when applicable, the row ID before creating a discussion to ensure the discussion attaches to the correct location.


**Basic Parameters**

- `sheet_id`: The ID of the sheet where the discussion starts. This parameter is required.
- `target_type`: The level at which to create the discussion. Accepted values are `SHEET` and `ROW`. This parameter is required.
- `row_id`: The ID of the specific row to associate with the discussion. Required when `target_type` is `ROW`; omit when `target_type` is `SHEET`.
- `discussion`: An object containing a comment with the initial message text. Minimum 1 character required. This parameter is required.


**Key Features**

- **Unified discussion creation**: Creates discussions at either the sheet level or the row level through a single tool, replacing two separate tools.
- **Auto-generated titles**: The discussion title creates automatically from the first 100 characters of the comment text, streamlining discussion setup.
- **Flexible targeting**: Supports sheet-wide conversations for broad topics and row-focused conversations for item-specific feedback.


**Limitations**

- Exactly one initial comment is required to create a discussion; discussions cannot be created without an opening comment.
- When `target_type` is `ROW`, `row_id` is required; omitting it returns an error.


**Use Cases**

- **Broad sheet feedback**: Set `target_type` to `SHEET` to create a discussion for general feedback or questions about the entire sheet.
- **Task clarification**: Set `target_type` to `ROW` to start a discussion on a specific task row to ask clarifying questions or provide additional context about requirements.
- **Issue tracking**: Create discussions on rows representing bugs or issues to track status updates, resolution steps, and team feedback in one place.
- **Project updates**: Initiate row-level discussions to discuss progress, blockers, or changes related to a specific project item or milestone.
- **Approval workflows**: Use discussions on rows to gather feedback, approvals, or sign-offs from team members before moving a task to the next stage.
- **Team coordination**: Start sheet-level conversations about sheet-wide processes, workflows, or initiatives.
- **Documentation**: Establish discussion threads for recording decisions, notes, or context about the sheet.


### delete_discussion

**Access scopes:** `WRITE_SHEETS`

**Toolset:** `discussions`

The `delete_discussion` tool permanently removes an entire discussion thread and all of its comments from a Smartsheet. (⚠️ destructive, irreversible)

**Best Practices**

- Use `get_discussion` to review the discussion and its comments before deletion.
- Double-check that you have the correct sheet ID and discussion ID.
- Ensure the discussion is truly no longer needed before proceeding with deletion.


**Basic Parameters**

- `sheet_id`: The ID of the sheet containing the discussion being deleted.
- `discussion_id`: The ID of the discussion to be deleted.


**Use Cases**

- **Resolve off-topic discussions**: Remove discussions that are not relevant to the project or sheet.
- **Clean up resolved items**: Delete discussions that were created for resolved issues that no longer require ongoing documentation.
- **Remove duplicate discussions**: Eliminate duplicate discussion threads that were accidentally created.
- **Maintain sheet hygiene**: Delete outdated or archived discussions to keep the sheet organized.


### add_comment

**Access scopes:** `WRITE_SHEETS`

**Toolset:** `discussions`

`add_comment` enables you to add a new reply or additional message to an existing discussion thread within a Smartsheet.

**Best Practices**

- Retrieve the discussion ID first using the `list_discussions` tool before adding a comment.
- Verify that the discussion exists and accepts new comments.
- Keep comment text clear and concise for better readability within discussion threads.


**Basic Parameters**

- `sheet_id`: The ID of the sheet that contains the discussion.
- `discussion_id`: The ID of the existing discussion to which you add the comment.
- `comment`: An object containing the comment text (minimum 1 character required).


**Limitations**

- You require the discussion ID before adding a comment; standalone comments cannot be created.
- You cannot add comments to discussions that are closed or locked.


**Use Cases**

- **Team collaboration**: Add replies to ongoing discussions about sheet items or deliverables.
- **Status updates**: Provide updates or clarifications on existing discussion threads.
- **Feedback loops**: Continue conversations by responding to colleague comments within the sheet.


### update_comment

**Access scopes:** `WRITE_SHEETS`

**Toolset:** `discussions`

`update_comment` modifies the text content of an existing comment on a sheet. This tool allows you to correct, revise, or amend a comment you previously created without needing to delete and recreate it. (⚠️ destructive)

**Best Practices**

- Confirm the correct comment ID and sheet ID before updating to prevent modifying the wrong comment.
- Verify that the discussion or comment location still exists before attempting an update.
- Keep the new comment text clear and concise to maintain discussion readability.


**Basic Parameters**

- `sheet_id`: The ID of the Smartsheet containing the comment.
- `comment_id`: The ID of the specific comment to update.
- `comment`: An object containing the `text` field with the new comment content (minimum 1 character).


**Key Features**

- **Text modification**: Replace or update the entire comment text with new content.
- **Ownership requirement**: Only the user who created the comment updates it.
- **Lightweight operation**: Updates only the comment text without affecting other sheet elements.


**Limitations**

- Only you can update comments you created.
- Comments in closed or locked discussions cannot be updated.
- The update operation replaces the entire comment text, not portions of it.


**Use Cases**

- **Correct mistakes**: Fix typos or grammatical errors in a previously posted comment.
- **Clarify information**: Update a comment with additional details or clarification without creating a new one.
- **Revise feedback**: Modify feedback or suggestions in a comment thread based on new information.
- **Maintain discussion context**: Keep a comment current while preserving its place in the discussion thread.


### delete_comment

**Access scopes:** `WRITE_SHEETS`

**Toolset:** `discussions`

`delete_comment` removes a single comment from a sheet permanently. (⚠️ destructive, irreversible)

**Best Practices**

- Use `get_discussion` or list discussions to confirm comment details first.
- Double-check you have the correct `sheet_id` and `comment_id` before executing the deletion.


**Basic Parameters**

- `sheet_id` - The ID of the sheet containing the comment.
- `comment_id` - The ID of the comment to delete.


**Limitations**

- Only the user that created the comment has permission to delete it.


**Use Cases**

- **Remove spam or inappropriate content** - Delete comments that violate community standards or are off-topic.
- **Clean up test comments** - Remove temporary comments added during sheet development or testing.
- **Maintain data accuracy** - Delete outdated or incorrect comments that no longer apply to the sheet.


## Reports

### list_reports

**Access scopes:** `READ_SHEETS`

`list_reports` retrieves a list of all reports that the user has access to. This tool shows basic report metadata such as ID, name, access level, and permalink URL, making it useful for discovering available reports before retrieving their detailed contents.

**Best Practices**

- Use pagination with the `page_size` and `page` parameters to efficiently retrieve reports when you have many reports in your Smartsheet account.
- Check the `total_pages` field in the response to determine if additional pages are available and continue iterating through pages as needed.
- Use this tool before calling `get_report` to discover which reports are available in your workspace.


**Basic Parameters**

- `page`. The page number to retrieve, starting at 1 (default is 1).
- `page_size`. The number of reports to display per page, ranging from 1 to 100 (default is 100).


**Key Features**

- **Pagination Support**: Distributes large numbers of reports across pages with a maximum of 100 reports per page.
- **Basic Metadata**: Provides essential report information including ID, name, access level, and permalink.


**Limitations**

- Returns only reports the user has access to, excluding those restricted by workspace or sheet permissions.
- Does not include detailed report content such as rows, columns, or cell data (use `get_report` instead).


**Use Cases**

- **Discovery**: Find all available reports in a Smartsheet account to identify which reports exist and their basic properties.
- **Inventory**: Build a comprehensive catalog of reports for auditing or documentation purposes.
- **Navigation**: Determine which report ID to use before calling `get_report` to retrieve detailed report data.


### get_report

**Access scopes:** `READ_SHEETS`

The `get_report` tool retrieves detailed report data by report ID, including columns, rows, and cell values. Reports provide read-only aggregated views of source sheets and can contain thousands of rows, which the tool handles through pagination for efficient data retrieval.

**Best Practices**

- Discover available reports using `list_reports` before calling this tool.
- Use the `page_size` and `page` parameters to paginate through large reports efficiently.
- Include optional elements strategically to avoid unnecessary data transfer.
- Verify the report ID is correct before making the request.


**Basic Parameters**

- `report_id`: The ID of the report to retrieve (required).
- `page`: The page number for pagination, starting at 1 (default: 1).
- `page_size`: The number of rows to return per page, between 1 and 10,000 (default: 100).
- `include`: Optional list of elements to include in the response, such as attachments, discussions, format, objectValue, proofs, scope, source, or sourceSheets.


**Key Features**

- **Pagination support**: Handles large reports with thousands of rows by retrieving data in chunks.
- **Flexible data inclusion**: The `include` parameter lets you request additional metadata like attachments, discussions, and source sheet information.
- **Read-only aggregation**: Reports present aggregated views of source sheet data without modification capabilities.
- **Comprehensive cell data**: Returns detailed information about report columns, rows, and individual cell values.


**Limitations**

- Reports are read-only and cannot be modified through this tool.
- Large reports may require multiple API calls due to pagination limits.
- The maximum page size is 10,000 rows per request.


**Use Cases**

- **Data analysis**: Extract report data for analysis, dashboards, or business intelligence purposes.
- **Reporting workflows**: Retrieve aggregated metrics or KPIs from Smartsheet reports for integration into external systems.
- **Audit and compliance**: Pull report snapshots for record-keeping or compliance documentation.
- **Dashboard integration**: Feed report data into custom dashboards or visualizations.


### create_report

The `create_report` tool creates a new Smartsheet report that aggregates data from one or more source sheets or from all of the sheets in one or more workspaces. The `create_report` tool supports custom column definitions, filters, grouping, sorting, and summarizing criteria, and can produce either a row report or a sheet summary report.

**Access scopes:** `READ_SHEETS`

**Best Practices**

The following items are best practices for using the `create_report` tool:

- Verify that all column `title` values exactly match the corresponding column titles in the source sheets, as matching is case-sensitive and must be precise.
- Ensure all column `index` values are unique and zero-based across the full column definition list.
- For row reports, designate exactly one column with `primary=true` using `type=TEXT_NUMBER`.
- For sheet summary reports, designate exactly one column with `sheetNameColumn=true` using `type=TEXT_NUMBER`.
- When grouping criteria are defined, be aware that the primary column moves to index 0 on first render in the app, which may affect expected column ordering.
- Use the the `get_report` tool after creation to confirm the report structure and data before sharing or embedding the report in dashboards.


**Basic Parameters**

The `create_report` tool has the following parameters:

- `name` — The report name, between 1 and 50 characters.
- `destination` — The destination folder or workspace where the report is created, specified as an object with a `destinationId` (the numeric folder or workspace ID) and a `destinationType` (either `"folder"` or `"workspace"`).
- `scope` — A list of 1 to 100 source sheets or workspaces to aggregate, each specified with an `assetId` and an `assetType` of either `"sheet"` or `"workspace"`.
- `columns` — A list of 1 to 400 column definitions, each with a zero-based `index`, a `type`, and additional identifying fields depending on the column kind (regular, system, primary, or sheet name column). Optional per-column fields include `hidden`, `width`, `primary`, `sheetNameColumn`, `systemColumnType`, and `title`.
- `is_summary_report` — A boolean that controls whether the report is a sheet summary report (`true`) or a row report (`false`). The `is_summary_report` parameter defaults to `false`.
- `report_definition` — An optional object containing `filters`, `groupingCriteria`, `sortingCriteria`, and `summarizingCriteria` to shape the report's data presentation.


Refer to the `POST /2.0/reports` API operation [documentation](/api/smartsheet/openapi/reports/createreport) for details on creating a report and specifying the report definition.

**Key Features**

The `create_report` tool has the following key features:

- **Row and summary report types** — Supports both row reports, which aggregate individual rows from source sheets, and sheet summary reports, which aggregate sheet summary fields.
- **Multi-source scoping** — Accepts up to 100 source sheets (specified explicitly or as part of workspaces) as input, enabling cross-sheet and cross-workspace data aggregation in a single report.
- **Flexible column definitions** — Supports regular columns (matched by type and title), system columns (matched by type and system column type), primary columns, and sheet name columns, with optional hidden and width settings.
- **Filter expressions** — Supports nested filter expressions up to 3 levels deep using `AND`/`OR` operators and a wide range of filter operators covering equality, comparisons, date ranges, blank checks, and multi-value matching.
- **Grouping criteria** — Allows columns to be used as grouping criteria with configurable sort direction and expand/collapse state.
- **Sorting criteria** — Supports multi-column sorting with `ASCENDING` or `DESCENDING` direction per column.
- **Summarizing criteria** — Supports column-level aggregations using `SUM`, `AVG`, `MIN`, `MAX`, `COUNT`, `FIRST`, and `LAST`.


**Limitations**

The `create_report` tool has the following limitations:

- Report names are limited to 50 characters.
- A maximum of 400 columns may be defined per report.
- The scope is limited to 100 sheets.
- Filter expressions support a maximum nesting depth of 3 levels.


**Use Cases**

The following items describe use cases for the `create_report` tool:

- **Cross-sheet status rollup** — Aggregate task status columns from multiple project sheets into a single report to give stakeholders a unified view of progress across all projects.
- **Department-wide resource tracking** — Scope a report to an entire workspace to consolidate resource allocation rows from every sheet in a department's workspace.
- **Filtered executive summary** — Create a row report with filter criteria that surfaces only high-priority or overdue items from across dozens of source sheets.
- **Grouped pipeline view** — Define grouping criteria on a status or owner column to organize aggregated rows into collapsible sections for easier review.
- **Summarized financial rollup** — Use summarizing criteria with `SUM` or `AVG` aggregations on numeric columns to produce totals and averages across source sheets.
- **Sheet summary dashboard feed** — Create a sheet summary report (`is_summary_report=true`) to pull sheet-level summary fields together, useful for high-level KPI dashboards.
- **Sorted delivery schedule** — Apply sorting criteria on a date column so that aggregated rows from multiple sheets appear in chronological order across the full report.


## Automated workflows

### get_workflows

**Access scopes:** `READ_SHEETS`

**Toolset:** `automations`

`get_workflows` lists all workflows attached to a sheet, returning each workflow's full trigger and action tree with pagination support. Results are ordered ascending by workflow ID.

**Basic Parameters**

The `get_workflows` tool has the following parameters:

- `sheet_id` (required): The ID of the sheet whose workflows to list.
- `last_key` (optional): Opaque pagination cursor from a previous `get_workflows` response. Pass it back to fetch the next page.
- `max_items` (optional): Maximum number of workflows to return per page (1–1000). The `max_items` parameter defaults to 100. Workflow trees can be large — use a small value when only a few are needed.


**Key Features**

The `get_workflows` tool has the following key features:

- **Full tree output**: Each workflow's `root_node` is returned in the same by-names format accepted by the `create_workflow` tool, making it easy to inspect, replicate, or modify existing workflows.
- **Pagination support**: Use `last_key` to iterate through sheets with many workflows.


**Limitations**

The `get_workflows` tool has the following limitations:

- Reminder-type workflows are not returned.
- The caller must have permission to access the target sheet.


**Use Cases**

The following items describe use cases for the `get_workflows` tool:

- **Workflow audit**: Retrieve and review all workflows on a sheet to understand what automation is in place.
- **Workflow replication**: Read an existing workflow's tree and use it as the basis for a new workflow with the `create_workflow` tool.
- **Status check**: Identify which workflows are enabled or disabled before calling the `enable_workflow` or `disable_workflow` tool.


### create_workflow

**Access scopes:** `WRITE_SHEETS`

**Toolset:** `automations`

`create_workflow` creates a new workflow on a sheet using human-readable names for columns, recipients, and other references. The workflow is defined as a typed tree specifying a trigger and a chain of actions or conditions.

**Best Practices**

The following items are best practices for using the `create_workflow` tool:

- Use the `get_workflows` tool on an existing sheet to study the tree structure before composing a new workflow from scratch.
- Verify that all referenced column titles, recipient emails, and document mapping names exist on the sheet before calling — unknown names are rejected by the API without creating anything.
- Use `{}` for `notificationCustomizationJson` on `EMAIL_RECIPIENT`, `UPDATE_REQUEST`, and `APPROVAL` actions unless explicit customization is needed.


**Basic Parameters**

The `create_workflow` tool has the following parameters:

- `sheet_id` (required): The ID of the sheet the workflow attaches to.
- `name` (required): Display name for the workflow (up to 255 characters).
- `root_node` (required): The workflow definition as a typed tree. The root has `type: "ROOT_NODE"` and contains a `trigger` and a `childNode`. All `type` discriminants are `UPPER_SNAKE_CASE`. Columns are referenced by title (`columnTitle`); people are referenced by email address. The ID field in recipient objects is always a string.
- `frequency` (optional): How often the workflow runs once triggered. The `frequency` parameter defaults to `RIGHT_AWAY` (run immediately when the trigger fires).
- `enabled` (optional): Whether the workflow is active immediately after creation. The `enabled` parameter defaults to `true`.


**Key Features**

The `create_workflow` tool has the following key features:

- **Human-readable references**: Columns, recipients, and document mappings are specified by name rather than numeric ID, making workflows easier to compose and read.
- **Schema-validated tree**: The `root_node` structure is validated before the API call; errors report the exact field path and permitted values for precise correction.
- **Immediate activation**: Workflows are enabled by default upon creation; set `enabled: false` to create a workflow in a disabled state.


**Limitations**

The `create_workflow` tool has the following limitations:

- All referenced column titles and email addresses must already exist on the sheet — the tool does not create missing resources.
- Recipient emails must belong to Smartsheet users; assign-people emails must have an existing contact record.
- Column title matching is case-sensitive.


**Use Cases**

The following items describe use cases for the `create_workflow` tool:

- **Automated notifications**: Create a workflow that sends an email alert when a row's status column changes to a specific value.
- **Approval routing**: Build an approval workflow triggered when a new row is added, sending an update request to a designated reviewer.
- **Scheduled reminders**: Set up a time-based workflow that sends reminders at a defined frequency when a due-date condition is met.
- **Row automation**: Automatically move or copy rows to another sheet when specific criteria are satisfied.


### update_workflow

**Access scopes:** `WRITE_SHEETS`

**Toolset:** `automations`

The `update_workflow` tool updates a Smartsheet workflow by ID, fully replacing its definition using human-readable names. It overwrites the stored workflow tree with exactly the tree sent — anything omitted from `root_node` is removed from the workflow. Updating a workflow also invalidates any in-flight approval actions: pending approval emails stop being actionable.

(⚠️ destructive, irreversible)

**Best Practices**

The following items are best practices for using the `update_workflow` tool:

- Call the `get_workflows` tool first to read the current definition, then modify it and send the COMPLETE tree back — never send a partial tree.
- Omit `enabled` to preserve the workflow's current enabled/disabled state; only pass it to deliberately toggle that state.
- Pass `expected_version` (from a previous `update_workflow`, `enable_workflow`, or `disable_workflow` response) to guard against concurrent edits; on a 409 conflict, re-read the workflow and retry with the fresh definition.
- Reference columns by title and people by email; use UPPER_SNAKE_CASE for all `type` discriminants, exactly as in the `create_workflow` tool.
- Do not include node `id` fields in `root_node` — the tree schema rejects them; node identity is regenerated on every edit.


**Basic Parameters**

The `update_workflow` tool has the following parameters:

- `workflow_id` (required, string) — The ID of the workflow to update, as shown in Smartsheet.
- `sheet_id` (required, integer) — The current sheet ID of the workflow. Must match the sheet the workflow already lives on — workflows cannot be moved to another sheet.
- `name` (required, string) — The workflow display name to store. Up to 255 characters; may be empty.
- `root_node` (required) — The complete replacement workflow tree using the by-names contract: `{type: 'ROOT_NODE', trigger: {type: <TRIGGER_TYPE>, ...}, childNode: {type: <NODE_TYPE>, ...}}`. Uses the same schema as the `create_workflow` tool. The stored definition becomes exactly this tree.
- `frequency` (required) — How often the workflow runs once triggered. Must always be supplied on update; there is no default.
- `enabled` (boolean, optional) — Whether the workflow is enabled. Omit to keep the current enabled/disabled state; pass `true` or `false` only to deliberately change it.
- `expected_version` (integer, optional) — Optimistic-concurrency guard. The `version` from a previous `update_workflow`, `enable_workflow`, or `disable_workflow` response. If the workflow was edited by someone else since that version, the update fails with 409 and makes no changes. Omit for an unconditional update.


**Key Features**

The `update_workflow` tool has the following key features:

- **Full replacement semantics** — The stored workflow definition becomes exactly the `root_node` tree sent; any node omitted is removed, making this a complete overwrite rather than a patch.
- **Human-readable names** — Columns are referenced by title and recipients by email address, avoiding the need to look up internal IDs.
- **Optimistic concurrency control** — The optional `expected_version` parameter detects concurrent edits and fails safely with 409, enabling read-modify-write patterns without data loss.
- **Enabled/disabled state preservation** — Omitting `enabled` keeps the workflow's current state; an edit alone never inadvertently re-enables a disabled workflow.
- **Pre-flight tree validation** — Tree-structure violations (invalid condition counts, missing child nodes, etc.) are caught and the offending path is reported before anything is sent to the backend.


**Limitations**

The `update_workflow` tool has the following limitations:

- Full replace, not a patch: the workflow becomes exactly what is sent; any node omitted from `root_node` is removed.
- `sheet_id` must be the workflow's current sheet — workflows cannot be moved to another sheet via update.
- Updating a workflow invalidates its in-flight approval actions: pending approval emails stop being actionable.
- The caller must have permission to edit the workflow's sheet.
- Condition nodes must carry 1–20 conditions AND a `childNode`; IF_ELSE nodes require at least one condition branch; ELSE nodes require a `childNode` — violations are rejected with the offending path.
- Node `id` fields must not be included in `root_node` — the schema rejects them.


**Use Cases**

The following items describe use cases for the `update_workflow` tool:

- **Modifying trigger or action configuration** — Read the current workflow, adjust a trigger type or notification recipient, and write the full updated tree back.
- **Restructuring a workflow tree** — Add, remove, or reorder condition branches and action nodes by sending a revised complete tree.
- **Renaming a workflow** — Update the `name` field while passing the rest of the definition unchanged.


### enable_workflow

**Access scopes:** `WRITE_SHEETS`

**Toolset:** `automations`

`enable_workflow` re-activates a disabled Smartsheet workflow by its ID. Enabling a workflow that is already enabled is idempotent and produces no change.

**Basic Parameters**

The `enable_workflow` tool has the following parameters:

- `workflow_id` (required): The ID of the workflow to enable.


**Limitations**

The `enable_workflow` tool has the following limitations:

- The caller must have permission to the workflow's sheet.


**Use Cases**

The following items describe use cases for the `enable_workflow` tool:

- **Reactivation**: Re-enable a workflow that was previously disabled after temporary maintenance or testing is complete.
- **Workflow lifecycle**: Use alongside the `disable_workflow` tool to toggle automation on and off without deleting it.


### disable_workflow

**Access scopes:** `WRITE_SHEETS`

**Toolset:** `automations`

`disable_workflow` turns off a Smartsheet workflow without deleting it. The workflow can be re-enabled later with the `enable_workflow` tool. Disabling a workflow sends a notification to the sheet's admins.

**Best Practices**

The following items are best practices for using the `disable_workflow` tool:

- Prefer the `disable_workflow` tool over the `delete_workflow` tool whenever the workflow may need to be re-enabled later.


**Basic Parameters**

The `disable_workflow` tool has the following parameters:

- `workflow_id` (required): The ID of the workflow to disable.
- `disable_reason` (optional): The reason recorded for disabling, included in the admin notification. Leave unset in almost all cases — a default is applied automatically.


**Key Features**

The `disable_workflow` tool has the following key features:

- **Reversible**: A disabled workflow can be re-enabled at any time using the `enable_workflow` tool, unlike the `delete_workflow` tool which is permanent.
- **Idempotent**: Disabling an already-disabled workflow is safe.
- **Admin notification**: Smartsheet notifies the sheet's admins when a workflow is disabled.


**Limitations**

The `disable_workflow` tool has the following limitations:

- The caller must have permission to the workflow's sheet.


**Use Cases**

The following items describe use cases for the `disable_workflow` tool:

- **Temporary suspension**: Pause a notification workflow during a data migration or bulk update to prevent alert storms.
- **Testing**: Disable a production workflow while testing changes, then re-enable it when ready.
- **Maintenance windows**: Turn off automated row-copy or approval workflows during scheduled maintenance.


### delete_workflow

**Access scopes:** `WRITE_SHEETS`

**Toolset:** `automations`

The `delete_workflow` tool permanently deletes a Smartsheet workflow by its ID. Once deleted, the workflow cannot be recovered or re-enabled.

⚠️ destructive, irreversible

**Basic Parameters**

The `delete_workflow` tool has the following parameters:

- `workflow_id` (required): The ID of the workflow to delete.


**Limitations**

The `delete_workflow` tool has the following limitations:

- Deletion is permanent and cannot be undone.
- The caller must have permission to the workflow's sheet.
- To temporarily turn off a workflow rather than delete it, use the `disable_workflow` tool instead.


**Use Cases**

The following items describe use cases for the `delete_workflow` tool:

- **Cleanup**: Remove outdated or replaced workflows from a sheet to keep the automation list tidy.
- **Decommission**: Permanently remove a workflow when the underlying process it supported has been retired.


## Dashboards

### list_dashboards

**Access scopes:** `READ_SIGHTS`

`list_dashboards` retrieves a list of all dashboards (also called Sights) that the user has access to with pagination support. This tool helps discover available dashboards and navigate large sets of dashboard resources. It returns basic dashboard information including name, access level, creation and modification times.

**Best Practices**

- Use empty `last_key` parameter (default: "") for the first page of results.
- For subsequent pages, use the `last_key` value from the previous response to fetch the next page.
- Adjust `max_items` to control page size (default: 100).
- Detect the last page when `last_key` is `None` in the response.


**Basic Parameters**

- `last_key` (string, optional): Token-based pagination parameter. Set to empty string for the first page, then use the value from previous responses to fetch subsequent pages.
- `max_items` (integer, optional): Controls the number of results per page. Default is 100.


**Key Features**

- **Basic metadata return**: Returns dashboard ID, name, access level, creation time, and modification time for each dashboard.
- **Pagination support**: Uses token-based pagination to handle large collections of dashboards.
- **Access control visibility**: Shows the access level for each dashboard, indicating user permissions.


**Limitations**

- Returns basic metadata only, not full dashboard content or widget details.
- Does not include widget configuration, layout details, or advanced dashboard properties.


**Use Cases**

- **Dashboard discovery**: Identify all available dashboards the user can access without knowing specific IDs.
- **Large collection navigation**: Browse through extensive dashboard collections using pagination.
- **Access level inventory**: Determine which dashboards the user has VIEWER, EDITOR, or OWNER access to.
- **Dashboard listing for reports**: Generate reports or lists of all dashboards within an account.


### get_dashboard

**Access scopes:** `READ_SIGHTS`

`get_dashboard` retrieves detailed information about a specific dashboard by ID. Use this after `list_dashboards` to obtain complete dashboard details including widgets, layout configuration, and source information. Data supports modern features like multi-contact, multi-picklist, and metric widgets with sheet summaries.

**Best Practices**

- Call `list_dashboards` first to discover available dashboards and their IDs.
- Use the include parameter to add optional data like email addresses or template source information when needed.
- Cache dashboard IDs to reduce API calls if the same dashboard is accessed repeatedly.


**Basic Parameters**

- `dashboard_id`: The ID of the dashboard to retrieve (required, must be a positive integer).
- `include`: Optional parameter that controls which additional data elements are included in the response, supporting values like objectValue for email addresses and source for template source information.


**Key Features**

- **Complete metadata retrieval**: Provides full dashboard details including name, access level, creation and modification times.
- **Widget information**: Returns comprehensive widget configuration and layout details.
- **Template source tracking**: Can include source object information if the dashboard was created from another dashboard.
- **Multi-contact support**: Supports retrieval of email addresses for multi-contact data when included.
- **Modern widget types**: Handles multi-picklist and metric widgets with sheet summaries.


**Use Cases**

- **Dashboard exploration**: Retrieve complete dashboard details after discovering a dashboard ID through `list_dashboards`.
- **Widget analysis**: Access full widget configuration and layout information to understand dashboard structure.
- **Template sourcing**: Include source information to trace dashboards created from templates back to their origin.
- **Multi-contact workflows**: Retrieve email addresses associated with multi-contact widgets for notification or communication workflows.
- **Dashboard cloning**: Get all dashboard details needed to replicate or backup a dashboard structure.


### create_dashboard_with_ai

**Access scopes:** `CREATE_SIGHTS`

`create_dashboard_with_ai` creates a new Smartsheet dashboard whose widgets are generated by AI from one or more source sheets. The `create_dashboard_with_ai` tool accepts a natural-language prompt and up to five sheet asset sources, then returns a permalink for immediate access to the new dashboard.

This tool is unavailable for the Microsoft 365 Copilot Connector (the Copilot Studio connector for Copilot Chat)

**Best Practices**

The following items are best practices for using the `create_dashboard_with_ai` tool:

- Confirm the sheets to use as asset sources, the destination workspace, and a dashboard title before calling this tool.
- Specify a destination workspace explicitly. The tool does not infer a default destination.
- After a successful response, share or note the returned permalink for immediate access to the new dashboard.
- To resolve a sheet or workspace name to an ID, use the `search` tool, the `list_workspaces` tool, or the `browse_workspace` tool.
- Avoid calling the `get_sheet_summary` tool, the `get_columns` tool, or other read tools to inspect sheet contents before calling this tool - the tool reads sheet data directly from the supplied `asset_id`, making pre-fetching unnecessary.


**Basic Parameters**

The `create_dashboard_with_ai` tool has the following parameters:

- `asset_sources`: One to five sheet asset sources that ground the AI suggestions. Each entry requires `asset_type` set to `sheet` and `asset_id` set to the target sheet's ID.
- `destination`: The location for the new dashboard. The `destination_type` field must be `workspace` and the `destination_id` field must be the target workspace's ID.
- `name`: The initial dashboard title. The maximum length is 200 characters.
- `user_prompt`: A natural-language description of the dashboard. The maximum length is 1,000 characters.


**Key Features**

The `create_dashboard_with_ai` tool has the following key features:

- **AI-generated widgets**: Widgets are generated by AI from one or more source sheets, reducing manual dashboard configuration.
- **Immediate access via permalink**: Returns a permalink after successful creation, providing immediate access to the new dashboard.
- **Automatic rollback on failure**: If any step in the creation process fails, the blank dashboard rolls back automatically, preventing orphaned empty dashboards.
- **Multi-sheet grounding**: Supports up to five sheet asset sources, enabling dashboards that draw from multiple data sets.
- **Natural-language configuration**: Accepts a `user_prompt` written in natural language to describe the desired dashboard, making the tool accessible without requiring technical configuration.


**Limitations**

The `create_dashboard_with_ai` tool has the following limitations:

- Asset sources must be sheets only. Reports and other asset types are not supported.
- The destination must be a workspace the user has write access to. Folder and Home destinations are not supported.
- A maximum of five sheet asset sources is allowed per dashboard.
- The `name` parameter has a maximum length of 200 characters.
- The `user_prompt` parameter has a maximum length of 1,000 characters.


**Use Cases**

The following items describe use cases for the `create_dashboard_with_ai` tool:

- **Project status overview**: Build a project status dashboard from one or more project sheets to give stakeholders an at-a-glance view of progress and blockers.
- **Sales performance reporting**: Generate a sales dashboard from pipeline or CRM sheets to surface key metrics like revenue, quota attainment, and deal stage.
- **Cross-sheet data summary**: Combine data from up to five related sheets into a single dashboard to give leadership a unified view across teams or programs.
- **Rapid dashboard prototyping**: Use a natural-language prompt to quickly generate a dashboard layout before refining it manually in Smartsheet.


## Charts

This section describes Smartsheet MCP server tools for building charts, querying them, and adding them to dashboards.

### get_chart_suggestions

**Access scopes:** `READ_SHEETS`

The `get_chart_suggestions` tool retrieves AI-powered chart suggestions for a given Smartsheet sheet, returning categorized suggestions with chart type options and ready-to-use prompts that can be passed directly into the `create_chart_from_prompt` tool.

**Best Practices**

The following items are best practices for using the `get_chart_suggestions` tool:

- Call `get_chart_suggestions` before calling `create_chart_from_prompt` to surface relevant chart and metric ideas based on the sheet's actual data.
- Use the `user_prompt` parameter to guide the AI toward chart types or topics relevant to your goal, improving the relevance of returned suggestions.
- Use the `columns` parameter to narrow suggestions when a sheet has many columns and you only want insights from a specific subset.


**Basic Parameters**

The `get_chart_suggestions` tool has the following parameters:

- `sheet_id` — The ID of the sheet to get chart suggestions for. This is a required parameter.
- `category_count` — The number of suggestion categories to return, with a maximum of 5. The `category_count` parameter defaults to `5`.
- `columns` — An optional list of column IDs used to limit suggestions to specific columns. The `columns` parameter defaults to `null`.
- `suggestion_count` — The number of suggestions per category, with a maximum of 4. The `suggestion_count` parameter defaults to `4`.
- `user_prompt` — Optional natural language context describing the kind of chart you want, used to guide the AI's suggestions. The `user_prompt` parameter defaults to `null`.


**Key Features**

The `get_chart_suggestions` tool has the following key features:

- **AI-powered suggestions** — The tool uses AI to analyze the sheet's data and generate relevant chart suggestions organized into categories.
- **Categorized results** — Suggestions are grouped into categories, each containing multiple presentation options with different chart types.
- **Ready-to-use prompts** — Each suggestion includes a prompt that can be passed directly to the `create_chart_from_prompt` tool to create a chart without additional input.
- **Column scoping** — Suggestions can be limited to specific columns by passing their IDs, allowing focused exploration of particular data dimensions.
- **User context guidance** — An optional natural language prompt lets you steer the AI toward suggestions that match your analytical intent.


**Limitations**

The `get_chart_suggestions` tool has the following limitations:

- Only sheets are supported as data sources; reports and dashboards cannot be used.
- Suggestions are AI-generated and may not always be optimal for the data in the sheet.
- A maximum of 5 categories and 4 suggestions per category can be returned per call.


**Use Cases**

The following items describe use cases for the `get_chart_suggestions` tool:

- **Exploratory data analysis** — Use the tool when first working with an unfamiliar sheet to discover what charts and metrics the data is best suited for.
- **Guided chart creation** — Use suggestions as a starting point before calling `create_chart_from_prompt`, reducing the need to craft prompts from scratch.


### create_chart_from_prompt

**Access scopes:** `READ_SHEETS`

`create_chart_from_prompt` generates charts and metrics from a natural language description by starting or continuing a conversation against a sheet's data. The response can contain multiple messages, each representing a chart or metric, along with its definition and data. Chart data is not automatically rendered visually — it must be rendered as an artifact or inline visualization using the labels and datasets from the response.

**Best Practices**

The following items are best practices for using the `create_chart_from_prompt` tool:

- Use the `get_chart_suggestions` tool before this tool to surface relevant chart and metric ideas based on the sheet's data.
- After rendering the chart(s), call the `refine_chart` tool and offer the `add_charts_to_dashboard` tool.
- When the response contains multiple messages, ask the user which chart they want to refine or add to a dashboard first, then use that message's ID when calling the `refine_chart` or `add_charts_to_dashboard` tool.


**Basic Parameters**

The `create_chart_from_prompt` tool has the following parameters:

- `prompt`: A natural language description of the chart to create.
- `sheet_id`: The ID of the sheet to chart data from.
- `conversation_id`: An existing conversation ID to continue. The `conversation_id` parameter defaults to `null`.
- `previous_message_id`: The message ID of the previous answer, required when continuing an existing conversation. The `previous_message_id` parameter defaults to `null`.


**Key Features**

The `create_chart_from_prompt` tool has the following key features:

- **Natural language input:** Accepts a plain-language prompt describing the desired chart or metric, so no chart configuration syntax is required.
- **Multi-output responses:** A single call can return multiple charts and metrics together in the `messages` array.
- **Conversation continuity:** Supports multi-turn conversations by accepting a `conversation_id` and `previous_message_id` to refine or extend a prior result.
- **Rich result data:** Each message in the response includes the chart type, labels, and datasets needed to render the visualization.
- **Downstream workflow integration:** Results integrate directly with the `refine_chart`, `explain_chart`, and `add_charts_to_dashboard` tools using the returned conversation and message IDs.


**Limitations**

The `create_chart_from_prompt` tool has the following limitations:

- Only sheet data sources are supported; reports and dashboards cannot be used as data sources.
- Complex multi-axis charts may require follow-up refinement via the `refine_chart` tool.
- Chart data is not rendered automatically — rendering must be handled separately as an artifact or inline visualization.
- When continuing a conversation, `previous_message_id` is required alongside `conversation_id`; omitting it prevents continuation.


**Use Cases**

The following items describe use cases for the `create_chart_from_prompt` tool:

- **Quick data visualization:** Rapidly generate a bar, line, or pie chart from sheet data using a simple plain-language request, without needing to configure chart parameters manually.
- **Iterative chart refinement:** Start a chart conversation, review the result, then continue the same conversation with a follow-up prompt to adjust grouping, filters, or chart type.
- **Multi-metric dashboards:** Generate several related charts or metrics in a single call and then add selected results to a dashboard using the `add_charts_to_dashboard` tool.
- **Exploratory data analysis:** Use alongside the `get_chart_suggestions` tool to discover meaningful visualizations for a sheet before committing to a specific chart type.
- **Explainable reporting:** Pair with the `explain_chart` tool to produce a plain-language summary of how a generated chart or metric was derived from the underlying data.


### create_chart_from_data

**Access scopes:** **none**

Builds a chart structure from pre-computed data values — supporting bar, line, pie, and stacked bar chart types. Unlike the `create_chart_from_prompt` tool, `create_chart_from_data` does not query any sheet; you supply the data values directly. The resulting chart definition must be rendered manually as an artifact or inline visualization.

**Best Practices**

The following items are best practices for using the `create_chart_from_data` tool:

- Use the `create_chart_from_prompt` tool instead when working from raw Smartsheet data, as it handles data extraction automatically.
- Pre-compute or extract all data values before calling this tool, since it does not perform any sheet queries.
- Match the number of entries in each dataset's `data` array to the number of entries in `labels` to ensure a well-formed chart.
- After the tool returns, always render the chart yourself using the labels from `result.labelInfo.labels` and the datasets from `result.dataSetInfo.dataSets`.


**Basic Parameters**

The `create_chart_from_data` tool has the following parameters:

- `chart_type`: The type of chart to render. Accepted values are `bar`, `line`, `pie`, and `stacked_bar`.
- `datasets`: An array of dataset objects. Each object has a `data` property (an array of numbers) and an optional `label` property for the series name.
- `labels`: Category labels used on the x-axis for bar and line charts, or as segment labels for pie charts.
- `title`: The chart title.
- `data_format`: How to format data values displayed in the chart. Accepted values are `number`, `currency`, and `percent`. The `data_format` parameter defaults to `number`.


**Key Features**

The `create_chart_from_data` tool has the following key features:

- **Pre-computed data input:** Accepts data you have already computed or extracted, giving you full control over what is charted without relying on a sheet query.
- **Multiple chart types:** Supports `bar`, `line`, `pie`, and `stacked_bar` chart types to cover a range of visualization needs.
- **Multi-series support:** Accepts multiple dataset objects in a single call, enabling side-by-side or layered series on the same chart.
- **Flexible data formatting:** Formats displayed values as plain numbers, currency, or percentages via the `data_format` parameter.
- **Structured chart definition output:** Returns a JSON chart definition containing labels and datasets that you use to render the chart as an artifact or inline visualization.


**Limitations**

The `create_chart_from_data` tool has the following limitations:

- Does not query any Smartsheet sheet data; all values must be provided by the caller.
- Cannot be refined using the `refine_chart` tool, as there is no backing conversation.
- Cannot be added to a dashboard via the `add_charts_to_dashboard` tool, since it has no conversation backing.
- Only supports the four chart types explicitly listed (`bar`, `line`, `pie`, `stacked_bar`); other chart types are not available.
- Does not validate that dataset lengths match the number of labels, so mismatches must be avoided by the caller.


**Use Cases**

The following items describe use cases for the `create_chart_from_data` tool:

- **Visualizing externally sourced data:** Charting data that originates outside Smartsheet, such as values from a CSV export, a database query, or a manual calculation.
- **Displaying aggregated metrics:** Rendering summary statistics or KPIs that have already been computed, without needing to re-query a sheet.
- **Multi-series comparisons:** Presenting multiple data series side by side — for example, comparing actual versus budgeted figures across several months.
- **Percentage and currency breakdowns:** Displaying financial distributions or completion rates using the `currency` or `percent` data formats for cleaner presentation.
- **Custom chart construction:** Building a precisely defined chart when the automatic AI-driven interpretation of the `create_chart_from_prompt` tool would not produce the exact structure needed.


### refine_chart

**Access scopes:** `READ_SHEETS`

The `refine_chart` tool retrieves suggested follow-up refinements for an existing chart within an active conversation. It does not itself modify or update the chart — it returns a list of suggested next steps that can be applied by making a subsequent call to the `create_chart_from_prompt` tool.

**Best Practices**

The following items are best practices for using the `refine_chart` tool:

- Use the `create_chart_from_prompt` tool before calling `refine_chart` to establish a valid conversation and obtain the required `conversation_id` and `message_id`.
- To apply a chosen refinement, call the `create_chart_from_prompt` tool with the same `conversation_id`, the `previous_message_id`, and the refinement's prompt.


**Basic Parameters**

The `refine_chart` tool has the following parameters:

- `conversation_id` — The conversation ID returned from the `create_chart_from_prompt` tool. This is required.
- `message_id` — The message ID of the chart or metric answer to refine. This is required, and the message must be an answer (chart or metric), not a question.
- `count` — The number of refinement suggestions to return. The `count` parameter defaults to `5`, with a minimum of 1 and a maximum of 10.


**Key Features**

The `refine_chart` tool has the following key features:

- **Suggestion-based refinement** — Returns a set of suggested refinements, each with a title, prompt, chart type, and type, giving users structured options for improving their chart.
- **Conversation continuity** — Operates within an existing conversation started by the `create_chart_from_prompt` tool, preserving context across chart iterations.
- **Configurable suggestion count** — Allows the caller to control how many refinement suggestions are returned, up to a maximum of 10.
- **Non-destructive operation** — Does not alter the existing chart in any way; changes are only applied when a refinement prompt is passed to the `create_chart_from_prompt` tool.


**Limitations**

The `refine_chart` tool has the following limitations:

- Requires an active conversation established by the `create_chart_from_prompt` tool; it cannot be used independently or with charts created via the `create_chart_from_data` tool.
- Returns suggestions only — applying a refinement requires a separate follow-up call to the `create_chart_from_prompt` tool.
- The `message_id` must reference an answer message (a chart or metric); question messages are not valid targets.
- Charts created via `create_chart_from_data` cannot be refined using this tool, as they have no backing conversation.


**Use Cases**

The following items describe use cases for the `refine_chart` tool:

- **Iterative chart improvement** — After generating an initial chart with the `create_chart_from_prompt` tool, use `refine_chart` to surface actionable next steps for improving the visualization.
- **Guided user experience** — Present refinement suggestions to a user so they can select a direction for updating their chart without needing to write a new prompt from scratch.
- **Chart type exploration** — Use returned `chartType` values in suggestions to help users discover alternative chart types that may better represent their data.
- **Multi-chart conversation management** — In conversations that produce multiple charts or metrics, use `refine_chart` with a specific `message_id` to target refinements at a particular chart.


### explain_chart

**Access scopes:** `READ_SHEETS`

The `explain_chart` tool provides a plain-language explanation of how a chart or metric answer was produced within a charting conversation. It returns a summary and step-by-step reasoning describing the logic behind the chart, without modifying the chart itself.

**Best Practices**

The following items are best practices for using the `explain_chart` tool:

- Use `explain_chart` after generating a chart with the `create_chart_from_prompt` tool, to give stakeholders or reviewers a clear understanding of how the result was derived.
- When working with a chart that has been saved to a dashboard, supply the optional `chart_id` and `chart_version` parameters for the most accurate explanation.
- Confirm that the target message is an answer message (containing a chart or metric), not a question or prompt message, before calling the tool.


**Basic Parameters**

The `explain_chart` tool has the following parameters:

- `conversation_id`: The conversation ID from the `create_chart_from_prompt` tool. This parameter is required and identifies the active charting conversation containing the answer to explain.
- `message_id`: The message ID of the chart or metric answer to explain. This parameter is required and must reference an answer message, not a question.
- `chart_id`: An optional chart ID for a chart that has already been saved to a dashboard.
- `chart_version`: An optional chart version for a chart that has already been saved to a dashboard.


**Key Features**

The `explain_chart` tool has the following key features:

- **Plain-language summary:** Returns a human-readable summary describing how the chart or metric result was produced, making it easy to communicate methodology to non-technical stakeholders.
- **Step-by-step reasoning:** Breaks down the logic behind the chart into discrete steps, providing transparency into how the data was interpreted and visualized.
- **Dashboard chart support:** Accepts optional `chart_id` and `chart_version` parameters to explain charts that have been saved to a dashboard via the `add_charts_to_dashboard` tool.
- **Conversation-scoped context:** Operates within the context of an existing conversation started by the `create_chart_from_prompt` tool, meaning all relevant data and prompt history inform the explanation.


**Limitations**

The `explain_chart` tool has the following limitations:

- Requires an active conversation originally created by the `create_chart_from_prompt` tool — it cannot explain charts created through the `create_chart_from_data` tool, as those have no conversation backing.
- The `message_id` must reference an answer message (a chart or metric result), not a question or prompt message.
- Does not return updated chart data or a new visualization — it returns explanation text only.
- Cannot be used to modify, regenerate, or refine a chart; use the `refine_chart` tool for those operations.


**Use Cases**

The following items describe use cases for the `explain_chart` tool:

- **Stakeholder transparency:** Explain to a non-technical audience how a revenue or status chart was derived from sheet data, so they can trust and act on the results.
- **Audit and review:** Document the reasoning behind a dashboard chart during a project review or compliance audit, using the step-by-step explanation as a reference artifact.
- **Debugging unexpected results:** Investigate why a chart looks different than expected by reviewing the reasoning steps to spot incorrect column mappings or data interpretations.
- **Onboarding and knowledge transfer:** Help new team members understand what a saved dashboard chart represents and how it was built, without needing to recreate it.
- **Multi-chart disambiguation:** After the `create_chart_from_prompt` tool returns multiple chart messages in a single response, use `explain_chart` on a specific message ID to clarify what each individual chart represents before deciding which to refine or save.


### query_chart

**Access scopes:** `READ_SHEETS`

The `query_chart` tool queries a saved chart definition's data for visualization, returning the chart definition, data points, and styling needed for rendering. This tool is exclusively for charts that have already been saved to a dashboard via the `add_charts_to_dashboard` tool.

**Best Practices**

The following items are best practices for using the `query_chart` tool:

- Use the `chart_id` and `version` values returned directly from the `add_charts_to_dashboard` tool response, as these are the only reliable sources for those values.
- Do not call the `get_dashboard` tool to retrieve the `chart_id` or `version`, as chart widgets do not expose these fields through the public dashboard API.
- Do not use this tool after calling `create_chart_from_prompt`, as that tool returns chart data inline and does not produce a saved chart ID.


**Basic Parameters**

The `query_chart` tool has the following parameters:

- `chart_id`: A string representing the chart ID obtained from the `add_charts_to_dashboard` tool. This is a required parameter.
- `version`: A string representing the chart version obtained from the `add_charts_to_dashboard` tool. This is a required parameter.


**Key Features**

The `query_chart` tool has the following key features:

- **Saved chart retrieval:** Retrieves the full chart definition, including data points and styling, for a chart that has been saved to a Smartsheet dashboard.
- **Visualization-ready output:** Returns all data necessary to render the chart, including chart structure and configuration.
- **Dashboard chart support:** Works specifically within the context of charts added to dashboards, maintaining dashboard-specific context and styling.


**Limitations**

The `query_chart` tool has the following limitations:

- Requires a `chart_id` and `version` sourced exclusively from the `add_charts_to_dashboard` tool response.
- Does not work with conversation message IDs produced by the `create_chart_from_prompt` tool.
- The `chart_id` and `version` cannot be retrieved via the `get_dashboard` tool.
- Only applies to charts already saved to a dashboard; it cannot query unsaved or in-progress charts.


**Use Cases**

The following items describe use cases for the `query_chart` tool:

- **Re-rendering a dashboard chart:** Retrieves the data and styling for a previously saved chart so it can be rendered again in a visualization artifact or inline display.
- **Inspecting saved chart data:** Allows review of the underlying data points of a chart that was saved to a dashboard.
- **Syncing chart state:** Fetches the current definition of a saved chart to ensure the rendered visualization reflects the most up-to-date saved state on the dashboard.


### get_chart_definition

**Access scopes:** `READ_SHEETS`

Retrieves a saved chart definition — including its type, axes, styling, and configuration — for a chart that has already been saved to a dashboard via the `add_charts_to_dashboard` tool.

**Best Practices**

The following items are best practices for using the `get_chart_definition` tool:

- Use the `chart_id` and `version` values returned directly by the `add_charts_to_dashboard` tool, as these are the only reliable sources for these required values.
- Do not call the `get_dashboard` tool to retrieve `chart_id` or `version`, as chart widgets do not expose these fields through the public dashboard API.
- Do not call this tool after `create_chart_from_prompt`, as that tool returns chart data inline and no saved chart definition exists until the chart is added to a dashboard.
- Pass `dashboard_id` and `widget_id` when dashboard-specific styling needs to be reflected in the retrieved definition.


**Basic Parameters**

The `get_chart_definition` tool has the following parameters:

- `chart_id`: The chart ID from the `add_charts_to_dashboard` tool. This is a required string parameter.
- `version`: The chart version, also returned by the `add_charts_to_dashboard` tool. This is a required string parameter.
- `dashboard_id`: The dashboard ID, used to apply dashboard-specific styling. The `dashboard_id` parameter defaults to `null`.
- `widget_id`: The widget ID, used when the chart is placed on a dashboard. The `widget_id` parameter defaults to `null`.


**Key Features**

The `get_chart_definition` tool has the following key features:

- **Chart type and configuration retrieval:** Returns the complete chart definition, including chart type, axes configuration, and styling details.
- **Dashboard-specific styling:** Accepts optional `dashboard_id` and `widget_id` parameters to return styling that reflects the chart's appearance within a specific dashboard context.
- **Version-aware retrieval:** Uses a version string alongside the chart ID to ensure the desired iteration of a chart definition is retrieved.


**Limitations**

The `get_chart_definition` tool has the following limitations:

- Requires a `chart_id` and `version` obtained specifically from the `add_charts_to_dashboard` tool response; these values cannot be retrieved via the `get_dashboard` tool.
- Only works with charts that have been saved to a dashboard; it does not work with conversation message IDs or charts created inline via `create_chart_from_prompt` that have not yet been added to a dashboard.


**Use Cases**

The following items describe use cases for the `get_chart_definition` tool:

- **Inspecting a saved chart:** Retrieve the full configuration of a chart that was previously saved to a dashboard to review its type, axes, and styling settings.
- **Debugging chart appearance:** Examine the chart definition alongside dashboard and widget context to understand why a chart renders in a particular way.
- **Auditing dashboard charts:** Review chart definitions as part of a broader audit of dashboard content and visualization standards.
- **Pre-refinement review:** Inspect an existing chart definition before initiating a refinement workflow to understand what changes are needed.


### add_charts_to_dashboard

**Access scopes:** `CREATE_SIGHTS`

The `add_charts_to_dashboard` tool adds one or more previously created charts to a Smartsheet dashboard as new widgets in a single request. Each chart must have been created via the `create_chart_from_prompt` tool or refined via the `refine_chart` tool before it can be added. The tool returns a `dashboardPermalink` that links directly to the dashboard, and one result per chart, in the order the charts were supplied.

This tool is unavailable for the Microsoft 365 Copilot Connector (the Copilot Studio connector for Copilot Chat)

**Best Practices**

The following items are best practices for using the `add_charts_to_dashboard` tool:

- Pass every chart destined for the same dashboard in one call, even when there is only one chart.
- Don't add charts to the same dashboard with several calls in parallel. Each call places its widgets independently, so parallel calls can leave widgets overlapping.
- For more than 10 charts, make consecutive calls and wait for each call to finish before starting the next one.
- Verify that the target dashboard ID is correct before calling this tool, using the `list_dashboards` tool or the `get_dashboard` tool if needed.
- Check each entry in `results`. A successful call doesn't mean every chart was added, so tell the user which charts were added and which weren't.
- Only retry entries whose `reason` is `NOT_ATTEMPTED`, because those charts were never sent. Any other reason may already have created the widget, so retrying risks a duplicate.
- Surface the returned `dashboardPermalink` to the user as a "View on dashboard" link so they can immediately see the result.


**Basic Parameters**

The `add_charts_to_dashboard` tool has the following parameters:

- `dashboard_id` — An integer representing the ID of the dashboard where the chart widgets are placed.
- `charts` — An array of 1 to 10 charts to add, in the order they should appear. Each chart has the following properties:
  - `conversationId` — A string representing the conversation ID returned from the chart creation or refinement response.
  - `messageId` — A string representing the message ID of the specific chart response to add.
  - `messageType` — A string representing the message type from the chart creation or refinement response (`messages[].messageType`). The value must be `v2/ChartMessage`.


**Key Features**

The `add_charts_to_dashboard` tool has the following key features:

- **Multiple charts in one call** — Adds up to 10 charts to a dashboard in one request, placing them one after another so they don't overlap.
- **Per-chart results** — Returns one entry per chart, in request order. Each entry has a `type` of `SUCCEEDED` or `FAILED`. A failed entry includes a `reason`, such as `NOT_FOUND`, `UNAUTHORIZED`, or `NOT_ATTEMPTED`.
- **Conversation-based workflow** — Ties directly into the conversation flow started by the `create_chart_from_prompt` tool, using the `conversationId` and `messageId` from that flow to identify exactly which result to publish.
- **Dashboard permalink** — Returns a `dashboardPermalink`, giving immediate access to the live dashboard view.
- **Widget metadata** — Returns a `chartId`, `version`, and `widgetId` for each added chart that can be used with the `get_chart_definition` tool and the `query_chart` tool for further inspection or rendering.
- **Non-destructive placement** — Adds each chart as a new widget without moving or altering any existing widgets on the dashboard.


**Limitations**

The `add_charts_to_dashboard` tool has the following limitations:

- The user must have edit access to the target dashboard; the tool does not succeed with view-only permissions.
- Only charts created through the conversation flow (via the `create_chart_from_prompt` tool or the `refine_chart` tool) can be added; manually defined charts are not supported.
- Metrics can't be added to a dashboard. If any chart's `messageType` isn't `v2/ChartMessage`, the call is rejected and no charts are added.
- All charts in a call go to one dashboard; use one call per dashboard.
- Each chart is added as a new widget; the tool does not update or replace an existing widget.
- If a chart fails, charts already added by the same call stay on the dashboard.


**Use Cases**

The following items describe use cases for the `add_charts_to_dashboard` tool:

- **Publishing an AI-generated chart** — After using the `create_chart_from_prompt` tool to generate a chart from sheet data, use this tool to publish that chart directly onto an operational or executive dashboard.
- **Multi-chart deployment** — When a `create_chart_from_prompt` response returns several charts, add the ones you want to a dashboard in a single call.
- **Iterative dashboard building** — Combine with the `refine_chart` tool to iteratively improve a chart before finalizing and publishing it to a dashboard.


## Sharing

This section describes Smartsheet MCP server tools for sharing assets with groups and other users.

### list_shares

**Access scopes:** `ADMIN_WORKSPACES`, `SHARE_SHEETS`, `SHARE_SIGHTS`

**Toolset:** `sharing`

The `list_shares` tool retrieves a list of all users and groups with whom a Smartsheet asset has been shared. It returns share details including access levels, user and group information, and share scope, making it useful for understanding who has access to a given asset.

**Best Practices**

The following items are best practices for using the `list_shares` tool:

- Use the `sharing_include` parameter to narrow results when you only need direct shares versus inherited workspace shares, as this reduces noise in the response.
- When auditing permissions across assets with many collaborators, paginate through all results using `last_key` before drawing conclusions, since each page returns up to 100 shares.
- Combine results from the `list_shares` tool with the the `list_sheets` or the `browse_workspace` tool to build a comprehensive access map across multiple assets.


**Basic Parameters**

The `list_shares` tool has the following parameters:

- `asset_id`: The integer ID of the asset whose shares are being listed. This is a required parameter.
- `asset_type`: The type of asset being queried. Accepted values are `sheet`, `report`, `sight`, `workspace`, `collection`, and `file`. This is a required parameter.
- `last_key`: A pagination token used to retrieve the next page of results when an asset has more than 100 shares. Omit the `last_key` parameter to get the first page of results.
- `sharing_include`: An optional filter for share scope. Use `ITEM` to return only direct shares, or `WORKSPACE` to include shares inherited from a parent workspace. The `sharing_include` parameter defaults to `null`, meaning no scope filter is applied.


**Key Features**

The `list_shares` tool has the following key features:

- **Multi-asset type support:** Works across sheets, reports, sights (dashboards), workspaces, collections, and files, providing a unified way to audit sharing across different Smartsheet content types.
- **Share scope filtering:** The `sharing_include` parameter lets callers distinguish between shares applied directly to an item (`ITEM`) and those inherited from a workspace (`WORKSPACE`).
- **Access level detail:** Each returned share includes the collaborator's access level (e.g., viewer, editor, admin), enabling permission auditing without navigating the Smartsheet UI.


**Limitations**

The `list_shares` tool has the following limitations:

- Only assets the calling user has permission to view are accessible; shares on assets outside the user's access cannot be retrieved.
- Each page returns a maximum of 100 shares, requiring multiple calls with pagination for heavily shared assets.


**Use Cases**

The following items describe use cases for the `list_shares` tool:

- **Permission auditing:** Review all users and groups who have access to a specific sheet or workspace to ensure the right people have the right access levels.
- **Offboarding checks:** Verify whether a departing team member still has access to sensitive Smartsheet assets before revoking their access.
- **Compliance reporting:** Generate an access report for a workspace or collection to satisfy internal governance or external compliance requirements.
- **Access comparison:** Compare share lists across multiple assets to identify inconsistencies, such as a report being shared more broadly than its underlying sheet.
- **Inherited vs. direct share investigation:** Use the `sharing_include` filter to determine whether a user's access to an item is directly granted or inherited from a parent workspace.


## Favorites

The following sections describe Smartsheet MCP server tools for marking assets as favorites and operating on your list of favorites.

### list_favorites

**Access scopes:** `READ_SHEETS`

**Toolset:** `sharing`

The `list_favorites` tool retrieves a list of all items marked as favorites by the current user. Favorites can include sheets, reports, dashboards (sights), folders, workspaces, and templates, making it a quick way to discover and access frequently used resources.

**Best Practices**

The following items describe best practices for using the `list_favorites` tool:

- Iterate through pages when the user has a large number of favorites, since pagination is always enforced.
- Use `page_size` to balance response size and performance based on your use case.


**Basic Parameters**

The `list_favorites` tool has the following parameters:

- `page` (optional) — The number of the page to retrieve, starting at 1. The page number defaults to 1.
- `page_size` (optional) — The number of items per page, between 1 and 100. The `page_size` defaults to 100.


**Key Features**

The `list_favorites` tool has the following key features:

- **Multi-type support** — Returns favorites across all supported asset types: sheets, reports, dashboards (sights), folders, workspaces, and templates.
- **Paginated results** — Pagination is always enforced, allowing controlled retrieval of large favorites lists.
- **Quick resource discovery** — Serves as a fast index for locating frequently accessed Smartsheet resources without searching the broader account.


**Limitations**

The maximum page size is 100 items per page.

**Use Cases**

The following items describe use cases for the `list_favorites` tool:

- **Dashboard building** — Retrieve a user's favorites to populate a personalized home screen or quick-access panel.
- **Audit and inventory** — List all favorited assets to understand which resources a user relies on most frequently.
- **Navigation shortcuts** — Fetch favorites at session start to build a shortcut menu for rapid navigation to key sheets and reports.


### is_favorite

**Access scopes:** `READ_SHEETS`

**Toolset:** `sharing`

The `is_favorite` tool checks if a specific asset is marked as a favorite by the current user. Use this tool to determine the favorite status of a sheet, report, dashboard, folder, workspace, or template.

**Best Practices**

The following items describe best practices for using the `is_favorite` tool:

- Use the `include` parameter with `"name"` to enrich responses with human-readable context when displaying results to users.
- Handle 404 responses gracefully, as a 404 indicates the asset is simply not favorited rather than a system error.


**Basic Parameters**

The `is_favorite` tool has the following parameters:

- `asset_id` — The ID of the asset to check.
- `asset_type` — The type of asset to check. Valid values are `workspace`, `folder`, `sheet`, `report`, `template`, and `sight` (dashboard).
- `include` — A comma-separated list of optional elements to include in the response. Valid values are `"directId"` and `"name"`. The `include` parameter defaults to `null`.


**Key Features**

The `is_favorite` tool has the following key features:

- **Multi-asset type support** — Supports all major Smartsheet asset types: workspaces, folders, sheets, reports, templates, and sights (dashboards).
- **Optional enrichment** — Accepts an `include` parameter to return additional details such as the asset's name or direct ID alongside the favorite status.


**Limitations**

The `is_favorite` tool returns a 404 Not Found error if the asset is not marked as a favorite by the user, rather than returning a false or empty result.

**Use Cases**

The following items describe use cases for the `is_favorite` tool:

- **Conditional UI state** — Determine whether to display a "Add to Favorites" or "Remove from Favorites" option in a custom interface.
- **Audit and reporting** — Verify the favorite status of specific assets as part of a broader user preference or workspace audit workflow.
- **Workflow automation** — Check favorite status as a conditional step in an automated workflow that behaves differently based on whether an asset is bookmarked.


### add_favorites

**Access scopes:** `ADMIN_WORKSPACES`

**Toolset:** `sharing`

The `add_favorites` tool marks one or more Smartsheet assets as favorites for the current user, enabling quick access to frequently used resources. It supports bulk operations across a variety of asset types, including sheets, reports, dashboards, folders, workspaces, and templates.

**Best Practices**

A best practices for using the `add_favorites` tool is to batch multiple favorites into a single request (up to 100) rather than making repeated individual calls.

**Basic Parameters**

The `add_favorites` tool has the following parameters:

`favorites` — A list of favorite objects to add, where each object contains an `objectId` (the asset's numeric ID) and a `type` (the kind of asset being favorited). At least one item is required, and up to 100 items may be submitted in a single request.

**Key Features**

The `add_favorites` tool has the following key features:

- **Bulk operations** — Up to 100 favorites can be added in a single request, reducing the number of API calls needed for large-scale operations.
- **Multi-type support** — Supports favoriting assets of different types in the same request, including workspaces, folders, sheets, reports, templates, and sights (dashboards).
- **Idempotent behavior** — Assets that are already favorited are silently ignored without returning an error, making repeated calls safe.


**Limitations**

The `add_favorites` tool has the following limitations:

- A maximum of 100 favorites can be added in a single request.
- Only private sheet-type template IDs are allowed when the type is `template`.


**Use Cases**

The following items describe use cases for the `add_favorites` tool:

- **Onboarding setup** — Quickly favorite a curated set of key sheets, dashboards, and workspaces for a new team member so they have immediate access to the most important resources.
- **Project kickoff** — At the start of a project, favorite all relevant sheets, reports, and folders so the project team can navigate to them without searching.
- **Dashboard pinning** — Favorite multiple sight (dashboard) assets that are monitored regularly, making them readily accessible from the favorites list.
- **Template library access** — Favorite commonly used private templates so they surface quickly when creating new sheets.
- **Restoring favorites** — Re-add a saved list of favorites after a reset or when setting up Smartsheet in a new context.


### delete_favorites

**Access scopes:** `ADMIN_WORKSPACES`

**Toolset:** `sharing`

The `delete_favorites` tool removes one or more items from the current user's list of favorites in Smartsheet. It supports bulk removal of sheets, reports, dashboards, folders, workspaces, or templates in a single operation. Items that are not currently favorited are silently ignored, meaning no error is raised if a specified item was never marked as a favorite. (⚠️ destructive, irreversible)

**Best Practices**

A best practice for using the `delete_favorites` tool is to group removals by asset type and batch up to 10 IDs per request to minimize the number of calls needed.

**Basic Parameters**

The `delete_favorites` tool has the following parameters:

- `asset_ids` — A list of integer object IDs to remove from favorites. All IDs assigned to the `asset_ids` parameter must belong to the same asset type, and a minimum of 1 and maximum of 10 IDs may be provided per request.
- `asset_type` — The type of asset being unfavorited. Accepted values are `workspace`, `folder`, `sheet`, `report`, `template`, or `sight`.


**Key Features**

The `delete_favorites` tool has the following key features:

- **Bulk removal** — Up to 10 favorites of the same type can be removed in a single request, reducing the number of API calls needed for cleanup operations.
- **Silent ignore** — Items that are not currently favorited are silently skipped without raising an error, making the tool safe to call idempotently.


**Limitations**

The `delete_favorites` tool has the following limitations:

- All asset IDs in a single request must be of the same type; mixing types across a single call is not supported.
- A maximum of 10 asset IDs can be removed per request.
- The operation is irreversible.


**Use Cases**

The following items describe use cases for the `delete_favorites` tool:

- **Favorites cleanup** — Remove stale or irrelevant items from a user's favorites list after projects conclude or assets are archived.
- **Workspace offboarding** — Clear favorited workspaces or folders when a user transitions off a team or project.


## Portfolios

**Important:** Portfolio tool execution requires an Enterprise or Advanced Work Management plan.

The following sections describe Smartsheet MCP server tools for managing portfolios.

### list_portfolios

**Access scopes:** `READ_SHEETS`

**Toolset:** `portfolio`

The `list_portfolios` tool retrieves a paginated list of portfolios accessible to the current user, including name, workspace ID, and permalink. Portfolios contain project templates and projects. This tool is the starting point when a user asks to list projects or project templates but has not specified which portfolio — show the available portfolios and ask the user to select one before calling the `list_project_templates` tool or the `list_projects` tool.

**Best Practices**

The following items are best practices for using the `list_portfolios` tool:

- Use this tool first whenever the user asks about projects or project templates but has not specified a portfolio.
- Pass the lastKey value from each response as `last_key` in the next request to iterate through all pages.
- Use the portfolio ID returned by this tool with the `list_project_templates` tool to discover project templates within a portfolio.


**Basic Parameters**

The `list_portfolios` tool has the following parameters:

- `last_key` — Pagination token from the previous response. The `last_key` parameter defaults to null.
- `max_items` — The maximum number of portfolios to return per page. Accepts values 1–100. The `max_items` parameter defaults to null.


**Key Features**

The `list_portfolios` tool has the following key features:

- **Portfolio discovery** — Returns all portfolios accessible to the current user in a single paginated interface.
- **Token-based pagination** — Supports keyset pagination via `last_key` and lastKey to iterate through large portfolio collections.
- **Portfolio metadata** — Returns each portfolio's ID, name, workspace ID, and permalink URL.
- **Total count** — Returns the total number of portfolios across all pages when the API makes it available.


**Limitations**

The `list_portfolios` tool has the following limitations:

- Returns basic portfolio metadata only, not full portfolio contents such as project templates or projects.
- Token-based pagination is required for large portfolio collections.


**Use Cases**

The following items describe use cases for the `list_portfolios` tool:

- **Portfolio ID discovery** — Retrieves portfolio IDs required before calling tools such as the `list_project_templates` tool or the `get_portfolio_project_list_sheet` tool.
- **Multi-portfolio selection** — Presents users who have access to multiple portfolios with a labeled list so they can confirm which portfolio to target.
- **Paginated inventory** — Handles accounts with large numbers of portfolios by iterating through pages using pagination tokens.


### create_portfolio

**Access scopes:** `ADMIN_WORKSPACES`

**Toolset:** `portfolio`

`create_portfolio` creates a new portfolio. A portfolio is a self-serve workspace for standardizing and managing projects at scale. It is created from a standard prototype that includes a project list sheet, portfolio-level dashboards, and reports. A default project template named "Standard template" is automatically created along with the portfolio.

**Best Practices**

The following items are best practices for using the `create_portfolio` tool:

- Use a descriptive name that reflects the team, program, or initiative the portfolio represents.
- After creation, use the `get_portfolio_project_list_sheet` tool to retrieve the project list sheet ID, which is the entry point for provisioning projects.
- After creation, use the `list_project_templates` tool to confirm the default "Standard template" was created and to obtain its ID before customizing the template workspace.


**Basic Parameters**

The `create_portfolio` tool has the following parameters:

- name — The name to assign to the new portfolio. Must be between 1 and 50 characters. This parameter is required.


**Key Features**

The `create_portfolio` tool has the following key features:

- **Standard prototype provisioning** — Creates the portfolio from a standard prototype that includes a project list sheet, portfolio-level dashboards, and reports automatically.
- **Default project template** — Automatically creates a default project template named "Standard template" inside the new portfolio, providing an immediate starting point for project provisioning.
- **Result message** — Returns a message field (`SUCCESS` or `PARTIAL_SUCCESS`) and a resultCode (0 for success, 3 for partial success) alongside the created portfolio object. A `SUCCESS` message doesn't confirm that a default project template was created; use `list_project_templates` to verify the template creation.


**Limitations**

The `create_portfolio` tool has the following limitations:

- Portfolio names must be between 1 and 50 characters.
- The portfolio workspace and project list sheet are provisioned asynchronously — the returned workspaceId may be null immediately after creation until provisioning completes.


**Use Cases**

The following items describe use cases for the `create_portfolio` tool:

- **Program setup** — Creates a portfolio to standardize and manage a set of related projects for a team, department, or business initiative.
- **Project management at scale** — Establishes the portfolio structure needed to provision multiple projects from shared project templates with consistent sheets, dashboards, and reports.
- **Onboarding new teams** — Quickly spins up a portfolio with a default project template so a new team can begin provisioning projects immediately.


### get_portfolio

**Access scopes:** `READ_SHEETS`

**Toolset:** `portfolio`

`get_portfolio` retrieves a specific portfolio by its ID, returning the portfolio's name, workspace ID, and permalink.

**Best Practices**

The following items are best practices for using the `get_portfolio` tool:

- Use the `list_portfolios` tool first to discover valid portfolio IDs when the user has not provided one.
- Check workspaceId in the response before calling workspace-level tools — a null value indicates the portfolio has not yet been provisioned.


**Basic Parameters**

The `get_portfolio` tool has the following parameters:

- `portfolio_id` — The UUID of the portfolio to retrieve. This parameter is required.


**Key Features**

The `get_portfolio` tool has the following key features:

- **Single portfolio retrieval** — Returns full metadata for one portfolio by ID without fetching the entire portfolio list.
- **Workspace ID access** — Returns the associated workspaceId, which is null for unprovisioned portfolios and can be used with workspace-level tools once provisioned.
- **Permalink access** — Returns a direct URL to the portfolio for sharing or navigation.


**Limitations**

The `get_portfolio` tool has the following limitations:

- Requires a valid portfolio ID — use the `list_portfolios` tool to discover IDs.
- Returns portfolio metadata only, not portfolio contents such as project templates or projects.
- workspaceId and permalink are null for portfolios that have not been provisioned.


**Use Cases**

The following items describe use cases for the `get_portfolio` tool:

- **Portfolio detail lookup** — Retrieves name, workspace ID, and permalink for a specific portfolio when its ID is already known.
- **Provisioning status check** — Verifies whether a portfolio has been provisioned by inspecting whether workspaceId is populated before proceeding with workspace operations.
- **Permalink retrieval** — Obtains a direct link to a portfolio for sharing with stakeholders.


### delete_portfolio

**Access scopes:** `ADMIN_WORKSPACES`

**Toolset:** `portfolio`

The `delete_portfolio` tool permanently deletes a portfolio by its ID, including all project template workspaces, project workspaces, and all assets within those workspaces. (⚠️ destructive, irreversible)

**Best Practices**

The following items are best practices for using the `delete_portfolio` tool:

- Use the `list_portfolios` tool to confirm the portfolio ID before deletion.
- Use the `list_project_templates` tool and the `list_projects` tool to review all project templates and projects that will be permanently deleted.
- Confirm with the user before proceeding — this operation deletes all projects, project templates, and their workspace contents with no recovery path.


**Basic Parameters**

The `delete_portfolio` tool has the following parameters:

- `portfolio_id` — The UUID of the portfolio to delete. This parameter is required.


**Key Features**

The `delete_portfolio` tool has the following key features:

- **Cascading deletion** — Deletes the portfolio workspace along with all project templates and all projects provisioned from those templates in a single operation.
- **Result message** — Returns a message field (`SUCCESS` or `PARTIAL_SUCCESS`) and a resultCode (0 for success, 3 for partial success) to confirm the outcome.


**Limitations**

The `delete_portfolio` tool has the following limitations:

- Only the portfolio owner can delete a portfolio.
- Deletion is permanent and cannot be undone — all data in the portfolio, project template, and project workspaces is permanently lost.
- Deletes all project templates and all projects provisioned from those templates; there is no option to preserve any child resources.


**Use Cases**

The following items describe use cases for the `delete_portfolio` tool:

- **Portfolio decommissioning** — Permanently removes a portfolio and all associated project templates and projects when a program or initiative has concluded and its data is no longer needed.
- **Cleanup after testing** — Deletes a portfolio created for testing or demonstration purposes to remove all test data and workspaces in a single operation.


### list_project_templates

**Access scopes:** `READ_SHEETS`

**Toolset:** `portfolio`

`list_project_templates` retrieves a list of project templates associated with a portfolio, including each template's name, workspace ID, and permalink. Each project template lives in its own workspace, and projects are created from project templates.

**Best Practices**

The following items are best practices for using the `list_project_templates` tool:

- Use the `list_portfolios` tool first to obtain a valid portfolio ID when the user has not provided one.
- Use the project template ID returned by this tool with the `list_projects` tool to discover projects provisioned from a given template.
- Use the workspaceId returned here with the `browse_workspace` tool to inspect or customize a project template's workspace before provisioning projects from it.


**Basic Parameters**

The `list_project_templates` tool has the following parameters:

- `portfolio_id` — The UUID of the portfolio whose project templates are listed. This parameter is required.
- `last_key` — Pagination token from the previous response. The `last_key` parameter defaults to null.
- `max_items` — The maximum number of project templates to return per page. Accepts values 1–100. The `max_items` parameter defaults to null.


**Key Features**

The `list_project_templates` tool has the following key features:

- **Project template discovery** — Returns all project templates associated with a specific portfolio.
- **Workspace ID access** — Returns the workspaceId for each project template, enabling workspace-level operations on the template's workspace.
- **Permalink access** — Returns a direct URL to each project template workspace for sharing or navigation.
- **Total count** — Returns the total number of project templates when the API makes it available.


**Limitations**

The `list_project_templates` tool has the following limitations:

- Requires a valid portfolio ID — use the `list_portfolios` tool to discover IDs.
- Pagination parameters (`last_key` and max_items) are accepted but currently ignored by the backend; all project templates are returned in a single response.
- workspaceId and permalink are null for project templates that have not yet been provisioned.


**Use Cases**

The following items describe use cases for the `list_project_templates` tool:

- **Template ID discovery** — Retrieves project template IDs required before calling tools such as the `list_projects` tool or the `get_project_template` tool.
- **Template workspace inspection** — Obtains workspaceId values to browse or customize a project template's workspace before provisioning new projects from it.
- **Portfolio template inventory** — Audits all project templates available within a portfolio to understand what project structures are available for provisioning.
- **Permalink retrieval** — Obtains direct links to project template workspaces for sharing with stakeholders.


### create_project_template

**Access scopes:** `ADMIN_WORKSPACES`

**Toolset:** `portfolio`

`create_project_template` creates a new project template within a portfolio. A project template copies the structure of a source workspace at creation time, and each project provisioned from it inherits the same sheets, dashboards, reports, and other items. The source workspace is not modified.

**Best Practices**

The following items are best practices for using the `create_project_template` tool:

- Omit `asset_source` unless the user explicitly provides a workspace ID or folder ID to use as the template source — do not infer or select a source workspace by default.
- Use the `browse_workspace` tool or the `search` tool to confirm a source workspace ID before passing it as asset_source.
- After creation, use the `get_project_template` tool to retrieve the workspaceId and customize the template workspace before provisioning projects from it.


**Basic Parameters**

The `create_project_template` tool has the following parameters:

- `portfolio_id` — The UUID of the portfolio in which to create the project template. This parameter is required.
- `name` — The name to assign to the new project template. Must be between 1 and 50 characters. This parameter is required.
- `asset_source` — An optional source asset whose structure is copied into the project template at creation time. When provided, requires:
  - `asset_type` — The type of source asset: workspace or folder.
  - `asset_id` — The integer ID of the source workspace or folder.


The `asset_source` parameter defaults to null.

**Key Features**

The `create_project_template` tool has the following key features:

- **Blank or source-based creation** — Creates a project template from scratch when `asset_source` is omitted, or copies the structure of an existing workspace or folder when `asset_source` is provided.
- **Non-destructive source handling** — When a source workspace or folder is specified, its contents are copied at creation time and the original is not modified.
- **Inherited project structure** — Every project provisioned from the template inherits the same sheets, dashboards, reports, and other items present in the template workspace.
- **Result message** — Returns a message field (`SUCCESS` or `PARTIAL_SUCCESS`) and a resultCode (0 for success, 3 for partial success) alongside the created project template object.


**Limitations**

The `create_project_template` tool has the following limitations:

- Project template names must be between 1 and 50 characters.
- `asset_source` copies workspace structure only at creation time — subsequent changes to the source workspace are not reflected in the template.
- The template workspace workspaceId may be null immediately after creation until provisioning completes.


**Use Cases**

The following items describe use cases for the `create_project_template` tool:

- **Blank template creation** — Creates an empty project template workspace within a portfolio that can be customized by adding sheets, dashboards, and reports before any projects are provisioned from it.
- **Template from existing workspace** — Copies the structure of an existing workspace into a new project template so that its layout and asset organization become the standard for all future projects
provisioned from it.
- **Template from folder** — Uses a specific folder's structure as the basis for a project template, enabling fine-grained control over which assets are included.
- **Multi-template portfolios** — Adds additional project templates to a portfolio to support different project types or workflows beyond the default "Standard template."


### get_project_template

**Access scopes:** `READ_SHEETS`

**Toolset:** `portfolio`

`get_project_template` retrieves a specific project template by its ID, including name, workspace ID, permalink, and a summary of the parent portfolio. The workspaceId can be used to customize the template workspace — adding sheets, dashboards, and other assets — before provisioning projects from it.

**Best Practices**

The following items are best practices for using the `get_project_template` tool:

- Use the `list_project_templates` tool first to discover valid project template IDs when the user has not provided one.
- Use the returned workspaceId with the `browse_workspace` tool to inspect or customize the template workspace before provisioning projects from it.
- Check workspaceId before calling workspace-level tools — a null value indicates the project template has not yet been provisioned.


**Basic Parameters**

The `get_project_template` tool has the following parameters:

- `blueprint_id` — The UUID of the project template to retrieve. This parameter is required.


**Key Features**

The `get_project_template` tool has the following key features:

- **Single project template retrieval** — Returns full metadata for one project template by ID without fetching the entire template list.
- **Workspace ID access** — Returns the workspaceId for the template workspace, enabling workspace-level tools to inspect or modify the template before provisioning projects.
- **Parent portfolio summary** — Includes a nested portfolio object with the parent portfolio's ID, name, and workspace ID, providing full hierarchy context in a single call.
- **Permalink access** — Returns a direct URL to the project template workspace for sharing or navigation.


**Limitations**

The `get_project_template` tool has the following limitations:

- Requires a valid project template ID — use the `list_project_templates` tool to discover IDs.
- Returns project template metadata only, not the full contents of the template workspace.
- workspaceId and permalink are null for project templates that have not yet been provisioned.


**Use Cases**

The following items describe use cases for the `get_project_template` tool:

- **Template detail lookup** — Retrieves name, workspace ID, permalink, and parent portfolio details for a specific project template when its ID is already known.
- **Template workspace customization** — Obtains the workspaceId needed to add or modify sheets, dashboards, and other assets in the template workspace before provisioning projects from it.
- **Hierarchy context** — Confirms which portfolio a project template belongs to without making a separate call to the `get_portfolio` tool.
- **Provisioning status check** — Verifies whether a project template has been provisioned by inspecting whether workspaceId is populated before proceeding with workspace operations.


### delete_project_template

**Access scopes:** `ADMIN_WORKSPACES`

**Toolset:** `portfolio`

The `delete_project_template` tool permanently deletes a project template by its ID, including all assets within the project template workspace.

(⚠️ destructive, irreversible)

**Best Practices**

The following items are best practices for using the `delete_project_template` tool:

- Use the `list_projects` tool to verify that no active projects exist under the template before attempting deletion — the operation fails if any active projects remain.
- Use the `get_project_template` tool to confirm the project template ID and review its details before deletion.
- Confirm with the user before proceeding — all data in the project template workspace is permanently lost with no recovery path.


**Basic Parameters**

The `delete_project_template` tool has the following parameters:

- `blueprint_id` — The UUID of the project template to delete. This parameter is required.


**Key Features**

The `delete_project_template` tool has the following key features:

- **Full workspace deletion** — Deletes the project template workspace and all of its contents, including sheets, dashboards, reports, and other assets.
- **Result message** — Returns a message field (`SUCCESS` or `PARTIAL_SUCCESS`) and a resultCode (0 for success, 3 for partial success) to confirm the outcome.


**Limitations**

The `delete_project_template` tool has the following limitations:

- Cannot delete a project template that has active projects — all active projects must be removed before deletion.
- Deletion is permanent and cannot be undone — all data in the project template workspace is permanently lost.
- Deletes only the project template and its workspace contents; projects previously provisioned from the template are not affected.


**Use Cases**

The following items describe use cases for the `delete_project_template` tool:

- **Template retirement** — Permanently removes a project template that is no longer in use, after all projects provisioned from it have been closed or removed.
- **Cleanup after testing** — Deletes a project template created for testing or prototyping purposes once it is no longer needed.


### list_projects

**Access scopes:** `READ_SHEETS`

**Toolset:** `portfolio`

`list_projects` retrieves a paginated list of projects associated with a specific project template, including each project's name, workspace ID, and permalink. Projects are created from project templates inside a portfolio. This tool lists projects for one project template at a time.

**Best Practices**

The following items are best practices for using the `list_projects` tool:

- Use the `list_project_templates` tool first to obtain a valid project template ID when the user has not provided one.
- Pass the lastKey value from each response as `last_key` in the next request to iterate through all pages.
- To list projects across multiple project templates, call this tool once per template ID.


**Basic Parameters**

The `list_projects` tool has the following parameters:

- `blueprint_id` — The UUID of the project template whose projects are listed. This parameter is required.
- `last_key` — Pagination token from the previous response. The `last_key` parameter defaults to null.
- `max_items` — The maximum number of projects to return per page. Accepts values 1–100. The `max_items` parameter defaults to null.


**Key Features**

The `list_projects` tool has the following key features:

- **Project discovery** — Returns all projects provisioned from a specific project template.
- **Token-based pagination** — Supports keyset pagination via `last_key` and lastKey to iterate through large project collections.
- **Project metadata** — Returns each project's ID, name, workspace ID, and permalink URL.
- **Total count** — Returns the total number of projects across all pages when the API makes it available.


**Limitations**

The `list_projects` tool has the following limitations:

- Requires a valid project template ID — use the `list_project_templates` tool to discover IDs.
- Lists projects for one project template at a time; listing projects across multiple templates requires multiple calls.
- Token-based pagination is required for large project collections.
- workspaceId and permalink are null for projects that have not yet been provisioned.


**Use Cases**

The following items describe use cases for the `list_projects` tool:

- **Project inventory** — Lists all projects under a given project template to audit what has been provisioned.
- **Project workspace navigation** — Retrieves permalinks and workspace IDs to navigate directly to project workspaces.
- **Provisioning status check** — Identifies projects where workspaceId is null, indicating provisioning has not yet completed.
- **Paginated browsing** — Handles project templates with large numbers of projects by iterating through pages using pagination tokens.


### get_project

**Access scopes:** `READ_SHEETS`

**Toolset:** `portfolio`

`get_project` retrieves a specific project by its ID, returning the project's name, workspace ID, and permalink.

**Best Practices**

The following items are best practices for using the `get_project` tool:

- Use the `list_projects` tool first to discover valid project IDs when the user has not provided one.
- Check workspaceId in the response before calling workspace-level tools — a null value indicates the project has not yet been provisioned.


**Basic Parameters**

The `get_project` tool has the following parameters:

- `project_id` — The UUID of the project to retrieve. This parameter is required.


**Key Features**

The `get_project` tool has the following key features:

- **Single project retrieval** — Returns full metadata for one project by ID without fetching the entire project list.
- **Workspace ID access** — Returns the associated workspaceId, which is null for unprovisioned projects and can be used with workspace-level tools once provisioned.
- **Permalink access** — Returns a direct URL to the project workspace for sharing or navigation.


**Limitations**

The `get_project` tool has the following limitations:

- Requires a valid project ID — use the `list_projects` tool to discover IDs.
- Returns project metadata only, not project contents such as sheets or dashboards within the project workspace.
- workspaceId and permalink are null for projects that have not yet been provisioned.


**Use Cases**

The following items describe use cases for the `get_project` tool:

- **Project detail lookup** — Retrieves name, workspace ID, and permalink for a specific project when its ID is already known.
- **Provisioning status check** — Verifies whether a project has been provisioned by inspecting whether workspaceId is populated before proceeding with workspace operations.
- **Permalink retrieval** — Obtains a direct link to a project workspace for sharing with stakeholders.


### get_portfolio_project_list_sheet

**Access scopes:** `READ_SHEETS`

**Toolset:** `portfolio`

`get_portfolio_project_list_sheet` retrieves the project list sheet associated with a portfolio. The project list sheet is the centralized control panel for provisioning projects from project templates. It returns the sheet ID and permalink. Use the sheet ID with row tools to add or update rows to trigger project provisioning.

**Best Practices**

The following items are best practices for using the `get_portfolio_project_list_sheet` tool:

- Use the `list_portfolios` tool first to obtain a valid portfolio ID when the user has not provided one.
- Confirm the portfolio is fully provisioned before calling this tool — the project list sheet is not available until provisioning completes.
- Use the `list_project_templates` tool to retrieve exact project template names before adding rows, since the Project Template column value must match a template name exactly.
- Use the returned sheet ID with the `add_rows` tool to provision new projects by adding rows with the required columns.


**Basic Parameters**

The `get_portfolio_project_list_sheet` tool has the following parameters:

- `portfolio_id` — The UUID of the portfolio whose project list sheet is retrieved. This parameter is required.


**Key Features**

The `get_portfolio_project_list_sheet` tool has the following key features:

- **Project provisioning entry point** — Returns the sheet ID of the project list sheet, which is used with row tools to provision new projects by adding rows.
- **Row-based provisioning** — Each row added to the sheet specifies a Project Name, a Project Template name (must match exactly), and a Workspace Status of Active to trigger provisioning.
- **Permalink access** — Returns a direct URL to the project list sheet for navigation or sharing.


**Limitations**

The `get_portfolio_project_list_sheet` tool has the following limitations:

- Requires a valid portfolio ID — use the `list_portfolios` tool to discover IDs.
- The portfolio must be fully provisioned before the project list sheet is available.
- A maximum of 100 projects can be provisioned per operation.


**Use Cases**

The following items describe use cases for the `get_portfolio_project_list_sheet` tool:

- **Project provisioning setup** — Retrieves the sheet ID needed before calling the `add_rows` tool to provision one or more new projects from a project template.
- **Direct sheet navigation** — Obtains a permalink to the project list sheet so users can open and manage it directly in Smartsheet.
- **Bulk project provisioning** — Retrieves the sheet ID as the first step in a workflow that adds multiple rows to provision up to 100 projects in a single operation.


## Scenario planning

**Important:** Scenario planning tool execution requires an Enterprise or Advanced Work Management plan.

The following sections describe Smartsheet MCP server tools for scenario planning.

### get_scenario_groups

**Toolset:** `scenario_planning`

`get_scenario_groups` returns a paginated list of scenario plans from the Resource Management (RM) service. A scenario plan is a named collection of scenarios that explore different resource allocation and scheduling options for a set of projects. Use this tool to discover accessible scenario plans organization-wide or scoped to a specific workspace.

**Best Practices**

The following items are best practices for using the `get_scenario_groups` tool:

- Before calling this tool, decide whether you want scenario plans for a specific workspace or across your entire Resource Management organization.
- Set `include_scenarios` to `true` when you need the child scenarios embedded in the response — for example, to resolve a scenario's `taskId` before calling tools like `get_scenario_diffs` or `get_scenario_capacity_workload`.
- Use `last_key` from each response to paginate through large result sets.


**Basic Parameters**

The `get_scenario_groups` tool has the following parameters:

- `workspace_id` — The ID of the workspace to filter results by. Omit to return scenario plans across your entire organization. This parameter is optional.
- `include_scenarios` — Set to `true` to embed child scenarios in each plan. The `include_scenarios` parameter defaults to `false`.
- `last_key` — Pagination token from the previous response to retrieve the next page. This parameter is optional.
- `max_items` — Maximum number of items to return per page. Accepted range is 1–100. The `max_items` parameter defaults to 10.


**Key Features**

The `get_scenario_groups` tool has the following key features:

- **Embedded child scenarios** — When `include_scenarios` is `true`, each plan includes its child scenarios with fields such as `taskId`, `name`, `provisioningStatus`, `isApplied`, `sourceSheetIds`, and calculated `metrics`.
- **Source sheet IDs** — Each scenario plan and child scenario exposes `sourceSheetIds`, which can be used with other Smartsheet tools to inspect or update the underlying project sheets.
- **Pagination support** — Returns results in pages using a `lastKey` cursor, allowing efficient traversal of large result sets.
- **Permission flags** — Returns `permissions` on each plan (and each scenario when included) indicating whether the current user can view, edit, delete, share, or apply.


**Use Cases**

The following items describe use cases for the `get_scenario_groups` tool:

- **Scenario plan discovery** — List all scenario plans accessible in the organization or within a specific workspace before exploring individual scenarios.
- **Scenario ID resolution** — Set `include_scenarios` to `true` to retrieve child scenario `taskId` values needed as input for `get_scenario_diffs` or `get_scenario_capacity_workload`.
- **Scenario status review** — Inspect `isApplied` and `provisioningStatus` fields on child scenarios to understand which plan is currently active and which are alternatives.


### get_scenario_group

**Toolset:** `scenario_planning`

`get_scenario_group` returns a single scenario plan by ID from the Resource Management (RM) service. Use it when the scenario plan ID is already known to fetch the plan, its child scenarios, and optionally the latest metrics for a time window.

**Best Practices**

The following items are best practices for using the `get_scenario_group` tool:

- Prefer `get_scenario_group` over the `get_scenario_groups` tool when the scenario plan ID is already known.
- When fetching metrics for a scenario plan, pass `start_date` with `end_date` to scope them to a custom time window.
- Always supply `start_date` and `end_date` together when using a custom metrics window — neither is valid without the other.


**Basic Parameters**

The `get_scenario_group` tool has the following parameters:

- `scenario_group_id` (required) — ID of the scenario plan to retrieve. Must be greater than 0.
- `include_scenarios` — Whether to embed child scenarios in the response. The `include_scenarios` parameter defaults to `true`.
- `start_date` — Start of the custom metrics window (YYYY-MM-DD); requires `end_date`. The `start_date` parameter defaults to null.
- `end_date` — End of the custom metrics window (YYYY-MM-DD); requires `start_date`. The `end_date` parameter defaults to null.


**Key Features**

The `get_scenario_group` tool has the following key features:

- **Child scenario embedding** — When `include_scenarios` is `true` (the default), the response embeds all child scenarios with their full metadata, including status, permissions, and calculated metrics.
- **Custom metrics window** — Passing `start_date` and `end_date` scopes the returned metrics to a specific time period, enabling time-bounded capacity and project analysis.
- **Rich scenario metrics** — Each embedded scenario can include capacity data per user, discipline, and role; over/under-capacity summaries; tasks at risk; project stats; and windowed duration data.
- **Baseline delta comparison** — Non-baseline scenarios include a `delta` field comparing their metrics against the baseline (delay, duration, user count, and capacity changes).
- **Permission flags** — The response includes per-user permission flags (view, edit, delete, share, apply) for both the scenario plan and each child scenario.


**Limitations**

The `get_scenario_group` tool has the following limitations:

- When specifying a custom metrics window, both `start_date` and `end_date` must be provided together.


**Use Cases**

The following items describe use cases for the `get_scenario_group` tool:

- **Fetching a known scenario plan** — Retrieve the full details of a scenario plan when the ID is already available from a prior listing or creation call.
- **Reviewing child scenarios** — Inspect all child scenarios under a plan, including their status, applied/preferred flags, and associated Smartsheet sheet and folder IDs.
- **Analyzing capacity over a date range** — Pass `start_date` and `end_date` to retrieve metrics for a specific planning window, enabling capacity analysis for a sprint, quarter, or fiscal period.
- **Comparing scenarios against the baseline** — Read the `delta` fields on non-baseline scenarios to assess how duration, delay, user count, and capacity differ from the plan's baseline.
- **Checking user permissions** — Verify what actions the current user can perform on the scenario plan and its child scenarios (view, edit, delete, share, apply).


### create_scenario_group

**Toolset:** `scenario_planning`

`create_scenario_group` creates a new scenario plan in a Smartsheet workspace. A scenario plan is a named collection of scenarios that explore different resource allocation and scheduling options for a set of projects. Creating a scenario plan creates only a baseline scenario.

**Best Practices**

The following items are best practices for using the `create_scenario_group` tool:

- Call `get_scenario_groups` first to check whether a scenario plan with the same name already exists in the target workspace.
- Use the `id` field from `browse_workspace` results to obtain numeric sheet IDs for the `source_sheet_ids` parameter.


**Basic Parameters**

The `create_scenario_group` tool has the following parameters:

- `workspace_id` — The encoded or numeric ID of the workspace in which to create the scenario plan. This parameter is required.
- `name` — The display name for the new scenario plan. This parameter is required.
- `source_sheet_ids` — An array of 1–5 numeric Smartsheet sheet IDs to associate with the plan. This parameter is required.


**Key Features**

The `create_scenario_group` tool has the following key features:

- **Automatic baseline creation** — Automatically creates a baseline scenario as the first child of the new scenario plan; the returned result contains the created baseline scenario.
- **Multi-sheet association** — Supports associating 1–5 source sheets with a single scenario plan, enabling multi-project scenario planning.
- **Permalink access** — Returns a `permalink` in the result so users can navigate directly to the new scenario plan.


**Limitations**

The `create_scenario_group` tool has the following limitations:

- You must have at least Admin permissions on the workspace where you create the plan and an Admin on all project sheets that you include.
- The source sheets must all belong to the same Resource Management organization and have Workload Tracking enabled.
- A maximum of 5 source sheets may be associated with a single scenario plan.
- Requires an Enterprise plan with the Scenario Planning feature enabled.


**Use Cases**

The following items describe use cases for the `create_scenario_group` tool:

- **New scenario plan setup** — Create a named scenario plan in a workspace to begin exploring alternative resource and scheduling options for one or more projects.
- **Multi-project planning** — Associate up to 5 project sheets with a single scenario plan to model tradeoffs across an entire portfolio of work.


### delete_scenario_group

**Toolset:** `scenario_planning`

`delete_scenario_group` permanently deletes a scenario plan and all of its scenarios from a Smartsheet workspace. This operation cannot be undone. (⚠️ destructive, irreversible)

**Basic Parameters**

The `delete_scenario_group` tool has the following parameters:

- `scenario_group_id` — The numeric database ID of the scenario plan to delete. This parameter is required. Obtain it from `get_scenario_groups`.


**Key Features**

The `delete_scenario_group` tool has the following key features:

- **Complete removal** — Deletes the scenario group and all child scenarios, including the baseline scenario, in a single operation.


**Limitations**

The `delete_scenario_group` tool has the following limitations:

- Deletion is permanent and cannot be reversed through the API.
- All scenarios within the scenario plan — including the baseline — are deleted along with the scenario plan.


**Use Cases**

The following items describe use cases for the `delete_scenario_group` tool:

- **Clean up completed planning cycles** — Remove a scenario plan after a planning cycle is complete and all decisions have been finalized and applied to source sheets.
- **Remove abandoned plans** — Delete scenario plans that were created for exploration but are no longer relevant or needed by the team.


### create_scenario

**Toolset:** `scenario_planning`

`create_scenario` adds a new scenario to an existing scenario plan (also called a scenario plan). Use this tool after `create_scenario_group` has established a baseline scenario to add alternative "what-if" scenarios for comparison.

**Best Practices**

The following items are best practices for using the `create_scenario` tool:

- Use a descriptive name (such as "Optimistic" or "Headcount Freeze") that clearly identifies what the scenario represents.
- After the tool returns, check `result.provisioningStatus`: `COMPLETED` means the scenario is ready to use; `IN_PROGRESS` or `UPDATING` means it is still being set up — refresh the scenario plan page within a minute; `FAILED` means setup did not succeed.


**Basic Parameters**

The `create_scenario` tool has the following parameters:

- `scenario_group_id` — The numeric database ID of the scenario plan to add the scenario to. This parameter is required. Obtain it from `get_scenario_groups`.
- `name` — The display name for the new scenario. This parameter is required.


**Key Features**

The `create_scenario` tool has the following key features:

- **Alternative scenario creation** — Adds a named "what-if" scenario to an existing scenario plan so it can be compared against the baseline and other scenarios.
- **Provisioning status** — Returns a `provisioningStatus` field (`COMPLETED`, `IN_PROGRESS`, `UPDATING`, `FAILED`, or `UNKNOWN`) indicating whether the scenario setup is complete.


**Limitations**

The `create_scenario` tool has the following limitations:

- A scenario plan can contain a maximum of 4 scenarios total, including the baseline.
- Cannot create a scenario outside of an existing scenario plan. Use `create_scenario_group` to create a new scenario plan first.


**Use Cases**

The following items describe use cases for the `create_scenario` tool:

- **What-if analysis** — Create an alternative scenario (such as "Delayed Start" or "Reduced Headcount") within an existing scenario plan to model different resource allocation outcomes.
- **Comparative planning** — Add multiple named scenarios to a plan to compare project timelines, capacity utilization, and over/under-capacity indicators side by side before committing to a plan.
- **Iterative exploration** — Build up a scenario plan incrementally by adding scenarios one at a time, evaluating each with the `get_scenario_diffs` tool and the `get_scenario_capacity_workload` tool before adding the next.


### get_scenario_diffs

**Toolset:** `scenario_planning`

`get_scenario_diffs` computes and returns all cell, row, and column differences between a scenario and its source sheets, including blocking and non-blocking conflicts and an aggregate apply-eligibility summary. Use this tool before applying a scenario to explain exactly what would change and whether apply is blocked.

**Basic Parameters**

The `get_scenario_diffs` tool has the following parameters:

- `scenario_id` — The `taskId` of the scenario to compute diffs for. This parameter is required. Obtain it from `get_scenario_groups` with `include_scenarios=true`.


**Key Features**

The `get_scenario_diffs` tool has the following key features:

- **Cell-level diffs** — Returns every changed cell grouped by row, with scenario and source values, column titles, column types, and column tags.
- **Row and column additions and deletions** — Lists rows and columns that exist only in the scenario, only in the source, or that have been deleted from either side.
- **Blocking and non-blocking conflicts** — Identifies per-sheet conflicts (such as type changes, formula additions, or user-added rows) and flags whether each conflict prevents applying the scenario.
- **Aggregate apply-eligibility summary** — The top-level `summary` object reports total sheets, conflict counts, cell diff counts, and the `can_apply_all_sheets` boolean so you can determine apply eligibility at a glance.
- **Per-sheet diff summaries** — Each sheet diff includes a `sheet_summary` with counts for cell diffs, row and column additions, deletions, and conflicts without requiring traversal of every detail array.


**Limitations**

The `get_scenario_diffs` tool has the following limitations:

- You must have at least Editor permissions on the workspace and all of the project sheets.


**Use Cases**

The following items describe use cases for the `get_scenario_diffs` tool:

- **Pre-apply review** — Inspect all changes a scenario would make to source sheets before committing, so stakeholders can confirm the impact.
- **Conflict resolution** — Surface blocking conflicts and their types to understand what must be resolved before a scenario can be applied.
- **Change summary reporting** — Use `summary` and per-sheet `sheet_summary` counts to produce a concise change report across all affected sheets.
- **Assignee comparison** — Compare `totalSourceAssignees` and `totalScenarioAssignees` to understand how resource assignments shift between the current plan and the scenario.


### get_scenario_capacity_workload

**Toolset:** `scenario_planning`

`get_scenario_capacity_workload` returns capacity (available hours) and workload (assigned hours) for a scenario over a specified date range, broken down by time bucket and grouped by user, discipline, or role. Use it to assess whether a scenario creates over- or under-capacity situations before applying it.

**Best Practices**

The following items are best practices for using the `get_scenario_capacity_workload` tool:

- Use `group_names` (preferred over `group_ids`) to filter results to specific people, disciplines, or roles.
- Compute utilization as `workload_hours / total_hours`; note that placeholder users do not have capacities.
- Use `instant_type=month` for broad planning views (up to a 6-month range) and `instant_type=week` for detailed scheduling views (up to 26 weeks).


**Basic Parameters**

The `get_scenario_capacity_workload` tool has the following parameters:

- `scenario_id` — The `taskId` of the scenario to query. This parameter is required. Obtain it from `get_scenario_groups` with `include_scenarios=true`.
- `start_date` — Start of the date range, inclusive, in `YYYY-MM-DD` format. This parameter is required.
- `end_date` — End of the date range, inclusive, in `YYYY-MM-DD` format. This parameter is required.
- `group_type` — Grouping dimension for the results. Accepted values are `USER`, `DISCIPLINE`, and `RESOURCE_TYPE`. The `group_type` parameter defaults to `USER`.
- `instant_type` — Time bucket size for the columns. Accepted values are `month` and `week`. The `instant_type` parameter defaults to `month`.
- `group_names` — Optional list of group display names to filter results. Groups not in this list still appear in the response with 0 hours.
- `group_ids` — Optional list of RM-native group IDs (`rmUserId` or `rmTagId`) to filter results. Use `group_names` instead when display names are available.
- `filter_roles` — Optional list of role names. Only assignments matching these roles contribute non-zero hours.
- `filter_disciplines` — Optional list of discipline names. Only assignments matching these disciplines contribute non-zero hours.
- `filter_locations` — Optional list of location names. Only assignments matching these locations contribute non-zero hours.
- `filter_assignment_status` — Optional assignment-status filter. Accepted values are `confirmed` for licensed users or `placeholder` for placeholder resources. For example, `confirmed` filters on only licensed user capacity and `placeholder` filters on only placeholder workload hours. Groups with non-matching assignments return 0 hours.


**Key Features**

The `get_scenario_capacity_workload` tool has the following key features:

- **Capacity vs. workload matrix** — Returns available total hours and assigned workload hours for each group, keyed by group display name and time bucket label, making it straightforward to calculate utilization.
- **Flexible grouping** — Supports grouping by individual users (`USER`), discipline (`DISCIPLINE`), or role (`RESOURCE_TYPE`) to match different planning perspectives.
- **Weekly or monthly bucketing** — Allows switching between weekly and monthly time buckets to adjust the level of scheduling granularity.
- **Targeted filtering** — Accepts filters by group name, role, discipline, location, and assignment status so that queries can be scoped to exactly the population you care about.


**Limitations**

The `get_scenario_capacity_workload` tool has the following limitations:

- You must have at least Editor permissions on the workspace and all of the project sheets.
- `instant_type=month` allows at most a 6-month date range; `instant_type=week` allows at most 26 weeks.
- Placeholder users do not have capacity values; only workload hours are returned for them.
- Date-range and filter values are validated by the service and may return descriptive errors if invalid.


**Use Cases**

The following items describe use cases for the `get_scenario_capacity_workload` tool:

- **Over-capacity identification** — Compare workload hours against available hours per user, discipline or role to find bottlenecks before a scenario is applied.
- **Resource utilization analysis** — Calculate utilization ratios for each team member, discipline or role over a planning horizon to guide staffing decisions.
- **Scenario comparison** — Run this tool against multiple scenarios to compare capacity impact side by side before committing to one.
- **Filtered team view** — Pass `group_names`, `filter_disciplines`, or `filter_roles` to focus the response on a specific team or skill set, reducing noise from unrelated resource groups.
- **Placeholder vs. confirmed workload** — Use `filter_assignment_status` to separate confirmed assignments from placeholder allocations for more accurate capacity planning.


### apply_scenario

**Toolset:** `scenario_planning`

`apply_scenario` applies a scenario's diffs to its source sheets. The operation is accepted asynchronously — a successful response means the apply request was accepted, not that the source sheets have finished updating. (⚠️ destructive)

**Best Practices**

The following items are best practices for using the `apply_scenario` tool:

- Call `get_scenario_diffs` first to check for blocking conflicts before calling this tool. The tool returns an error if any source sheet has blocking conflicts.


**Basic Parameters**

The `apply_scenario` tool has the following parameters:

- `scenario_id` — The `taskId` of the scenario whose diffs should be applied to source sheets. This parameter is required. Obtain it from `get_scenario_groups` with `include_scenarios=true`.


**Key Features**

The `apply_scenario` tool has the following key features:

- **Asynchronous application** — Accepts the apply request immediately and returns a success response while source sheet updates continue in the background.
- **Diff-based updates** — Writes only the changes captured in the scenario's diffs back to the source sheets, leaving unchanged data intact.


**Limitations**

The `apply_scenario` tool has the following limitations:

- You must have at least Admin permissions on the workspace and all of the project sheets.
- Returns an error if the scenario plan already has an applied scenario, or if any source sheet has blocking conflicts. Call `get_scenario_diffs` first to check for blocking conflicts before calling this tool.
- Baseline scenarios cannot be applied; only non-baseline scenarios are eligible.
- Requires apply permission on the scenario plan, editor access on all source sheets, and an Enterprise plan with the Scenario Planning feature enabled.


**Use Cases**

The following items describe use cases for the `apply_scenario` tool:

- **Commit a chosen plan** — After reviewing scenario diffs and confirming no blocking conflicts exist, apply the preferred scenario to make its changes live across all source sheets.
- **Finalize resource allocation** — Apply a scenario that resolves over-capacity issues or optimizes project timelines once stakeholders have reviewed and approved the plan.


### get_shadow_sheet

**Toolset:** `scenario_planning`

`get_shadow_sheet` retrieves a scenario sheet — a scenario-specific copy of a source sheet used by Scenario Planning. The tool returns the sheet structure including columns and rows.

**Best Practices**

The following items are best practices for using the `get_shadow_sheet` tool:

- Call the `get_scenario_groups` tool with `include_scenarios=true` first to obtain the scenario sheet ID from the `source_sheet_ids` field of a scenario.
- Use the `exclude` parameter to omit cell fields you don't need — such as `value` and `displayValue` — to reduce payload size when only column metadata is required.
- Call this tool before using the `add_shadow_sheet_rows` tool, the `update_shadow_sheet_rows` tool, or the `delete_shadow_sheet_rows` tool to confirm column IDs and existing row IDs.


**Basic Parameters**

The `get_shadow_sheet` tool has the following parameters:

- `sheet_id` — The ID of the scenario sheet to retrieve. This parameter is required. Obtain it from the `source_sheet_ids` field of a scenario returned by the `get_scenario_groups` tool with `include_scenarios=true`.
- `exclude` — An optional list of elements to omit from the response. Accepted values are `filteredOutRows`, `linkInFromCellDetails`, `linksOutToCellsDetails`, `nonexistentCells`, `cellLinks`, `value`, `displayValue`, `image`, and `imageAltText`. The `exclude` parameter defaults to `null`.
- `page` — The page number for paginating rows (1-based). The `page` parameter defaults to `1`.
- `page_size` — The number of rows per page. Maximum 500. The `page_size` parameter defaults to `100`.


**Key Features**

The `get_shadow_sheet` tool has the following key features:

- **Full sheet structure** — Returns the scenario sheet's columns and rows, providing the complete structure needed to inspect or modify scenario data.
- **Payload reduction** — The `exclude` parameter omits specific cell fields to reduce response size when only partial cell data is needed.


**Limitations**

The `get_shadow_sheet` tool has the following limitations:

- The caller must have at least Editor permissions on the workspace and all associated project sheets.
- The results don't include a permalink or workspace for the sheet, because the sheets are inaccessible.


**Use Cases**

The following items describe use cases for the `get_shadow_sheet` tool:

- **Pre-edit inspection** — Retrieve a scenario sheet's column IDs and existing row IDs before calling the `add_shadow_sheet_rows` tool, the `update_shadow_sheet_rows` tool, or the `delete_shadow_sheet_rows` tool.
- **Scenario state review** — Inspect the current data in a scenario sheet to understand how a scenario differs from its source sheet before applying it.


### get_shadow_sheet_row

**Toolset:** `scenario_planning`

`get_shadow_sheet_row` retrieves a single row from a scenario sheet by its row ID in a Scenario Planning scenario. The tool returns the full row data including cell values.

**Best Practices**

The following items are best practices for using the `get_shadow_sheet_row` tool:

- Call the `get_shadow_sheet` tool first to list rows and obtain valid row IDs before retrieving a specific row.
- Use this tool to confirm current cell values before performing an update with the `update_shadow_sheet_rows` tool.


**Basic Parameters**

The `get_shadow_sheet_row` tool has the following parameters:

- `sheet_id` — The ID of the scenario sheet containing the row. This parameter is required. Obtain it from the `source_sheet_ids` field of a scenario returned by the `get_scenario_groups` tool with `include_scenarios=true`.
- `row_id` — The ID of the row to retrieve. This parameter is required. Obtain it from the rows returned by the `get_shadow_sheet` tool.


**Key Features**

The `get_shadow_sheet_row` tool has the following key features:

- **Single-row retrieval** — Returns complete data for one row, including all cell values, without fetching the full scenario sheet.
- **Targeted inspection** — Efficiently reads a specific row by ID, useful for confirming current values before an update.


**Limitations**

The `get_shadow_sheet_row` tool has the following limitations:

- Only one row is returned per call.
- The `sheet_id` must identify a scenario sheet, not a regular sheet.
- Requires at least Editor permissions on the workspace and all associated project sheets.


**Use Cases**

The following items describe use cases for the `get_shadow_sheet_row` tool:

- **Pre-update verification** — Confirm a row's current cell values before modifying it with the `update_shadow_sheet_rows` tool.
- **Targeted data inspection** — Retrieve a single row's data without loading the full scenario sheet, reducing response size.


### add_shadow_sheet_rows

**Toolset:** `scenario_planning`

`add_shadow_sheet_rows` adds one or more rows to a scenario sheet in a Scenario Planning scenario. Each row can specify where it is inserted using location specifiers. The tool returns the newly created rows.

**Best Practices**

The following items are best practices for using the `add_shadow_sheet_rows` tool:

- Call the `get_shadow_sheet` tool first to confirm the sheet structure and obtain column IDs.
- Ensure every row in the `rows` array specifies the same positioning attribute or an acceptable combination (`toBottom`, `toTop`, `parentId`, `siblingId`, or `above`). Split rows with different locations into separate calls.
- Use `parentId` to insert a row as a child of an existing row. Combine with `toBottom=true` to place it as the last child.


**Basic Parameters**

The `add_shadow_sheet_rows` tool has the following parameters:

- `sheet_id` — The ID of the scenario sheet to add rows to. This parameter is required. Obtain it from the `source_sheet_ids` field of a scenario returned by the `get_scenario_groups` tool with `include_scenarios=true`.
- `rows` — A list of one or more row objects to add. This parameter is required. Each row object can contain the following fields:
  - `cells` — An optional array of cell objects. Each cell requires a `columnId` and either a `value` or a `formula`.
  - `toBottom`, `toTop` — Booleans to position the row at the bottom or top of the sheet.
  - `parentId` — The row ID of the parent row to nest this row under as a child.
  - `siblingId` — The row ID to place this row next to at the same indentation level.
  - `above` — When `true`, positions the row above the specified `siblingId`.
  - `indent`, `outdent` — Number of levels to adjust the row's hierarchy. Must be used alone, without other location specifiers.
  - `expanded`, `locked`, `format` — Optional row properties.


**Key Features**

The `add_shadow_sheet_rows` tool has the following key features:

- **Flexible positioning** — Supports `toTop`, `toBottom`, `parentId`, `siblingId`, and `above` location specifiers to insert rows at any position in the scenario sheet.
- **Hierarchical placement** — Use `parentId` and `indent` to create parent-child row relationships and multi-level hierarchies within the scenario.
- **Batch insertion** — Adds up to 500 rows in a single call for efficient scenario population.


**Limitations**

The `add_shadow_sheet_rows` tool has the following limitations:

- Maximum 500 rows per call.
- Does not support rows with image cells.
- The `sheet_id` must identify a scenario sheet, not a regular sheet.
- Every row in the `rows` array must specify the same positioning attribute or a compatible combination; rows with different locations require separate calls.


**Use Cases**

The following items describe use cases for the `add_shadow_sheet_rows` tool:

- **Scenario population** — Add new task rows to a scenario sheet to model additional work items in a "what-if" scenario before comparing it to the baseline.
- **Hierarchical structure** — Insert child rows under existing parent rows to add phases or subtasks within a scenario's project plan.
- **Bulk row insertion** — Add up to 500 rows in a single call to efficiently build out a scenario's scenario sheet.


### update_shadow_sheet_rows

**Toolset:** `scenario_planning`

The `update_shadow_sheet_rows` tool modifies one or more existing rows in a scenario sheet in a Scenario Planning scenario. Each row object must include a row ID identifying which row to update. The tool returns the updated rows.

(⚠️ destructive, irreversible)

**Best Practices**

The following items are best practices for using the `update_shadow_sheet_rows` tool:

- Call the `get_shadow_sheet` tool first to retrieve row IDs, then call the `get_shadow_sheet_row` tool to confirm current cell values before updating.
- Include only the fields you want to change. Unspecified fields are left unchanged.
- Review the results for errors before calling the `apply_scenario` tool.


**Basic Parameters**

The `update_shadow_sheet_rows` tool has the following parameters:

- `sheet_id` — The ID of the scenario sheet containing the rows to update. This parameter is required. Obtain it from the `source_sheet_ids` field of a scenario returned by the `get_scenario_groups` tool with `include_scenarios=true`.
- `rows` — A list of one or more row objects to update. This parameter is required. Each row object must include the following fields:
  - `id` — The ID of the row to update. This field is required.
  - `cells` — An optional array of cell objects. Each cell requires a `columnId` and either a `value` or a `formula`.
  - `toBottom`, `toTop`, `parentId`, `siblingId`, `above`, `indent`, `outdent` — Optional location specifiers to move the row simultaneously with updating its data.
  - `expanded`, `locked`, `format` — Optional row properties.


**Key Features**

The `update_shadow_sheet_rows` tool has the following key features:

- **Partial updates** — Only modifies the fields you specify; all other row data remains unchanged.
- **Combined data and position update** — Updates cell values and repositions a row in a single operation using location specifiers.
- **Batch updates** — Modifies up to 500 rows in a single call.


**Limitations**

The `update_shadow_sheet_rows` tool has the following limitations:

- Maximum 500 rows per call.
- Updates are permanent within the scenario and cannot be automatically undone.
- The `sheet_id` must identify a scenario sheet, not a regular sheet.
- Each row object must include an `id` field; rows cannot be identified by position or content.


**Use Cases**

The following items describe use cases for the `update_shadow_sheet_rows` tool:

- **Scenario adjustment** — Modify task dates, assignments, or statuses in a scenario sheet to model a different resource allocation or timeline before comparing it to the baseline.
- **Bulk cell updates** — Change values across multiple rows in a single call to efficiently update a scenario's project data.
- **Row repositioning** — Move rows to different positions or hierarchy levels within the scenario sheet while simultaneously updating their cell values.


### delete_shadow_sheet_rows

**Toolset:** `scenario_planning`

The `delete_shadow_sheet_rows` tool permanently removes one or more rows from a scenario sheet in a Scenario Planning scenario by row ID. The response contains the IDs of all deleted rows, including child rows of any specified parent rows.

(⚠️ destructive, irreversible)

**Best Practices**

The following items are best practices for using the `delete_shadow_sheet_rows` tool:

- Call the `get_shadow_sheet` tool first to retrieve rows and confirm their IDs before deleting.
- Verify the row hierarchy before deleting parent rows, as deleting a parent row also deletes all its child rows.


**Basic Parameters**

The `delete_shadow_sheet_rows` tool has the following parameters:

- `sheet_id` — The ID of the scenario sheet to delete rows from. This parameter is required. Obtain it from the `source_sheet_ids` field of a scenario returned by the `get_scenario_groups` tool with `include_scenarios=true`.
- `row_ids` — An array of one or more row IDs to delete. This parameter is required.


**Key Features**

The `delete_shadow_sheet_rows` tool has the following key features:

- **Cascading deletion** — Deleting a parent row automatically deletes all its child rows. The response lists every deleted row ID, including children.
- **Batch deletion** — Removes multiple rows in a single call.


**Limitations**

The `delete_shadow_sheet_rows` tool has the following limitations:

- Deletion is permanent within the scenario and cannot be automatically undone.
- The `sheet_id` must identify a scenario sheet, not a regular sheet.
- Requires at least Editor permissions on the workspace and all associated project sheets.


**Use Cases**

The following items describe use cases for the `delete_shadow_sheet_rows` tool:

- **Scenario simplification** — Remove tasks or milestones from a scenario sheet that are not relevant to a particular "what-if" scenario being modeled.
- **Hierarchy pruning** — Delete parent rows along with all their children to eliminate entire work packages from a scenario in a single operation.
- **Scenario cleanup** — Remove incorrectly added rows from a scenario sheet before using the `get_scenario_diffs` tool or the `apply_scenario` tool.


## User plans

The following sections describe Smartsheet MCP server tools for managing users plans and seats.

### get_plan_id

**Access scopes:** Not applicable

**Toolset:** `users`

**Important:** The `get_plan_id` is available to system admins only.

The `get_plan_id` tool retrieves the list of plans that the authenticated user is a member of. It is primarily used to discover a `planId` when it is required by other plan-based operations, such as retrieving seat requests or managing plan members. The user's identity is resolved automatically from the authenticated session, so no user ID input is required.

**Best Practices**

The following items are best practices for using the `get_plan_id` tool:

- Call this tool first whenever a plan-based tool requires a `planId` and the user has not provided one.
- If only one plan is returned, use that `planId` directly without asking the user.
- If multiple plans are returned, present the list to the user using `plan_name` to identify each plan, with `seat_type` and `is_internal` as additional context, and ask them to confirm which `planId` to use.
- If `last_key` is present in the response, fetch the next page before presenting the full list to the user.


**Basic Parameters**

The `get_plan_id` tool has the following parameters:

- `last_key` — an opaque pagination token for fetching the next page of results. The `last_key` parameter defaults to an empty string.
- `max_items` — the maximum number of items to return per page (1–100). The `max_items` parameter defaults to 100.


**Key Features**

The `get_plan_id` tool has the following key features:

- **Session-based identity resolution:** The authenticated user's ID is resolved automatically from the session — no user ID input is required.
- **Pagination support:** Supports keyset pagination via `last_key` to iterate through plans when the user belongs to many.
- **Plan context fields:** Returns `plan_name`, `seat_type`, and `is_internal` to help identify and select the correct plan when multiple are present.


**Limitations**

The `get_plan_id` tool has the following limitations:

- Returns plan memberships for the authenticated user only — cannot look up plans for other users.
- `plan_name` may be absent for plans whose organization cannot be resolved; fall back to the raw `planId` when presenting such a plan.
- Admin status is not surfaced by this endpoint — it exists at the org layer and cannot be inferred from plan membership data.


**Use Cases**

The following items describe use cases for the `get_plan_id` tool:

- **Plan ID discovery:** Resolves the `planId` required before calling tools such as the `get_seat_requests` tool or the `get_seat_usage` tool.
- **Multi-plan selection:** Presents users who belong to multiple plans with a labeled list so they can confirm which plan to target.


### get_seat_usage

**Access scopes:** `ADMIN_USERS`

**Toolset:** `users`

The `get_seat_usage` tool retrieves per-user seat usage detail and activity scores for a plan as a flat, paginated list. Plan administrators use it to review who holds seats, how users are billed, and how active each user is.

This tool is unavailable for the Microsoft 365 Copilot Connector (the Copilot Studio connector for Copilot Chat)

**Best Practices**

The following items are best practices for using the `get_seat_usage` tool:

- Paginate through all pages by passing the `last_key` from each previous response into the next call until no `last_key` is returned.
- Use the `activity_window` parameter to match the lookback period to your review cycle — longer windows produce more stable scores for infrequent but legitimate users.
- Combine `min_activity_score`/`max_activity_score` with `billing_states` to identify paid seats held by inactive users before making licensing decisions.


**Basic Parameters**

The `get_seat_usage` tool has the following parameters:

- `plan_id` — the ID of the plan to query. Required.
- `seat_types` — filters results to one or more seat types: `MEMBER`, `PROVISIONAL_MEMBER`, `GUEST`, or `CONTRIBUTOR`.
- `billing_states` — filters results to one or more billing states: `PAID`, `CONVERT_THIS_CYCLE`, `CONVERT_NEXT_CYCLE`, or `FREE`.
- `departments` — filters results to one or more department names.
- `user_ids` — filters results to one or more specific user IDs.
- `min_activity_score` — lower bound (inclusive) on the activity score filter (0–100).
- `max_activity_score` — upper bound (inclusive) on the activity score filter (0–100).
- `activity_window` — the lookback period used to compute each user's activity score. The `activity_window` parameter defaults to `NINETY_DAYS`. Other values are
`ONE_HUNDRED_EIGHTY_DAYS`, `TWO_HUNDRED_SEVENTY_DAYS`, and `THREE_HUNDRED_SIXTY_FIVE_DAYS`.
- `max_items` — the maximum number of users returned per page. The `max_items` parameter defaults to `25`.
- `last_key` — the pagination token used to fetch the next page of results. The `last_key` parameter defaults to an empty string (first page).
- `sort_order` — the sort direction (`ASC` or `DESC`) applied to the activity score column. The `sort_order` parameter defaults to `DESC`.


**Key Features**

The `get_seat_usage` tool has the following key features:

- **Activity scoring** — computes a 0–100 activity score per user based on the configured `activity_window`, along with component-level detail supporting nuanced engagement analysis.
- **Flexible filtering** — supports simultaneous filtering by seat type, billing state, department, user ID, and activity score range.


**Limitations**

The `get_seat_usage` tool has the following limitations:

- The caller must be an administrator of the plan.
- The maximum page size is 100 users per page; larger result sets require multiple paginated calls.


**Use Cases**

The following items describe use cases for the `get_seat_usage` tool:

- **License reclamation** — identify paid seats with low activity scores to reclaim unused licenses and reduce costs.
- **Inactive user review** — filter by `min_activity_score`/`max_activity_score` to generate a list of users who have not engaged with the plan recently.
- **Billing audit** — combine `billing_states` and `seat_types` filters to audit which users are in a conversion or paid state ahead of a billing cycle.
- **Department-level reporting** — filter by `departments` to produce per-department seat usage and activity summaries for team managers.


### get_license_inventory

**Access scopes:** `ADMIN_USERS`

**Toolset:** `users`

`get_license_inventory` retrieves a point-in-time license usage snapshot for a Smartsheet plan. System administrators use it to check available licenses, track usage against plan limits, and monitor reconciliation period activity.

This tool is unavailable for the Microsoft 365 Copilot Connector (the Copilot Studio connector for Copilot Chat)

**Best Practices**

The following items are best practices for using the `get_license_inventory` tool:

- Use the `get_plan_id` tool to look up a plan ID if you don't already have one.
- Pass `period=RECON` when you need usage counts scoped to the current reconciliation window rather than the full plan period.


**Basic Parameters**

The `get_license_inventory` tool has the following parameters:

- `plan_id` — ID of the plan to retrieve license inventory for. This parameter is required.
- `period` — Reporting period for the counts: `ALL` or `RECON`. This parameter is optional. The `period` parameter defaults to `ALL`, which reports counts across the full plan period.


**Key Features**

The `get_license_inventory` tool has the following key features:

- **License counts and limits.** Reports the number of member licenses in use and the total allowed under the plan.
- **Provisional and guest/contributor counts.** Includes counts for provisional members and guest or contributor users separately from licensed members.
- **Pending purchase tracking.** Reports how many additional licenses still need to be purchased to cover current membership.
- **Reconciliation window scoping.** Supports a `RECON` period option to isolate counts to the current reconciliation window.
- **Date visibility.** Returns plan usage period dates and the current reconciliation period dates alongside the counts.


**Limitations**

The `get_license_inventory` tool has the following limitations:

- Requires the caller to be an administrator of the plan.


**Use Cases**

The following items describe use cases for the `get_license_inventory` tool:

- **Available license check.** Answer "how many licenses are left on my plan?" before provisioning new members.
- **Reconciliation review.** Determine usage within the current reconciliation window to anticipate billing adjustments before the period closes.
- **Capacity planning.** Compare current license consumption against plan limits to decide whether to purchase additional seats.
- **Pending purchase audit.** Identify how many licenses need to be purchased to bring the plan into compliance with current membership counts.


## Get more tool and capability details

The Smartsheet MCP server is **fully self-describing**, providing built-in tool definitions, detailed parameter schemas, and pre-defined prompt templates. Once your AI client is connected to the Smartsheet MCP server, your client's chat interface is a great way to learn more about the MCP server tools and capabilities.

Here are some example prompts:

- **Learn the MCP server's capabilities:**
Prompt:
> *What can I do with the Smartsheet MCP server?*
- **List underlying tools:**
Prompt:
> *List all available Smartsheet tools.*
- **Get tool examples:**
Prompt:
> *Give me examples of using create_sheet_in_workspace.*
- **Surface underlying endpoints:**
Prompt:
> *Which API endpoints does add_rows use?*


**Tip:** If you've connected your AI client to multiple MCP servers that share similar tool names, use the `Smartsheet:` prefix to avoid ambiguity.

For example,
`Describe Smartsheet:list_workspaces`

Now you know the details and best practices regarding the Smartsheet MCP server tools.

## Related content

[MCP server toolsets](/ai-mcp/smartsheet/mcp-server-toolsets) explains how toolsets work, how they benefit AI clients and users, and the search-then-execute pattern.

[Quickstart](/ai-mcp/smartsheet/mcp-quickstart) walks you through connecting Claude Code to the Smartsheet MCP server and using the server as an interactive coding companion.

Smartsheet MCP prompt library provides powerful, insightful example prompts.