# 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. Requirements **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. Note *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 Note 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 & 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 st{arting 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.} #### 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 If not specified, returns all asset types. - **`max_item`** (optional): Control page size (1–100 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 100 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", or "sights" (dashboards). 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 100; 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 100 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 100) 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 100 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. ## Sheets #### 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. #### create_sheet_in_workspace **Access scopes:** CREATE_SHEETS` `create_sheet_in_workspace` creates a new blank sheet from scratch within a specified Smartsheet workspace. Use this tool when you need to build a sheet with custom column definitions directly in a workspace, starting with a completely blank slate. **Best Practices** - Ensure exactly one column is marked as `primary: true` — sheets require a primary column. - Define all column structures before creating the sheet; you cannot add or modify columns during the creation call. - Use descriptive column titles that clearly indicate the data type and purpose. - Validate that the `workspace_id` is positive and accessible before attempting creation. - Plan your column configuration carefully, as column setup is fundamental to the sheet's functionality. **Basic Parameters** - `workspace_id` (integer, required) — Positive integer identifying the target workspace where the sheet is to be created. Obtain this from `list_workspaces`, `create_workspace`, or `search` tool results. - `sheet` (object, required) — Sheet definition object containing: - `name` (string, required) — The name of the new sheet; must be unique within the workspace. - `columns` (array, required) — Array of column objects defining the sheet structure; at least one column must be present and exactly one must have `primary: true`. **Key Features** - **Custom column definitions** — Define columns with specific types (TEXT_NUMBER, DATE, CONTACT_LIST, CHECKBOX, PICKLIST, MULTI_PICKLIST, MULTI_CONTACT_LIST) and optional settings like format, validation, and width. - **Primary column requirement** — Automatically enforces that exactly one column is marked as primary; primary columns must be of type TEXT_NUMBER. - **System columns** — Support for system-managed columns like AUTO_NUMBER, CREATED_BY, CREATED_DATE, MODIFIED_BY, and MODIFIED_DATE. - **Advanced column options** — Configure picklist values, contact options, auto-numbering format (prefix, suffix, padding), and column tags for Gantt and calendar integration. - **Project settings** — Optionally set working days, non-working days, and work day length for project-based sheets. - **Gantt and resource management** — Enable Gantt views and resource management features at sheet creation time. - **Sheet metadata** — Automatically generates and returns sheet ID, permalink, and full column metadata upon creation. **Limitations** - Sheet name must be unique within the workspace; duplicate names cause creation to fail. - Exactly one column must have `primary: true` or the request fails. - At least one column definition is required in the request. **Use Cases** - **Building project tracking sheets** — Create sheets with custom columns for tasks, dates, assignees, and status to set up project management workflows. - **Inventory management systems** — Define columns for item names, quantities, locations, and dates to establish product tracking sheets. - **Customer database setup** — Create sheets with contact information, company details, and communication preferences columns. - **Survey or form data collection** — Build sheets with predefined column structures to capture and organize responses. - **Team resource planning** — Set up sheets with resource names, skills, availability, and allocation columns for capacity planning. #### create_sheet_in_folder **Access scopes:** CREATE_SHEETS` `create_sheet_in_folder` creates a new blank sheet from scratch within a specified Smartsheet folder. This is useful when you need to add a new sheet with custom column definitions directly to a folder structure, rather than copying from an existing template. It allows you to define columns with specific types and properties during sheet creation. **Best Practices** - Always obtain a valid `folder_id` from `browse_folder`, `search_smartsheet`, or a previous folder creation operation before calling this tool. - Ensure at least one column is marked as primary—exactly one column with `primary: true` is required for valid sheet creation. - Define column types explicitly; unsupported types cause the operation to fail. - Verify that the parent folder name is unique and meaningful to maintain organized folder structures. - Consider the column structure carefully before creation, as modifying column structure later requires separate operations. **Basic Parameters** - `folder_id` (integer, required) – The target folder ID where the sheet is to be created; must be a positive integer obtained from browsing or searching Smartsheet. - `sheet` (object, required) – A sheet object containing: - `name` (string) – The name of the new sheet. - `columns` (array) – At least one column definition with `title` and `type` properties; exactly one column must have `primary: true`. **Key Features** - **Custom column definitions** – Define columns with specific types (TEXT_NUMBER, DATE, CONTACT_LIST, CHECKBOX, PICKLIST, MULTI_PICKLIST, MULTI_CONTACT_LIST) and properties. - **Primary column requirement** – Exactly one column must be designated as primary for valid sheet creation. - **Optional configuration** – Additional sheet properties like `ganttEnabled`, `dependenciesEnabled`, and `resourceManagementEnabled` can be optionally set. - **Column properties** – Each column can include symbol settings, picklist options, contact options, validation rules, formatting, and descriptions. - **Immediate accessibility** – Returns the newly created sheet with its ID, permalink, columns, and metadata for immediate use. **Limitations** - The sheet name must be unique within the target folder. - User must have edit permissions on the parent folder. - At least one column definition is required, and exactly one column must be marked as primary. - No support for creating sheets with data rows directly; rows must be added separately with `add_rows`. - Column type validation is strict; invalid or unsupported column types fail the operation. **Use Cases** - **Project tracking sheet** – Create a blank project sheet with columns for Task Name (primary), Start Date, End Date, and Status to begin tracking immediately. - **Simple task list** – Build a quick to-do list sheet with just a Task Name column (primary) and a Checkbox column for completion tracking. - **Client onboarding tracker** – Set up a dedicated sheet with Company Name (primary), Contact Email, Status, and Assignment columns within a client folder. - **Inventory management** – Create a fresh inventory sheet with Item SKU (primary), Quantity, Reorder Level, and Last Updated columns for warehouse tracking. - **Team resource allocation** – Establish a resource sheet with Resource Name (primary), Role, Available Hours, and Project Assignment columns for capacity planning. #### 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. ## Sheet templates #### create_sheet_in_workspace_from_template **Access scopes:** CREATE_SHEETS` `create_sheet_in_workspace_from_template` creates a new sheet by cloning an existing template sheet within a specified Smartsheet workspace. This tool is useful when you want to quickly set up a new sheet with a predefined structure, formatting, and optionally data from a template. **Best Practices** - Identify and store template sheet IDs before calling this tool for efficient reuse. - Use the `include` parameter to specify exactly which template elements to copy, reducing clutter in new sheets. - Ensure template sheets are well-documented so team members understand what each template contains. - Keep template sheets updated with standardized columns and formatting to maintain consistency across projects. - Verify the workspace ID is correct before making the API call to avoid creating sheets in the wrong location. **Basic Parameters** - `workspace_id` - The positive integer ID of the target workspace where the new sheet is to be created. - `sheet` - An object containing the new sheet's configuration including `name` (sheet name) and `from_id` (the template sheet ID to clone from). - `include` - An optional comma-separated string specifying which elements from the template to copy, such as `data`, `attachments`, `discussions`, `cellLinks`, `forms`, `filters`, `rules`, and `ruleRecipients`. **Key Features** - **Template Cloning** - Copies the structure and optional content from an existing template sheet into a new sheet with a new name. - **Selective Content Transfer** - The `include` parameter allows you to choose which template elements (data, formatting, attachments, discussions, formulas, forms, filters, and automation rules) to copy into the new sheet. - **Workspace Organization** - The new sheet is created directly within the specified workspace, maintaining your organizational structure. - **Metadata Preservation** - The tool returns the new sheet's ID, permalink, columns, and other metadata, allowing you to immediately reference or further configure the sheet. **Limitations** - The sheet name must be unique within the target workspace. **Use Cases** - **Project Templates** - Clone a standardized project tracking template into a new workspace for each new project, maintaining consistent column structures and initial formatting. - **Recurring Workflows** - Create new instances of templates for recurring processes like monthly status reports, quarterly reviews, or weekly team checklists. - **Team Onboarding** - Use a predefined team sheet template to quickly set up new team tracking sheets with the same columns and structure. - **Bulk Sheet Creation** - Rapidly create multiple sheets based on the same template when scaling operations or adding new departments. - **Data Migration** - Clone a template with historical data into a new sheet for archive purposes or to start a new fiscal period with consistent structure. #### create_sheet_in_folder_from_template **Access scopes:** CREATE_SHEETS` The `create_sheet_in_folder_from_template` tool creates a new sheet from an existing template within a specified Smartsheet folder. This is useful when you want to clone a template sheet's structure and optionally its data into a target folder, without manually recreating the column structure. **Best Practices** - Verify the template sheet ID exists and is accessible before calling the tool. - Use the `include` parameter selectively to copy only the template elements you need for your use case, such as data, forms, or automation rules. - Ensure the target folder exists and you have edit permissions before attempting to create a sheet within it. - Choose meaningful sheet names that distinguish the new sheet from the template and other sheets in the folder. - When copying data from templates, verify that the data is relevant to your workflow and won't create duplicates or conflicts. **Basic Parameters** - `folder_id`: A positive integer representing the unique identifier of the Smartsheet folder where the new sheet is to be created. - `sheet`: An object containing the sheet configuration, which must include `name` (the new sheet name as a string) and `from_id` (the template sheet ID as a positive integer). - `include`: An optional comma-separated string specifying which template elements to copy, such as `data`, `attachments`, `discussions`, `cellLinks`, `forms`, `filters`, `rules`, or `ruleRecipients`. **Key Features** - **Template cloning**: Duplicates the column structure and metadata from an existing template sheet without manual setup. - **Selective content copying**: The `include` parameter lets you choose specific elements to carry over, such as cell data, file attachments, comments, formulas, and automation rules. - **Flexible automation**: Copy automation rules and rule recipients from the template to apply consistent workflows to the new sheet. - **Rich metadata support**: Preserves form definitions, saved filters, cell links, and other advanced Smartsheet features from the template. - **Automated response**: Returns the newly created sheet with its ID, permalink, full column definitions, and all relevant metadata. **Limitations** - The template sheet ID must be accessible and valid; inaccessible or deleted templates cause the operation to fail. - You must have edit permissions on the parent folder to create sheets within it. **Use Cases** - **Rapid project setup**: Create multiple project sheets from a standardized project template to ensure consistency across projects. - **Workflow standardization**: Duplicate forms, filters, and automation rules from a master template to new sheets to maintain standardized processes. - **Content cloning with selection**: Copy a template's data, attachments, and discussions into a new sheet while leaving behind certain elements you don't need. - **Team collaboration**: Quickly provision new sheets for team members using a pre-configured template with necessary columns and rules. - **Multi-environment deployment**: Create similar sheet structures across different folders to organize sheets by department, region, or project phase. ## 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. - `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. **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. - 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. #### 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. **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. ## Discussions & comments #### list_sheet_discussions **Access scopes:** READ_SHEETS` `list_sheet_discussions` retrieves all discussions from a Smartsheet, including both sheet-level and row-level conversations. This tool provides a comprehensive view of all collaboration and comments across the entire sheet. **Best Practices** - Use `include_comments` and `include_attachments` parameters to retrieve only the data you need and reduce response overhead. - Reference the returned discussion ID values when you add comments with `add_comment` or delete discussions with `delete_discussion`. - Implement pagination for sheets with many discussions by adjusting the `page` parameter. **Basic Parameters** - `sheet_id` - The ID of the Smartsheet from which you want to retrieve discussions. - `include_comments` - A boolean flag that includes all comments within each discussion when set to true. Defaults to false. - `include_attachments` - A boolean flag that includes attachments associated with discussions when set to true. Defaults to false. - `page` - The page number for pagination results. Defaults to 1, starting from the first page. - `page_size` - The number of discussions to return per page. Defaults to 100 and accepts a maximum of 100. **Key Features** - **Comprehensive retrieval** - Gathers all discussions from the entire sheet in a single call, rather than fetching row-by-row discussions separately. - **Flexible content inclusion** - Allows you to control whether comments and attachments appear in the response, optimizing for performance or completeness. - **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. **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. - Returns both sheet-level and row-level discussions without filtering, requiring client-side logic if you need to separate them. **Use Cases** - **Collaboration auditing** - Retrieve all discussions to review the history of collaboration, feedback, and decision-making on a sheet. - **Comment analysis** - Gather all comments across the sheet to identify action items, approvals, or outstanding questions. - **Data export** - Extract complete discussion records including comments and attachments for external documentation or archival purposes. - **Discussion cleanup** - Identify and remove outdated or resolved discussions to keep the sheet focused and organized. #### list_row_discussions **Access scopes:** READ_SHEETS` `list_row_discussions` retrieves all discussions that are associated with a specific row in a Smartsheet. This tool provides focused access to collaboration threads and comments on a particular row without pulling unrelated sheet-level or other row discussions. **Best Practices** - Use `include_comments` set to true when you need to read the full discussion thread content, not just discussion metadata. - Combine with `include_attachments` to retrieve any files or links that were added to the discussions. - Use pagination parameters (`page` and `page_size`) when a row has many discussions to manage large result sets efficiently. - Filter at the row level rather than retrieving all sheet discussions when you need discussions for a specific row to improve performance. **Basic Parameters** - `sheet_id`: The unique identifier of the sheet containing the row (required). - `row_id`: The unique identifier of the specific row whose discussions you want to retrieve (required). - `include_comments`: A boolean flag that determines whether full comment text is included in the response (optional, defaults to false). - `include_attachments`: A boolean flag that determines whether attached files or links are included in the response (optional, defaults to false). - `page`: The page number for pagination when results exceed one page (optional, defaults to 1). - `page_size`: The number of discussions to return per page, with a maximum of 100 (optional, defaults to 100). **Key Features** - **Row-specific focus**: Returns discussions only for the designated row, excluding sheet-level or other row discussions. - **Pagination support**: Handles rows with multiple discussions through configurable page size and page number parameters. - **Selective content loading**: Optionally includes comments and attachments to control response size and data retrieval. - **Collaboration tracking**: Provides access to all threaded conversations and feedback associated with a specific row item. **Limitations** - Returns paginated results with a default of 100 discussions per page and a maximum of 100. - Comments and attachments are only included when explicitly requested through the `include_comments` and `include_attachments` parameters. - Only returns discussions that are directly associated with the specified row. **Use Cases** - **Track row feedback**: Review all discussion threads on a specific work item, task, or record to understand stakeholder feedback and decisions. - **Extract collaboration context**: Retrieve full comment threads with attachments to reference supporting documents and historical context for a row. - **Monitor approval workflows**: Check discussions on rows to track approvals, sign-offs, or status updates in collaborative workflows. - **Audit discussion history**: Access paginated discussion data for reporting, compliance, or historical analysis of conversations on particular rows. #### get_discussion **Access scopes:** READ_SHEETS` `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_on_row **Access scopes:** WRITE_SHEETS` `create_discussion_on_row` starts a conversation focused on a particular row in a Smartsheet sheet. This tool initiates a discussion thread that references that specific row, enabling team members to collaborate and discuss issues, tasks, or details related to that row. 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 row discussions to keep comments organized by context rather than spreading feedback across sheet-level discussions. - Reference the discussion ID from the response when adding follow-up comments using `add_comment`. **Basic Parameters** - `sheet_id`: The ID of the sheet containing the row where the discussion starts. - `row_id`: The ID of the specific row to associate with the discussion. - `discussion`: An object containing a comment with the initial message text (minimum 1 character required). **Key Features** - **Auto-generated titles**: The discussion title creates automatically from the first 100 characters of the comment text, streamlining discussion setup. - **Row-focused conversations**: Discussions attach to specific rows, keeping related feedback and comments organized by row context. **Use Cases** - **Task clarification**: Start a discussion on a task row to ask team members 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. - **Collaborative problem solving**: Start discussions on rows representing problems or challenges to enable team members to brainstorm solutions together. #### create_discussion_on_sheet **Access scopes:** WRITE_SHEETS` `create_discussion_on_sheet` starts a conversation at the sheet level in Smartsheet. The discussion title generates automatically from the first 100 characters of the initial comment text. **Best Practices** - Verify the sheet ID exists before initiating a discussion. - Compose clear and concise comment text to create a meaningful auto-generated title. - Use sheet-level discussions for broad topics that affect the entire sheet, not individual rows. **Basic Parameters** - `sheet_id`: The ID of the Smartsheet where the discussion starts. - `discussion`: An object containing a comment with text to initiate the discussion. **Key Features** - **Auto-generated titles**: The discussion title creates automatically from the first 100 characters of the comment text. - **Sheet-level scope**: Discussions apply to the entire sheet, not individual rows or cells. **Use Cases** - **Broad sheet feedback**: Create discussions for general feedback or questions about the entire sheet. - **Team coordination**: Start 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` 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` `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 `list_sheet_discussions` or `list_row_discussions` 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` `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` `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. ## 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. ## Workspaces & 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 If not specified, returns all asset types. - **`max_item`** (optional): Control page size (1–100 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 100 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", or "sights" (dashboards). 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 100; 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 100 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 100) 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 100 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. **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_in_workspace **Access scopes:** ADMIN_WORKSPACES` `create_folder_in_workspace` creates a top-level folder within a workspace to organize sheets, reports, and dashboards. This tool helps establish folder structure for workspace organization. **Best Practices** - Establish a clear naming convention before creating folders to maintain consistency across workspaces. - Verify you have `ADMIN` permissions on the target workspace before attempting to create folders. **Basic Parameters** - `workspace_id` - The ID of the workspace where the folder is being created (must be a positive integer). - `folder` - A folder object containing the `name` property, which specifies the folder's name (required, must be non-empty). **Key Features** - **Workspace organization** - Creates top-level folders directly within a workspace to structure assets hierarchically. - **Asset management** - Organizes sheets, reports, and dashboards into dedicated folder structures. - **Unique Naming**: Enforces unique folder names within each workspace to maintain organization clarity. **Limitations** - User must possess `ADMIN` permissions on the workspace to create folders. - Folder names must be unique within the parent workspace. **Use Cases** - **Project organization** - Create separate folders for different projects or departments within a workspace. - **Asset categorization** - Organize sheets by team, function, or business unit. - **Workspace setup** - Establish initial folder structure when building out a new workspace. - **Access control** - Use folders to logically group assets that share similar permission requirements. #### create_folder_in_folder **Access scopes:** ADMIN_WORKSPACES` `create_folder_in_folder` creates a nested folder within an existing folder to build hierarchical folder organization. This tool enables you to establish multi-level folder structures within Smartsheet workspaces. **Basic Parameters** - `folder_id` (integer, required): The ID of the parent folder where the new folder will be created. This ID must be obtained from browse_folder, browse_workspace, or search operations and must be a positive integer. - `folder` (object, required): A folder object containing the name property. The name must be non-empty and unique within the parent folder. **Key Features** - **Hierarchical Organization**: Creates nested folders to establish multi-level folder structures within Smartsheet. - **Unique Naming**: Enforces unique folder names within each parent folder to maintain organization clarity. - **Folder Details Returned**: Returns the created folder details including the folder ID and permalink for reference and 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 parent folder to create nested folders. - Folder names must be unique within the parent folder. **Use Cases** - **Project Organization**: Create nested folders to organize projects by department, quarter, or project type within a 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. ## 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 [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. Use the Smartsheet Connector with Claude provides powerful, insightful example prompts.