add_columns
ChatGPTAdds one or more new columns to the specified sheet.
Overview
Make Smartsheet a native part of your AI workflow. Ask your AI to analyze project timelines, create graphs to summarize your sheet information, all through conversation. The Smartsheet connector eliminates manual data entry and repetitive updates, letting you focus on decisions while AI handles the details. Transform how you manage projects with AI that understands your Smartsheet data and can act on it.
Tools
add_comment
ChatGPT<summary>Adds a new comment to an existing discussion. Use this to add a reply or additional comment to a discussion thread on a sheet or row.</summary><limitations>- Requires existing discussion ID (use list_sheet_discussions or list_row_discussions first) - Comment text required (minimum 1 character) - Cannot add comments to closed/locked discussions</limitations>
add_favorites
ChatGPT<summary>Marks one or more assets as favorites for the current user. Use this tool to add sheets, reports, dashboards, folders, workspaces, or templates to the user's favorites list for quick access. Supports bulk operations.</summary><limitations>- Each favorite requires both asset ID and type - Valid asset types: workspace, folder, sheet, report, template, sight (dashboard) - Assets already favorited will be ignored (no error) - User must have access to each asset to favorite it - Maximum 100 favorites can be added in a single request </limitations>
add_rows
ChatGPT<summary>Adds one or more new rows to the specified sheet with optional positioning. Each row can specify where it should be inserted using location specifiers.</summary><location_specifiers>Control where new rows are inserted (optional - defaults to bottom if not specified): Single Location Specifiers (use only one): - toTop: Insert at the top of the sheet - toBottom: Insert at the bottom (API default) - parentId: Insert as FIRST child of parent row (indented) - siblingId: Insert BELOW the specified row (same level) Valid Combinations (exceptions to single-specifier rule): - parentId + toBottom: Insert as LAST child of parent - siblingId + above: Insert ABOVE the sibling Indent/Outdent (must be used alone): - indent: Number of levels to indent (cannot use with other specifiers) - outdent: Number of levels to outdent (cannot use with other specifiers) Invalid Combinations: - Cannot use parentId with siblingId - Cannot use siblingId with toTop or toBottom (except siblingId + above) - Cannot use indent/outdent with any location specifier</location_specifiers><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.</limitations>
attach_url
ChatGPT<summary>Attaches a URL to a Smartsheet sheet, row, or comment. Use this to add links to external resources (Google Drive, Box, Dropbox, etc.).</summary><limitations>- For row attachments: provide target_id as the row ID - For comment attachments: provide target_id as the comment ID - For sheet attachments: target_id is not required</limitations>
browse_folder
ChatGPT<summary>Browse all children (nested folders, sheets, reports, dashboards) within a folder. Use this tool to explore folder contents and navigate hierarchical structure. Supports server-side filtering by asset type and token-based pagination.</summary><limitations>- Requires folder_id (obtain from search, browse_workspace, or parent folder) - Returns direct children only (not recursive) - Asset types: folders, sheets, reports, sights (dashboards) - Maximum 100 items per page</limitations><instructions>Use asset_types parameter to filter by resource type Use last_key from previous response to fetch next page </instructions>
browse_workspace
ChatGPT<summary>Browse all children (folders, sheets, reports, dashboards) within a workspace. Use this tool to explore workspace contents and discover available assets. Supports server-side filtering by asset type and token-based pagination.</summary><limitations>- Requires workspace_id (obtain from list_workspaces or search tool) - Returns top-level children only (not nested folder contents) - Asset types: folders, sheets, reports, sights (dashboards) - Maximum 100 items per page</limitations><instructions>Use asset_types parameter to filter by resource type Use last_key from previous response to fetch next page </instructions>
create_discussion_on_row
ChatGPT<summary>Creates a new discussion on a specific row. Use this to start a conversation about a particular row. The discussion title is auto-generated from the first 100 characters of the comment text.</summary><limitations>- Requires a comment with text (minimum 1 character) - Discussion title auto-generated (first 100 chars of comment) </limitations>
create_discussion_on_sheet
ChatGPT<summary>Creates a new discussion on a sheet. Use this to start a conversation at the sheet level. The discussion title is auto-generated from the first 100 characters of the comment text.</summary><limitations>- Requires a comment with text - Discussion title auto-generated (first 100 chars of comment) </limitations>
create_folder_in_folder
ChatGPT<summary>Creates a nested folder within an existing folder to build hierarchical structure. Use this tool to create multi-level folder organization.</summary><limitations>- Requires valid folder_id (from browse_workspace, browse_folder, or search) - Folder name is required (must be non-empty) - User must have
ADMIN permissions on parent folder - Folder names must be unique within parent folder - Smartsheet supports deep folder nesting</limitations>create_folder_in_workspace
ChatGPT<summary>Creates a new folder within a workspace to organize sheets, reports, and dashboards. Use this tool to add folder structure to workspaces.</summary><limitations>- Requires valid workspace_id (from list_workspaces, create_workspace, or search) - Folder name is required (must be non-empty) - User must have
ADMIN permissions on workspace - Folder names must be unique within parent workspace</limitations>create_report
ChatGPT<summary>Creates a new Smartsheet report aggregating data from one or more source sheets or workspaces. Supports custom columns, filters, grouping, sorting, and summarizing criteria.</summary><instructions>To build a report: 1. Specify a destination (folder or workspace ID and type) 2. Provide scope: list of source sheets or workspaces by asset_id and asset_type 3. Define columns: each column needs index (zero-based), type, and title matching source sheet columns 4. Optionally add report_definition for filters, grouping, sorting, and summarizing Column matching rules: - Regular columns: matched by type + title - System columns: matched by type + systemColumnType - Primary column: set primary=true - Sheet name column: set sheetNameColumn=true with type=TEXT_NUMBER All column index values must be unique. Exactly one column must have primary=true for row reports. For summary reports, exactly one column must have sheetNameColumn=true. When groupingCriteria is defined, the primary column moves to index 0 on first render in the app.</instructions>
create_sheet
ChatGPT<summary>Creates a new sheet within a specified Smartsheet folder or workspace. Supports creating from scratch with custom columns OR from an existing template. Provide CreateSheet with columns for blank sheets, or CreateSheetFromTemplate with from_id for templates.</summary><limitations>- Sheet name must be unique within the container - User must have edit permissions on the parent container - For template creation: template must be accessible to the user </limitations>
create_workspace
ChatGPT<summary>Creates a new workspace with a name. Use this tool to organize sheets, reports, and folders into a dedicated workspace.</summary><limitations>- Workspace name is required (must be non-empty) - Workspace name must be unique within organization - User must have permissions to create workspaces (
ADMIN permissions)</limitations>delete_attachment
ChatGPT<warning>⚠️ DESTRUCTIVE OPERATION: This tool PERMANENTLY DELETES an attachment from Smartsheet. Deletion is IRREVERSIBLE and CANNOT be undone. The file will be LOST FOREVER. </warning><summary>Deletes an attachment from a sheet. Use this tool ONLY when you are absolutely certain the attachment should be permanently removed. </summary><limitations>- Cannot delete attachments you don't have permission to modify - Cannot recover deleted attachments </limitations><instructions>- Use get_attachment or list_attachments to confirm attachment details first - Double-check you have the correct sheet_id and attachment_id</instructions>
delete_column
ChatGPT<warning>⚠️ DESTRUCTIVE OPERATION: This tool PERMANENTLY DELETES a column from Smartsheet. Deletion is IRREVERSIBLE and CANNOT be undone through the API. ALL DATA in this column across ALL ROWS will be LOST FOREVER. </warning><summary>Deletes a single column from the specified sheet by column ID. Use this tool ONLY when you are absolutely certain the column and all its data should be permanently removed. </summary><instructions>- ALWAYS verify column ID is correct before deletion - Use get_columns to confirm column structure and IDs first - Consider the impact on formulas, automations, and reports that reference this column - Ensure dependent workflows are updated after deletion - Remember: There is NO undo for this operation - Double-check you have the correct sheet_id and column_id</instructions><limitations>- Cannot delete system columns (e.g., Created Date, Modified Date) - Cannot delete primary columns if they are used in dependencies - Only one column can be deleted at a time (no bulk support)</limitations>
delete_comment
ChatGPT<warning>⚠️ DESTRUCTIVE OPERATION: This tool PERMANENTLY DELETES a comment from Smartsheet. Deletion is IRREVERSIBLE and CANNOT be undone. The comment and all its data will be LOST FOREVER. </warning><summary>Deletes a single comment from a sheet. Use this tool ONLY when you are absolutely certain the comment should be permanently removed. </summary><limitations>- Only the user that created the comment is permitted to delete it </limitations><instructions>- Use get_discussion or list_discussions to confirm comment details first - Double-check you have the correct sheet_id and comment_id</instructions>
delete_discussion
ChatGPT<warning>⚠️ DESTRUCTIVE OPERATION: This tool PERMANENTLY DELETES an entire discussion and ALL its comments from Smartsheet. Deletion is IRREVERSIBLE and CANNOT be undone. The discussion, all comments, and all attachments will be LOST FOREVER. </warning><summary>Deletes an entire discussion thread, including all comments within it. Use this tool ONLY when you are absolutely certain the entire discussion should be permanently removed. </summary><limitations>- Deletes the discussion AND all associated comments - Cannot delete discussions you don't have permission to modify </limitations><instructions>- Use get_discussion or list_discussions to confirm discussion details first - Double-check you have the correct sheet_id and discussion_id</instructions>
delete_favorites
ChatGPT<summary>Removes one or more items from the user's list of favorites. Use this tool to unfavorite sheets, reports, dashboards, folders, workspaces, or templates. Multiple items of the same type can be deleted in a single operation.</summary><limitations>- All items in a single request must be the same type - At least one object ID must be provided - Items not currently favorited are silently ignored (no error) - This operation cannot be undone </limitations>
delete_rows
ChatGPT<warning>⚠️ DESTRUCTIVE OPERATION: This tool PERMANENTLY DELETES rows from Smartsheet. Deletion is IRREVERSIBLE and CANNOT be undone through the API. All data in deleted rows will be LOST FOREVER. </warning><summary>Deletes one or more rows from the specified sheet by row ID. Use this tool ONLY when you are absolutely certain the rows should be permanently removed. </summary><instructions>- ALWAYS verify row IDs are correct before deletion - Consider backing up critical data before deletion - Use get_sheet_summary or get_rows_by_ids to confirm row contents first - Delete in small batches (max 10 rows per request) - Remember: There is NO undo for this operation - Double-check you have the correct sheet_id</instructions>
find_in_sheet
ChatGPT<summary>Search for text within a specific Smartsheet sheet. Returns matching cells with row/column IDs, display values, and character offsets for each match. Supports case-sensitive search, filtering, sorting, and pagination.</summary>
get_attachment
ChatGPT<summary>Retrieves attachment metadata by ID including name, type, URL, size, and timestamps. Use this to get download URLs and details for files attached to sheets, rows, or comments.</summary><limitations>- Requires exact attachment ID (no search or filtering) - Returns metadata only (not file contents) - Temporary download URLs expire (urlExpiresInMillis)</limitations>
get_cell_history
ChatGPT<summary>Retrieve the complete modification history for a specific cell in a Smartsheet. Returns timestamped changes with old/new values and user attribution. Use this when you need to track how a specific cell's value has changed over time.</summary><limitations>- Rate limited to 30 requests per minute per API token (resource-intensive operation) - Requires exact cell location: sheet ID, row ID, and column ID - Does not support bulk history retrieval for multiple cells in single request - History entries are paginated (max 100 per page) - Cannot retrieve history for entire sheet at once (cell-level only)</limitations><instructions>Best practices: - Use get_sheet_summary first to identify row_id and column_id for cells of interest - Consider using get_sheet_version to check if sheet has changed before fetching history</instructions>
get_columns
ChatGPT<summary>Retrieves detailed column metadata from a Smartsheet. Use this tool to discover available columns, their types, and properties before working with sheet data.</summary><limitations>- Must provide at least one of url or sheet_id (if both provided, they must match)- URL must be a valid Smartsheet URL</limitations>
get_dashboard
ChatGPT<summary>Retrieves detailed information about a specific dashboard by ID. Use this after list_dashboards to get complete dashboard details including widgets, layout configuration, and source information. Data includes full support for modern features like multi-contact, multi-picklist, and metric widgets with sheet summaries.</summary><limitations>- Requires valid dashboard ID from list_dashboards or other sources - User must have access to the dashboard (minimum VIEWER access)</limitations>
get_discussion
ChatGPT<summary>Retrieves a single discussion by ID with full details including comments and attachments. Use this when you have a specific discussion ID and need complete details.</summary><limitations>- Requires exact discussion ID (no search or filtering) - Returns single discussion (not paginated) - Automatically includes comments and attachments</limitations>
get_report
ChatGPT<summary>Retrieves detailed report data by report ID including columns, rows, and cells. Supports pagination for large reports with thousands of rows. Use this tool after discovering reports with list_reports to get comprehensive report data for analysis. Reports are read-only aggregated views of source sheets.</summary><limitations>- Reports are read-only (cannot be modified) - Large reports may contain thousands of rows - use pagination for efficient retrieval</limitations>
get_resource_guide
ChatGPT<summary>Retrieve resource guides for tool operations. MUST be called before any other tool. Always include 'smartsheet-intelligence' in your first call to get the orchestration rules.</summary><instructions>Pass one or more intents to load guides in a single call. The 'smartsheet-intelligence' intent returns the orchestration guide. Include it in your first call.</instructions>
get_sheet_summary
ChatGPT<summary>Retrieves sheet data with optional multi-column filtering, sorting, and column selection. Use this tool when you need to analyze, summarize, or work with Smartsheet data. IMPORTANT: Call get_columns FIRST when using filters, sorting, or columns parameters to get exact case-sensitive column names.</summary><instructions>When to call get_columns FIRST: - REQUIRED: If using filters parameter (need exact case-sensitive column names) - REQUIRED: If using sorting parameter (need exact case-sensitive column names) - REQUIRED: If using columns parameter (need exact case-sensitive column names) Why this matters: Column names are CASE-SENSITIVE. If you guess column names for filters, sorting, or column selection without calling get_columns first, you will receive validation errors. The get_columns response shows exact names, types (TEXT_NUMBER, DATE, PICKLIST, etc.), and available options. However, if you're just exploring data without filters/sorting/column selection, you can call get_sheet_summary directly - it returns available_columns for subsequent use.For best results: Apply filters and column selection to minimize data transfer and improve performance</instructions><limitations>- Must provide at least one of url or sheet_id (if both provided, they must match) - Data limited to ~8000 tokens (may return sampled rows for large sheets) - Filters use AND logic only - Column names are case-sensitive (use get_columns to get exact names) - Sorting falls back to Modified Date DESC or primary column ASC if not specified</limitations>
get_sheet_version
ChatGPT<summary>Get the current version number of a sheet without loading the entire sheet. Version increments on any modification (cell changes, comments, rows, attachments, formatting). Use this for lightweight change detection or to determine if sheet history needs refreshing.</summary><limitations>- Must provide at least one of url or sheet_id (if both provided, they must match) - Returns only a version number (no historical data or change details) - Cannot retrieve previous version numbers (only current version) - Version number is monotonically increasing integer (starts at 0)</limitations>
is_favorite
ChatGPT<summary>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.</summary><limitations>- Returns a 404 Not Found error if the asset is not marked as favorite by the user. - Only checks the current user's favorites - Requires both asset ID and type to perform the check - Valid asset types: workspace, folder, sheet, report, template, sight (dashboard) </limitations>
list_attachments
ChatGPT<summary>Retrieves a paginated list of all attachments on a specific sheet. Use this tool to discover files, links, and cloud storage integrations attached to sheets. Supports pagination to handle sheets with many attachments efficiently.</summary><limitations>- Returns only attachments the authenticated user has permission to view - Maximum 100 attachments per page (enforced pagination) - Page numbers are 1-based (page 1 is the first page) - Includes attachments at all levels: sheet, row, and discussion</limitations>
list_dashboards
ChatGPT<summary>Retrieves a list of all dashboards (Sights) that the user has access to with pagination support. Use this tool to discover available dashboards and navigate large sets of dashboards. Returns basic dashboard information including name, access level, creation and modification times.</summary><limitations>- Returns basic metadata only (not full dashboard content or widgets) - Token-based pagination required for large dashboard collections </limitations><instructions>Use last_key from previous response to fetch next page </instructions>
list_discussion_attachments
ChatGPT<summary>Lists all attachments on a specific discussion with pagination. Use this to discover files and links attached to discussion comments.</summary><limitations>- Returns paginated results (default 100 per page, max 100) - Requires exact discussion ID - Returns attachments from all comments in the discussion</limitations>
list_favorites
ChatGPT<summary>Retrieves a list of all items marked as favorites by the current user. Favorites can include sheets, reports, dashboards (sights), folders, workspaces, and templates. Use this tool to quickly discover and access frequently used resources.</summary><limitations>- Returns only items favorited by the current user - Maximum page size is 100 items per page - Pagination is always enforced (iterate through pages to retrieve all favorites) </limitations>
list_reports
ChatGPT<summary>List all reports accessible to the user. Returns basic report information including ID, name, access level, and permalink. Use this to discover available reports before retrieving detailed report data.</summary><limitations>- Only returns reports the user has access to - Maximum page size is 100 reports per page - Pagination is always enforced (iterate through pages to retrieve all reports) - Does not include detailed report content (use get_report to retrieve report data)</limitations>
list_row_attachments
ChatGPT<summary>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. Supports pagination to handle rows with many attachments efficiently.</summary><limitations>- Returns only attachments the authenticated user has permission to view - Maximum 100 attachments per page (enforced pagination) - Page numbers are 1-based (page 1 is the first page) - Only returns attachments directly attached to the specified row</limitations>
list_row_discussions
ChatGPT<summary>Retrieves discussions for ONE specific row in a Smartsheet. Use this when you need focused conversation analysis on a particular row without unrelated discussions.</summary><limitations>- Returns paginated results (default 100 per page, max 100) - Comments and attachments only included if explicitly requested - Only returns discussions for the specified row</limitations>
list_shares
ChatGPT<summary>List all users and groups with whom a Smartsheet asset is shared. Returns share details including access levels, user/group information, and share scope. Use this to discover collaborators, audit permissions, or understand access patterns.</summary><limitations>- Only retrieves shares for assets you have permission to view - Returns exactly 100 shares per page (use pagination for assets with more shares) - Supports: sheet, report, sight (dashboard), workspace, collection, file assets</limitations>
list_sheet_attachments
ChatGPT<summary>Retrieves a paginated list of all attachments on a specific sheet. Use this tool to discover files, links, and cloud storage integrations attached to sheets. Supports pagination to handle sheets with many attachments efficiently.</summary><limitations>- Returns only attachments the authenticated user has permission to view - Maximum 100 attachments per page (enforced pagination) - Page numbers are 1-based (page 1 is the first page) - Includes attachments at all levels: sheet, row, and discussion</limitations>
list_sheet_discussions
ChatGPT<summary>Retrieves all discussions from a Smartsheet (both sheet-level and row-level). Use this to understand all conversations across the entire sheet, review comments, or track collaboration history.</summary><limitations>- Returns paginated results (default 100 per page, max 100) - Comments and attachments only included if explicitly requested - Includes both sheet-level and row-level discussions</limitations>
list_workspaces
ChatGPT<summary>Retrieves a list of workspaces from Smartsheet with pagination support.</summary><instructions>Use last_key from previous response to fetch next page</instructions>
search
ChatGPT<summary>Search across all accessible Smartsheet assets (sheets, reports, dashboards, folders, workspaces) to discover and locate resources. Use this tool when you need to find assets by name or content, locate specific items, or discover resources without knowing exact URLs. Supports fuzzy matching and returns results with context.</summary><limitations>- Returns maximum 100 results (no pagination available) - Search is eventually consistent (new items may take a few minutes to appear) - First-time API users may experience 24-hour data provisioning delay - Scopes: attachments, cellData, comments, folderNames, reportNames, sheetNames, sightNames, summaryFields, templateNames, workspaceNames - If scopes not specified, searches all types</limitations><instructions>Use double-quotes for exact match searches (e.g., '"Q4 Budget 2024"') Use scopes parameter to narrow search Use modified_since to filter by modification date For best results: Use specific terms like 'Q4 Budget' rather than generic terms</instructions>
update_column
ChatGPT<warning>⚠️ DESTRUCTIVE OPERATION: This tool modifies column properties in Smartsheet. Changes are PERMANENT and CANNOT be automatically undone. Changing column types may result in data loss or conversion. Verify column ID and properties before executing.</warning><summary>Updates an existing column's properties in the specified sheet. Can modify column title, type, index (position), and other properties. </summary><instructions>- Always verify the correct column ID before updating - Be extremely cautious when changing column types (may cause data loss) - Understand the impact on all rows when modifying column properties - Consider dependencies like formulas, automations, and reports - Remember: There is no automatic undo for this operation</instructions><limitations>- You cannot change the type of a Primary column.</limitations>
update_comment
ChatGPT<summary>Updates the text of an existing comment. Use this to modify or correct a comment you created.</summary><limitations>- Can only update your own comments - Comment text required (minimum 1 character) - Cannot update comments in closed/locked discussions - Only the user that created the comment is permitted to update it.</limitations>
update_rows
ChatGPT<warning>⚠️ DESTRUCTIVE OPERATION: This tool modifies existing row data in Smartsheet. Updates are PERMANENT and CANNOT be automatically undone. Verify row IDs and cell values before executing.</warning><summary>Updates one or more rows in the specified sheet with partial success support. Can update cell values, properties, AND reposition rows in a single operation. 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.</summary><location_specifiers>Optionally move rows while updating (same rules as add_rows): Single Location Specifiers (use only one): - toTop: Move to the top of the sheet - toBottom: Move to the bottom - parentId: Move as FIRST child of parent row (indented) - siblingId: Move BELOW the specified row (same level) Valid Combinations: - parentId + toBottom: Move as LAST child of parent - siblingId + above: Move ABOVE the sibling Indent/Outdent (must be used alone): - indent: Number of levels to indent - outdent: Number of levels to outdent Invalid Combinations: - Cannot use parentId with siblingId - Cannot use siblingId with toTop or toBottom (except siblingId + above) - Cannot use indent/outdent with any location specifier</location_specifiers><instructions>- 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</instructions><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.</limitations>
Capabilities
Writes
