Skip to content
Last updated

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 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 and standard limitations.

Discovery & navigation

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.}

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.

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.

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.
    • 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.

Attachments

list_attachments

Access scopes: READ_SHEETS

list_attachments retrieves a paginated list of all attachments on a specific sheet, including files, links, and cloud storage integrations attached at the sheet, row, and discussion levels.

Best Practices

  • Use pagination parameters to efficiently handle sheets with 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.

Basic Parameters

  • sheet_id: The ID of the sheet from which to list attachments (required).
  • page: Page number for pagination, using 1-based indexing where page 1 is the first page (optional, defaults to 1).
  • page_size: Number of attachments to retrieve per page, with a maximum of 100 (optional, defaults to 100).

Key Features

  • Comprehensive discovery: Returns attachments at all levels within a sheet, including sheet-level, row-level, and discussion-level attachments.
  • Efficient pagination: Supports paginated results to handle sheets with many attachments without overwhelming the response.
  • Permission-aware: Returns only attachments the authenticated user has permission to view.

Limitations

  • Returns only attachments the authenticated user has permission to view.

Use Cases

  • Attachment inventory: Audit all files and links attached to a sheet to understand what resources are associated with a project.
  • 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.

list_row_attachments

Access scopes: READ_SHEETS

list_row_attachments retrieves a paginated list of all attachments on a specific row. Use this tool to discover files, links, and cloud storage integrations attached to individual rows and to handle rows with many attachments efficiently through pagination.

Basic Parameters

  • sheet_id – The ID of the sheet containing the row.
  • row_id – The ID of the row to list attachments from.
  • page – Page number for pagination (1-based, defaults to 1).
  • page_size – Number of attachments per page, with a maximum of 100 (defaults to 100).

Key Features

  • Permission filtering – Returns only attachments the authenticated user has permission to view.
  • Multiple attachment types – Discovers files, links, and cloud storage integrations (Google Drive, Dropbox, etc.).

Limitations

  • Returns only attachments the authenticated user has permission to view.

Use Cases

  • Document discovery – Find all files attached to a task or item row to access supporting documentation.
  • Reference compilation – Gather all cloud storage links attached to a row for quick access to related resources.
  • Attachment auditing – Review what attachments exist on specific rows to ensure proper documentation.
  • Integration workflows – Extract attachment metadata programmatically to sync with external systems or automation tools.

list_discussion_attachments

Access scopes: READ_SHEETS

list_discussion_attachments retrieves a paginated list of all attachments on a specific discussion in Smartsheet. Use this tool to discover files and links that have been attached to discussion comments without retrieving the full discussion and comment content.

Best Practices

  • Combine with other discussion tools to build complete attachment workflows.
  • Verify both the discussion ID and sheet ID before querying to ensure accurate results.

Basic Parameters

  • discussion_id (required)—The ID of the discussion to list attachments from.
  • sheet_id (required)—The ID of the sheet containing the discussion.
  • page (optional)—Page number for pagination, starting at 1. Defaults to 1.
  • page_size (optional)—Number of attachments per page, with a maximum of 100. Defaults to 100.

Key Features

  • Complete Attachment Data—Includes attachment metadata such as name, type, size, creation details, and temporary URLs for files.
  • Multiple Attachment Types—Supports discovery of various attachment types including files, Google Drive links, OneDrive links, Box links, and other cloud storage integrations.

Limitations

  • Returns attachments from all comments in the discussion without filtering by individual comment.

Use Cases

  • Audit Attachment History—Review all files and links shared during a discussion to ensure nothing important is missing.
  • Export Discussion Files—Identify and process all attachments in a discussion for backup or archival purposes.
  • Link Validation—Check all external links and cloud storage references attached to a discussion for availability.
  • Attachment Inventory—Build a comprehensive list of what files and resources are connected to a specific discussion thread.

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 list_row_attachments or list_attachments tools 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 & 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.

Sharing

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

list_shares

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.

Access scopes: ADMIN_WORKSPACES, SHARE_SHEETS, SHARE_SIGHTS

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

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.

Access scopes: READ_SHEETS

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

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.

Access scopes: READ_SHEETS

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

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.

Access scopes: ADMIN_WORKSPACES

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

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)

Access scopes: ADMIN_WORKSPACES

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.

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 walks you through connecting Claude Code to the Smartsheet MCP server and using the server as an interactive coding companion.

Smartsheet MCP prompt cookbook provides powerful, insightful example prompts.

Previous page
Next page