add_charts_to_dashboard
ChatGPT<summary>Add previously created charts to a Smartsheet dashboard as widgets in one request. Returns a dashboardPermalink and one result per chart, in the order supplied.</summary><instructions>- Pass every chart destined for the dashboard in one call, even when there is only one. - Never place charts on the same dashboard with several calls in parallel: each request positions its widget independently, so the widgets overlap. - Pass every chart in the charts list, each with the conversation_id, message_id, and messageType from the chart creation/refinement response. - At most 10 charts per call. For more, make consecutive calls and wait for each to finish before starting the next; never issue them concurrently. - Every messageType must be 'v2/ChartMessage'. Metric answers cannot be placed. - Inspect results: each entry is either SUCCEEDED or FAILED, so a successful call does not mean every chart was placed. Tell the user which charts landed and which did not. - Only retry entries whose reason is NOT_ATTEMPTED; those were never sent. Any other reason may already have created the widget, so retrying risks a duplicate. - Surface the returned dashboardPermalink as a 'View on dashboard' link. - You can use list_dashboards or get_dashboard to find available dashboards.</instructions><limitations>- The user must have edit access to the target dashboard. - The target dashboard must not be locked (managed by an agentic solution); locked dashboards reject this write. - All charts go to a single dashboard; use one call per dashboard. - Only charts created via the conversation flow can be placed (not manually defined ones). - Charts are added as new widgets; existing widgets are not moved. - Charts already placed by an earlier call are not removed when a later chart fails.</limitations>
add_columns
ChatGPT<summary>Adds one or more new columns to the specified sheet. Within-batch duplicate detection is handled automatically: if the same title appears more than once in the batch (case-insensitive), only the first occurrence is sent to the API and duplicates are reported in the 'skipped' field.</summary><instructions>- Before calling, use get_columns to check existing column names on the sheet and exclude any titles that already exist. - Do NOT include the same title more than once in a single batch.</instructions>
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_report_columns
ChatGPT<summary>Adds one or more columns to an existing Smartsheet report.</summary><instructions>To add columns to a report: 1. Provide the report_id of the report to update 2. Provide columns: list of column definitions to add Each column requires index (zero-based position), type, and either title (regular columns), systemColumnType (system columns), primary=true (primary column), or sheetNameColumn=true (sheet name column). Column matching rules: - Regular columns: matched by type + title - System columns: matched by type + systemColumnType - Primary column: set primary=true with type=TEXT_NUMBER - Sheet name column: set sheetNameColumn=true with type=TEXT_NUMBER All column index values must be unique.</instructions><limitations>Maximum 400 columns per call. Column indexes must be unique across the 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><constraints>Constraint: Every row in the rows array must specify the same positioning attribute or acceptable combination of attributes (toBottom, toTop, parentId, siblingId, or above). Split rows by location into separate calls if needed.</constraints><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>
add_shadow_sheet_rows
ChatGPT<summary>A scenario sheet is the scenario-specific copy of a source sheet used by Scenario Planning. Add one or more rows to a scenario sheet. Each row can specify where it should be inserted using location specifiers. Returns the newly created rows.</summary><instructions>- Before calling this tool, confirm via get_scenario_groups (include_scenarios=true) that the owning scenario's scenario_type is not baseline. If it is baseline, do not call this tool — tell the user the scenario sheet is read-only. - Use this tool to populate or extend a scenario sheet within a scenario. - Every row in the rows array must specify the same positioning attribute or an acceptable combination (toBottom, toTop, parentId, siblingId, or above). Split rows by location into separate calls if needed. - Call get_shadow_sheet first to confirm the sheet structure and column IDs. - Leave include_cell_data false (the default) unless you need to read back a value the API derived rather than one you sent. The response otherwise echoes a cell for every column in the sheet for every row added, which is data you already have. The new row IDs are returned either way. - Refer to this resource as a "scenario sheet"; do not use internal implementation terminology when responding to the user.</instructions><limitations>- Maximum 500 rows per call. - Does not support rows with image cells. - The sheet_id must identify a scenario sheet, not a regular sheet. - Obtain the sheet_id from the source_sheet_ids field of a scenario; call get_scenario_groups with include_scenarios=true to retrieve scenarios with their source_sheet_ids. - Baseline scenario sheets (scenario_type == baseline) are read-only and must not be edited.</limitations>
apply_scenario
ChatGPT<summary>Apply a scenario's diffs to its source sheets. The request is accepted asynchronously — a successful response means apply was accepted, not that source sheets have finished updating.</summary><instructions>- Always call get_scenario_diffs first and confirm summary.can_apply_all_sheets is true (no blocking conflicts) before applying. - Always call get_scenario_groups with include_scenarios=true to resolve the scenario taskId and confirm with the user which scenario to apply. - Do not apply a baseline scenario; choose a non-baseline scenario the user named. - Inform the user that apply runs asynchronously and source sheets update after acceptance. - Refer to the resource as a "scenario plan"; do not use internal implementation terminology when responding to the user.</instructions><limitations>- Might encounter an error if the scenario plan already has an applied scenario, or if any sheet has blocking conflicts; distinguish these by the error message text. Call get_scenario_diffs first to check for blocking conflicts. - User must have apply permission, editor access on source sheets, and an enterprise plan with the feature enabled.</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, templates) 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), templates - Templates will only be fetched if both 'sheets' and 'templates', at a minimum, are requested</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, templates) 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), templates - Templates will only be fetched if both 'sheets' and 'templates', at a minimum, are requested</limitations><instructions>Use asset_types parameter to filter by resource type Use last_key from previous response to fetch next page </instructions>
create_chart_from_data
ChatGPT<summary>Build a chart structure from pre-computed data values (bar, line, pie, or stacked bar). Returns a JSON chart definition that you must render yourself as an artifact or inline visualization.</summary><instructions>- Use this tool when you have already computed or extracted data values to visualize. - Provide labels (x-axis categories) and one or more datasets (y-axis values). - Each dataset has a 'data' array of numbers and an optional 'label' (series name). - The chart data is NOT automatically rendered visually — you MUST render the chart yourself as an artifact or inline visualization using the data from the tool's response (labels from result.labelInfo.labels, datasets from result.dataSetInfo.dataSets). Do not stop at merely stating that a chart was created. - Use create_chart_from_prompt instead when working from raw sheet data.</instructions><limitations>- Does not query any sheet data — you must provide pre-computed values. - Cannot be refined via refine_chart. - Cannot be added to a dashboard (no Slise conversation backing).</limitations>
create_chart_from_prompt
ChatGPT<summary>Generate charts from a natural language description by starting (or continuing) a conversation against a sheet's data. The answer can contain MULTIPLE messages — several charts together.</summary><instructions>- Provide a sheet_id as the data source. - Describe what you want to see in the prompt. - To start fresh, omit conversation_id; the response includes a conversation_id and message_id. - To continue an existing conversation, pass the conversation_id and the previous_message_id along with the new prompt. - Use get_chart_suggestions BEFORE this to surface charts to create. - The response's messages array carries each chart together with its definition and data (labels, datasets, chart type, axes). The chart data is NOT automatically rendered visually — you MUST render each chart yourself as an artifact or inline visualization using the data from the response (labels from messages[].result.labelInfo.labels, datasets from messages[].result.dataSetInfo.dataSets). Do not stop at merely stating that a chart was created. - After rendering the chart(s), call refine_chart and offer add_charts_to_dashboard. If the response contains multiple messages, ask the user which chart they want to refine or add to a dashboard first, then use that message's messageId when calling refine_chart or add_charts_to_dashboard.</instructions><limitations>- Only SHEET data sources are supported (not reports). - The AI interprets your prompt based on available columns. - Complex multi-axis charts may require refinement.</limitations>
create_dashboard
ChatGPT<summary>Creates a new Smartsheet dashboard whose widgets are generated by AI from one or more sheets. Use this when the user asks for a brand new dashboard built from existing sheet data — for example: "create a dashboard for my Q3 sales sheet" or "build me a project status dashboard from these sheets". The tool returns a permalink the user can open immediately.</summary><limitations>- Asset sources must be sheets only (asset_type = sheet). Reports and other asset types are not supported. - Destination must be a workspace or folder the user can write to. Home destinations are not supported. - The blank dashboard is rolled back automatically if any step fails, so callers never see an orphaned empty dashboard.</limitations><instructions>Before calling this tool: confirm with the user (1) the sheets to use as asset sources, (2) the destination workspace or folder, and (3) a short title. If the user has not specified a destination, ask which workspace or folder to put the dashboard in — do not guess. After a successful response, share the returned permalink (result.permalink) with the user. To resolve a sheet, workspace, or folder name to an id, use the search tool (or list_workspaces / browse_workspace / browse_folder for destinations). Do NOT call get_sheet_summary, get_columns, or any other read tool to inspect sheet contents before calling this tool — dash-serv reads the sheet data itself from the supplied asset_id, so fetching rows or columns first is wasted work.</instructions>
create_dashboard_with_ai
ChatGPT<summary>Creates a new Smartsheet dashboard whose widgets are generated by AI from one or more sheets. Use this when the user asks for a brand new dashboard built from existing sheet data — for example: "create a dashboard for my Q3 sales sheet" or "build me a project status dashboard from these sheets". The tool returns a permalink the user can open immediately.</summary><limitations>- Asset sources must be sheets only (asset_type = sheet). Reports and other asset types are not supported. - Destination must be a workspace or folder the user can write to. Home destinations are not supported. - The blank dashboard is rolled back automatically if any step fails, so callers never see an orphaned empty dashboard.</limitations><instructions>Before calling this tool: confirm with the user (1) the sheets to use as asset sources, (2) the destination workspace or folder, and (3) a short title. If the user has not specified a destination, ask which workspace or folder to put the dashboard in — do not guess. After a successful response, share the returned permalink (result.permalink) with the user. To resolve a sheet, workspace, or folder name to an id, use the search tool (or list_workspaces / browse_workspace / browse_folder for destinations). Do NOT call get_sheet_summary, get_columns, or any other read tool to inspect sheet contents before calling this tool — dash-serv reads the sheet data itself from the supplied asset_id, so fetching rows or columns first is wasted work.</instructions>
create_discussion
ChatGPT<summary>Creates a new discussion on a sheet or specific row. Use this to start a conversation at the sheet level or 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) - When target_type is ROW, row_id must be provided </limitations>
create_document
ChatGPT<summary>Creates a Smartsheet Page (a markdown document) in a workspace, optionally with its content. Use this to save written content such as a status update, plan, or notes to Smartsheet.</summary><instructions>- Pass content to write the page in the same call. The result then has the written version and omits the content - If the result is PARTIAL_SUCCESS, the page exists but its content wasn't written, and content_error says why: retry with create_document_version using the returned id</instructions><limitations>- Requires admin or owner access to the workspace - name is at most 255 characters and cannot contain control characters or any of < > : ; % \ / " - content is at most 200,000 characters, and long pages can be rejected as too large before that, especially non-Latin text or pages opened in the browser - Supports headings, bold, italic, strikethrough, inline code, links, bullet and numbered lists, quotes, and code blocks; tables, images, checklists, horizontal rules, and HTML are kept as plain text, and nested lists are flattened</limitations>
create_document_version
ChatGPT<summary>Replaces a Smartsheet Page's entire content with the given markdown and records the change as a new version.</summary><instructions>- To change part of a page, send the full revised markdown; anything left out is removed - There is no conflict detection: read the page with get_document immediately before writing, and don't reuse content read earlier in the conversation. Edits saved since your read are overwritten</instructions><limitations>- Requires the page's ID or link - Requires edit access to the page - content is at most 200,000 characters, and long pages can be rejected as too large before that, especially non-Latin text or pages opened in the browser - Supports headings, bold, italic, strikethrough, inline code, links, bullet and numbered lists, quotes, and code blocks; tables, images, checklists, horizontal rules, and HTML are kept as plain text, and nested lists are flattened</limitations>
create_folder
ChatGPT<summary>Creates a new folder in a workspace or within another folder. Use WORKSPACE to create top-level folders, or FOLDER to create nested folder hierarchies.</summary><limitations>- Requires valid parent_id (workspace_id or folder_id from browse/list/search operations) - Folder name is required (must be non-empty) - User must have ADMIN permissions on the parent workspace - Folder names must be unique within the parent - When parent_type is WORKSPACE, parent_id is the workspace ID - When parent_type is FOLDER, parent_id is the folder ID - Smartsheet supports deep folder nesting</limitations>
create_portfolio
ChatGPT<summary>Creates a new portfolio. A portfolio is a self-serve workspace for standardizing and managing projects at scale. It is created from a standard prototype that includes a project list sheet used to provision projects, portfolio-level dashboards, and reports. A default project template named 'Standard template' is automatically created.</summary>
create_project_template
ChatGPT<summary>Creates a new project template within a portfolio. A project template copies the structure of a source workspace at creation time. Each project provisioned from it inherits the same sheets, dashboards, reports, and other items. The source workspace is not modified.</summary><instructions>IMPORTANT: Always create project templates WITHOUT asset_source (leave it null/omit it) unless the user EXPLICITLY requests to create a project template from an existing workspace or folder. Only set asset_source when the user specifically provides a workspace ID or folder ID to use as a template.</instructions>
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 with title (display name) - 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_scenario
ChatGPT<summary>Add a new scenario to an existing scenario plan. Returns the created scenario.</summary><instructions>- Always call get_scenario_groups with include_scenarios=true first to look up the scenario plan by name and check its current scenario count. - If the plan already has 4 scenarios (including the baseline), inform the user that the limit has been reached and do not proceed. - If the plan is not found in the first page, follow last_key to subsequent pages before concluding it does not exist. - If multiple plans share the same name, present each one to the user with its workspace_name and id, and ask them to confirm which one to use. - Even if only one match is found, confirm with the user that this is the correct plan before proceeding. - scenario_group_id is the numeric database ID from the confirmed scenario plan. - The name should clearly describe what this scenario represents (e.g. 'Optimistic', 'Headcount Freeze'). - The response is returned immediately as a result envelope. Check message for the overall outcome: SUCCESS means the request was fully accepted; PARTIAL_SUCCESS means the request was accepted but result may be absent. - When result is present, check result.provisioning_status to determine readiness: COMPLETED means the scenario is ready to use; IN_PROGRESS or UPDATING means it is still being set up and should be ready within a minute — advise the user to refresh their scenario plan page to see it once complete; FAILED means setup did not succeed; UNKNOWN means the status could not be determined. - Refer to the parent resource as a "scenario plan"; do not use internal implementation terminology when responding to the user.</instructions><limitations>- Cannot create scenarios outside of an existing scenario plan; use create_scenario_group to create a new plan with a baseline scenario first. </limitations>
create_scenario_group
ChatGPT<summary>Create a new scenario plan in a Smartsheet workspace. Also creates a baseline scenario as a child. Returns a result envelope whose result field contains the created baseline scenario.</summary><instructions>- Use get_scenario_groups first to check whether a plan with the same name already exists. - workspace_id is required — the scenario plan is always created within a workspace. - source_sheet_ids are the numeric sheet IDs (integers) to associate with this scenario plan; use the id field from browse_workspace results. - Refer to this resource as a "scenario plan"; do not use internal implementation terminology when responding to the user.</instructions><limitations>- Always creates a baseline scenario as the first child; individual scenario creation is not supported by this tool.</limitations>
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>
create_workspace_assets
ChatGPT<summary>Creates one or more Smartsheet assets (sheets, dashboards, workflows, reports, forms, etc.) in a single call, either in a brand-new workspace or in an existing workspace when workspace_id is provided. Use this tool whenever the user is building a solution, project, or tracker that involves multiple assets — regardless of whether a new or existing workspace is the target. Not for creating a single standalone asset without a workspace.</summary><instructions>Pass the user's full request as the message. Pass workspace_id when the user wants to add assets to an existing workspace; omit it to create a new workspace. Prefer this tool for standing up a multi-asset solution that spans multiple asset types or operations — e.g. sheets plus automation/alerts/workflows; sheets with reports, dashboards, or forms; a tracker or project to stand up; or a work-management problem to solve. Do not chain individual CREATE tools for those cases. Use individual CREATE tools only when creating a single standalone asset with no workspace, or when modifying existing assets. This tool may run as a multi-turn loop. Inspect 'status' in the result: if 'needs_input', relay 'refinement_question' (question_text plus options) to the user and STOP; if 'plan_proposed', relay 'refinement_plan.plan_markdown' to the user, ask them to approve or adjust, and STOP; if 'awaiting_reply', relay 'reply_message' to the user and STOP; if 'completed', report the 'summary'. On the next turn, call this tool again with 'message' set to the user's reply/approval and 'session_id' set to the EXACT value returned in the previous result. Pass session_id back verbatim; never invent or fabricate one. A 'completed' result closes the session and carries no session_id: for any follow-up request, call this tool again without session_id. Make only one call per user turn during refinement.</instructions><limitations>Typically takes 1-2 minutes, but may take longer for complex solutions. Only a 'completed' result carries a 'summary'; 'needs_input', 'plan_proposed', and 'awaiting_reply' results do not. After this tool completes, if a needed asset is missing from the summary and an individual CREATE tool exists for it, call that tool as a fallback.</limitations>
debug_harness
ChatGPT<summary>Internal test harness for validating MCP client capabilities. Tests timeout behavior, SSE progress notifications, connection resilience, and the maximum tool response size a client delivers to the model. Internal use only, not exposed to customers.</summary><limitations>Internal testing only; not for customer use. response_size payloads reach ~3 MB per field at 1,000,000 tokens, and channel='both' sends a full copy in each field (~6 MB), so use 'content' or 'structured' alone to find a client's per-result limit. The last block is an intentionally partial JSON row. Exact sizes are in the END-OF-PAYLOAD line and server logs, not in the response.</limitations><instructions>mode='timeout' (default): call with a duration and optional flags. Defaults to a silent wait (worst-case timeout test). Enable send_progress to test SSE keepalive with notifications every 10s. mode='response_size': returns immediately with a payload of target_tokens (o200k_base) made of blocks numbered 1..N with no gaps, each carrying tok~ (running token count), ending in END-OF-PAYLOAD. channel picks the field: 'content', 'structured' (structuredContent), or 'both'. Blocks are tagged C-<nonce> in content and S-<nonce> in structuredContent. After calling, do not call more tools. For each distinct tag you can see (C-... and S-... separately), report: the tag; the number of blocks you can see; the first and last visible block numbers; the first missing block number, or every gap in the numbering; the last tok~ value you can see; whether END-OF-PAYLOAD is visible and, if so, its blocks= and tok~ values; and any truncation, file, or error notice verbatim.</instructions>
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_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_portfolio
ChatGPT<warnings>DESTRUCTIVE OPERATION - CANNOT BE UNDONE Deleting a portfolio: - Deletes the portfolio workspace and all its contents - Deletes all project templates in the portfolio - Deletes all projects provisioned from those project templates - All data in portfolio/project template/project workspaces is permanently lost MANDATORY CONFIRMATION REQUIRED</warnings><summary>Permanently deletes a portfolio by its ID, including all project template workspaces, project workspaces, and all assets within those workspaces.</summary><limitations>- Only a portfolio owner can delete a portfolio</limitations>
delete_project_template
ChatGPT<warnings>DESTRUCTIVE OPERATION - CANNOT BE UNDONE Deleting a project template: - Deletes the project template workspace and all its contents - All data in the project template workspace is permanently lost MANDATORY CONFIRMATION REQUIRED</warnings><summary>Permanently deletes a project template by its ID, including all assets within it.</summary><limitations>- Cannot delete a project template that has active projects - All active projects must be removed before deletion</limitations>
delete_report
ChatGPT<summary>Permanently deletes a Smartsheet report by ID. This action cannot be undone.</summary><instructions>Confirm the report_id before calling this tool — deletion is permanent and irreversible. Use list_reports or get_report to verify the correct report before deleting.</instructions><limitations>- Deletion is permanent and cannot be undone - Requires admin or owner access on the report - Program (portfolio) reports cannot be deleted via API</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>
delete_scenario_group
ChatGPT<summary>Permanently delete a scenario plan and all of its scenarios. This cannot be undone.</summary><instructions>- Always call get_scenario_groups with include_scenarios=true first to look up the scenario plan by name and confirm with the user before deleting. - If the plan is not found in the first page, follow last_key to subsequent pages before concluding it does not exist. - If multiple plans share the same name, present each one to the user with its workspace_name and id, and ask them to confirm which one to delete. - Even if only one match is found, confirm with the user that this is the correct plan before proceeding. - Refer to this resource as a "scenario plan"; do not use internal implementation terminology when responding to the user.</instructions><limitations>- User must have delete permission on the plan and an enterprise plan with the feature enabled.</limitations>
delete_shadow_sheet_rows
ChatGPT<summary>A scenario sheet is the scenario-specific copy of a source sheet used by Scenario Planning. Delete one or more rows from a scenario sheet by row ID. The response contains the IDs of all deleted rows, including child rows of any specified parent rows.</summary><instructions>- Before calling this tool, confirm via get_scenario_groups (include_scenarios=true) that the owning scenario's scenario_type is not baseline. If it is baseline, do not call this tool — tell the user the scenario sheet is read-only. - Use this tool to remove rows from a scenario sheet within a scenario. - Call get_shadow_sheet first to retrieve rows and their IDs before deleting. - Deleting a parent row also deletes all its child rows; the response lists every deleted row ID including children. - Refer to this resource as a "scenario sheet"; do not use internal implementation terminology when responding to the user.</instructions><limitations>- Deletion is permanent within the scenario and cannot be automatically undone. - The sheet_id must identify a scenario sheet, not a regular sheet. - Obtain the sheet_id from the source_sheet_ids field of a scenario; call get_scenario_groups with include_scenarios=true to retrieve scenarios with their source_sheet_ids. - Baseline scenario sheets (scenario_type == baseline) are read-only and must not be edited.</limitations>
delete_workflow
ChatGPT<summary>Permanently deletes a Smartsheet workflow by its ID</summary><limitations>- The caller must have permission to the workflow's sheet - WARNING: deletion is permanent and cannot be undone — the workflow cannot be re-enabled after it is deleted - To only turn a workflow off temporarily, use disable_workflow instead</limitations><instructions>- Provide the workflow_id as shown in Smartsheet - Confirm the workflow_id is correct and that permanent deletion is intended before calling</instructions>
disable_workflow
ChatGPT<summary>Disables a Smartsheet workflow by its ID</summary><limitations>- The caller must have permission to the workflow's sheet - Disabling turns the workflow off; it can be re-enabled later with enable_workflow - A disable through this tool is recorded as a user action (status DISABLED_BY_USER): no invalidation reason is stored and no admin notification is sent</limitations><instructions>- Provide the workflow_id as shown in Smartsheet - Confirm the workflow_id is correct before disabling - The response includes the workflow's post-action version; pass it as expected_version to update_workflow for a conflict-safe follow-up edit</instructions>
enable_workflow
ChatGPT<summary>Enables a Smartsheet workflow by its ID</summary><limitations>- The caller must have permission to the workflow's sheet - Enabling an already-enabled workflow is idempotent - Events that occurred while the workflow was disabled are NOT processed retroactively - only new events trigger it after enabling</limitations><instructions>- Provide the workflow_id as shown in Smartsheet - Confirm the workflow_id is correct before enabling - The response includes the workflow's post-action version; pass it as expected_version to update_workflow for a conflict-safe follow-up edit</instructions>
execute_ai_solutions_write
ChatGPTCreate comprehensive end-to-end Smartsheet solutions from natural language using AI (workspaces, sheets, dashboards, workflows/automations, reports, forms, and related assets as needed). Prefer this path — via search_tools then this executor — when the user wants a new multi-asset or multi-operation solution from scratch (for example sheets plus automation, or sheets with reports and/or dashboards and/or forms), or describes a work-management problem to solve by standing up a new solution. Do NOT assemble those new solutions by chaining individual CREATE tools. Use individual CREATE tools when adding to or modifying existing assets, or for a simple one-off structural create. Do NOT call this tool until you have called search_tools(toolset="ai_solutions", access_type="write") first to discover available tools and their schemas, then pass the tool name and arguments here. Write operations may modify or delete data.
execute_automations_read
ChatGPTQuery Smartsheet automations and scheduled AI tasks. List rule-based workflows, including each workflow's full trigger/action tree, and list the current user's scheduled AI tasks (list_scheduled_ai_tasks). Do NOT call this tool until you have called search_tools(toolset="automations", access_type="read") first to discover available tools and their schemas, then pass the tool name and arguments here.
execute_automations_write
ChatGPTManage configured Smartsheet automations. Create, enable, disable, and delete workflows on sheets. Do NOT call this tool until you have called search_tools(toolset="automations", access_type="write") first to discover available tools and their schemas, then pass the tool name and arguments here. Write operations may modify or delete data.
execute_discussions_read
ChatGPTQuery discussions on a sheet or row, and retrieve a single discussion's full details. Do NOT call this tool until you have called search_tools(toolset="discussions", access_type="read") first to discover available tools and their schemas, then pass the tool name and arguments here.
execute_portfolio_read
ChatGPTQuery portfolios, project templates, and projects — list, inspect, and retrieve details. Do NOT call this tool until you have called search_tools(toolset="portfolio", access_type="read") first to discover available tools and their schemas, then pass the tool name and arguments here.
execute_portfolio_write
ChatGPTCreate and delete portfolios, project templates, and projects. Do NOT call this tool until you have called search_tools(toolset="portfolio", access_type="write") first to discover available tools and their schemas, then pass the tool name and arguments here. Write operations may modify or delete data.
execute_scenario_planning_read
ChatGPTQuery scenario plans, scenario diffs, capacity/workload, and scenario sheets — list, inspect, and retrieve details including individual rows. Do NOT call this tool until you have called search_tools(toolset="scenario_planning", access_type="read") first to discover available tools and their schemas, then pass the tool name and arguments here.
execute_scenario_planning_write
ChatGPTCreate and delete scenario plans, create scenarios, apply scenario diffs to source sheets, and add, update, or delete rows in scenario sheets. Do NOT call this tool until you have called search_tools(toolset="scenario_planning", access_type="write") first to discover available tools and their schemas, then pass the tool name and arguments here. Write operations may modify or delete data.
execute_sharing_read
ChatGPTQuery asset shares and the current user's favorites list, and check favorite status. Do NOT call this tool until you have called search_tools(toolset="sharing", access_type="read") first to discover available tools and their schemas, then pass the tool name and arguments here.
execute_sharing_write
ChatGPTAdd and remove items from the current user's favorites. Do NOT call this tool until you have called search_tools(toolset="sharing", access_type="write") first to discover available tools and their schemas, then pass the tool name and arguments here. Write operations may modify or delete data.
execute_users_read
ChatGPTQuery the current user's plan memberships, and a plan's license inventory, seat requests, and per-user seat usage. Do NOT call this tool until you have called search_tools(toolset="users", access_type="read") first to discover available tools and their schemas, then pass the tool name and arguments here.
explain_chart
ChatGPT<summary>Explain how a chart answer in a conversation was produced — a plain-language summary plus the step-by-step reasoning. Returns explanation text only; does NOT change the chart.</summary><instructions>- Use the conversation_id and message_id of the chart answer. - Optionally pass chart_id and chart_version for a chart already saved to a dashboard. - The response has a summary and steps.</instructions><limitations>- Requires an active conversation from create_chart_from_prompt. - The message must be a chart answer, not a question.</limitations>
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_chart_definition
ChatGPT<summary>Retrieve a saved chart-definition including its type, axes, styling, and configuration. This is only for charts already saved to a dashboard.</summary><instructions>- This tool is ONLY for charts saved via add_charts_to_dashboard. - Do NOT call this after create_chart_from_prompt — that returns chart data inline. - Use the chartId and version returned directly by add_charts_to_dashboard. - Do NOT call get_dashboard to retrieve chart_id or version — chart widgets do not expose these fields through the public dashboard API.</instructions><limitations>- Requires chart_id and version from the add_charts_to_dashboard response. - Does NOT work with conversation message IDs. - chart_id and version cannot be retrieved via get_dashboard.</limitations>
get_chart_suggestions
ChatGPT<summary>Get AI-powered chart suggestions for a Smartsheet sheet. Returns categories of suggestions, each with presentations (chart type options with prompts).</summary><instructions>- Provide the sheet_id of the sheet you want chart suggestions for. - Optionally narrow suggestions to specific columns by passing column IDs. - To create a chart from an option, call create_chart_from_prompt with that presentation's prompt.</instructions><limitations>- Only supports sheets (not reports or dashboards) as data sources. - Suggestions are AI-generated and may not always be optimal for the data.</limitations>
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_document
ChatGPT<summary>Retrieves a Smartsheet Page (a markdown document in a workspace) with its metadata and full current content as markdown.</summary><instructions>- Use the id returned by create_document, or pass a page link the user provides as url - Read the page before editing it: create_document_version replaces the whole content</instructions><limitations>- Requires the page's ID or link (no search by name) - Requires view access to the page - Pages containing a horizontal rule can't be read yet</limitations>
get_portfolio
ChatGPT<summary>Retrieves a specific portfolio by its ID, including name, workspace ID, status, and permalink.</summary><limitations>- Requires a valid portfolio ID</limitations>
get_portfolio_project_list_sheet
ChatGPT<summary>Retrieves the project list sheet associated with a portfolio. The project list sheet is the centralized project list used to provision new projects. Returns the sheet ID and permalink. Use the sheet ID with row tools to add or update rows.</summary><instructions>The project list sheet is the control panel for provisioning projects from project templates. There is no create_project tool — this sheet is the only way to provision a project. Provisioning triggers when the Workspace Status column reaches 'Active', by either route: - Add a row with Project Name, Project Template (must match a template name), and Workspace Status='Active'. - Update an existing row's Workspace Status to 'Active'. The Workspace Status cell MUST be set in the same write. A row added or updated without it provisions nothing, reports no error, and returns success — so treat a successful row write as 'submitted', never as 'provisioned'.</instructions><limitations>- Requires a valid portfolio ID - The portfolio must be fully provisioned before the project list sheet is available - Maximum of 100 projects can be provisioned per operation - Provisioning is asynchronous; projects do not exist immediately after the row write - There is no provisioning-status signal for a project. Confirm by polling list_projects or get_project until workspaceId is non-null. A project that never provisions is indistinguishable from one still in progress, so bound polling with a timeout</limitations>
get_project
ChatGPT<summary>Retrieves a specific project by its ID, including name, workspace ID, and permalink.</summary><limitations>- Requires a valid project ID</limitations>
get_project_template
ChatGPT<summary>Retrieves a specific project template by its ID, including workspace_id, name, permalink, and portfolio summary. The workspace_id can be used to customize the template workspace (add sheets, dashboards, etc.) before provisioning projects.</summary><limitations>- Requires a valid project template ID</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_scenario_capacity_workload
ChatGPT<summary>Return capacity (available hours) and workload (assigned hours) for a scenario over a date range.</summary><instructions>- Always call get_scenario_groups with include_scenarios=true first to resolve the scenario taskId (scenario_id) from the scenario plan the user named. - Use filters whenever the user names specific people, disciplines, roles, or locations — do not fetch the full unfiltered matrix if a narrower answer will do. - When filters are applied, ignore workload groups with 0/0 hours as filtered out (not idle capacity). - Utilization is workload_hours / total_hours; placeholder users do not have capacities. - instant_type month allows at most a 6-month range; week allows at most 26 weeks.</instructions><limitations>- Date-range and filters values are validated downstream and might return errors with a descriptive message.</limitations>
get_scenario_diffs
ChatGPT<summary>Compute and return all cell, row, and column diffs between a scenario and its source sheets, including conflicts and an aggregate apply-eligibility summary. Use before apply_scenario to explain what would change and whether apply is blocked.</summary><instructions>- Always call get_scenario_groups with include_scenarios=true first to resolve the scenario taskId (scenario_id) from the scenario plan the user named. - Prefer checking summary.can_apply_all_sheets and per-sheet apply_blocked / blocking_conflicts before recommending apply_scenario. - Use the counts in the sheet_summary field for a high-level overview; drill into cell_diffs, column_diffs, and row/column add-delete lists when the user needs specific change details.</instructions><limitations>- Diffs for baseline scenarios can be retrieved, but they cannot be applied. - Missing scenarios will be indicated by a not found error.</limitations>
get_scenario_group
ChatGPT<summary>Returns a single scenario plan by ID from the Resource Management (RM) service. Use when the scenario plan ID is already known to fetch the plan, its child scenarios, and optionally the latest metrics for a time window.</summary><instructions>Always prefer this tool over get_scenario_groups when the scenario plan ID is already known. Use this tool when fetching the latest metrics for a scenario plan (optionally pass start_date with end_date for a custom metrics window). include_scenarios defaults to true so child scenarios are embedded. When using a custom metrics window, both start_date and end_date are required (YYYY-MM-DD). When returning results to the user, always say "scenario plan" instead of "scenario group".</instructions><limitations>Applicable only when the scenario plan ID is known. Obtain the ID from get_scenario_groups or from the create_scenario_group response. Without an ID, resolve it via get_scenario_groups first. Child scenarios are only returned when include_scenarios is true.</limitations>
get_scenario_groups
ChatGPT<summary>Returns a paginated list of scenario plans from the Resource Management (RM) service. Use to retrieve scenario plans, either to discover all accessible ones or to limit to a specific workspace.</summary><instructions>Do not execute this tool until the user has specified either a workspace name or ID, or has confirmed they want scenario plans across their entire organization. Feel free to ask them follow up questions to clarify their intent. If they provide a workspace name, call list_workspaces to find the matching workspace_id, then call this tool with that workspace_id. If they provide an ID, use it directly. If they want all scenario plans, call without workspace_id. Set include_scenarios to true to embed child scenarios in the response (default false). Each scenario includes source_sheet_ids for use with other Smartsheet tools, and scenario_type to identify the baseline scenario — baseline scenario sheets must not be edited. Results are returned in the data array. Use last_key from the previous response to fetch the next page. Refer to this resource as a "scenario plan"; do not use internal implementation terminology when responding to the user.</instructions><limitations>Child scenarios are only returned when include_scenarios is true. Results are paginated.</limitations>
get_shadow_sheet
ChatGPT<summary>A scenario sheet is the scenario-specific copy of a source sheet used by Scenario Planning. Returns the sheet structure including columns. The response never includes permalink or workspace fields.</summary><instructions>- Use this tool to read the current state of a scenario sheet within a scenario. - To add, update, or delete rows, use add_shadow_sheet_rows, update_shadow_sheet_rows, or delete_shadow_sheet_rows respectively. - Before recommending any of those write tools, confirm via get_scenario_groups (include_scenarios=true) that the owning scenario's scenario_type is not baseline — baseline scenario sheets must not be edited. - Refer to this resource as a "scenario sheet"; do not use internal implementation terminology when responding to the user.</instructions><limitations>- permalink and workspace are always absent from the response. - The sheet_id must identify a scenario sheet, not a regular sheet. - Obtain the sheet_id from the source_sheet_ids field of a scenario; call get_scenario_groups with include_scenarios=true to retrieve scenarios with their source_sheet_ids. - Rows are returned by default; use exclude to omit specific cell fields and reduce payload size.</limitations>
get_shadow_sheet_row
ChatGPT<summary>A scenario sheet is the scenario-specific copy of a source sheet used by Scenario Planning. Retrieve a single row from a scenario sheet by its row ID in a Scenario Planning scenario. Returns the full row data including cell values.</summary><instructions>- Use this tool to inspect an individual row in a scenario sheet. - Obtain row_id from the rows returned by get_shadow_sheet. - Refer to this resource as a "scenario sheet"; do not use internal implementation terminology when responding to the user.</instructions><limitations>- The sheet_id must identify a scenario sheet, not a regular sheet. - Only one row is returned per call. - Obtain the sheet_id from the source_sheet_ids field of a scenario; call get_scenario_groups with include_scenarios=true to retrieve scenarios with their source_sheet_ids.</limitations>
get_sheet_aggregates
ChatGPT<summary>Computes exact grouped counts (group_by), numeric statistics (summary_stats), and date-range overlap verdicts (overlap_group_by/overlap_start_column/overlap_end_column) over a sheet's rows — median, mean, min, max, high/low outliers, top-3 value concentration, and who has double-booked/concurrent/conflicting date ranges. Use this instead of get_sheet_summary whenever a question needs counting, totals, medians, outlier detection, or overlap detection: 'how many tasks per person', 'any budget anomalies', 'top 3 by value', 'which owners have overlapping engagements'. Do NOT use group_by alone for an overlap question — group_by only counts rows per value, it does not compare date ranges, so it cannot tell 'has many engagements' apart from 'has engagements that conflict in time'. IMPORTANT: Call get_columns FIRST to get exact case-sensitive column names.</summary><instructions>Column names for group_by/summary_stats/overlap_ are CASE-SENSITIVE — call get_columns first to get exact names, or you will receive validation errors. Never tally rows, estimate a median, classify outliers, or compare date ranges by hand — this tool returns exact, server-computed results, including exactly which rows overlap. Aggregates are returned only when the aggregated row set is not sampled (metadata.is_sampled=false) and the exact aggregates fit within the token budget; otherwise metadata.aggregates_omitted is set to true rather than returning a partial result.</instructions><limitations>- Must provide at least one of url or sheet_id (if both provided, they must match) - Must provide at least one of group_by, summary_stats, or the overlap_ trio - overlap_group_by, overlap_start_column, and overlap_end_column must be provided together or not at all - overlap_start_column and overlap_end_column must be DATE-type columns (use get_columns to check column types); a non-date column raises a validation error rather than silently returning no overlaps - A row missing overlap_start_column or overlap_end_column, or with an end date before its start date, is excluded from overlap comparison entirely — never counted as non-overlapping - A row with a blank overlap_group_by value is excluded from overlap comparison entirely — unlike group_by, which reports blank cells as their own '(blank)' group, date_overlap has no group for them at all, so their absence means 'not examined', not 'no conflicts' - Aggregates cover at most 1000 matching rows per request (Grid Service limit); larger matching sets are reported as sampled rather than aggregated - Multiple filters are AND-combined by default; set filter_join_operator to OR to match any condition - Column names are case-sensitive (use get_columns to get exact names)</limitations>
get_sheet_path
ChatGPT<summary>Get the full hierarchical path of a sheet within the Smartsheet workspace hierarchy, including the UNIX-style path and direct permalink, without loading the sheet itself. Use this to determine where a sheet lives or to obtain a shareable link.</summary><limitations>- Must provide at least one of url or sheet_id (if both provided, they must match) - Requires workspace-level access to the sheet; otherwise the API returns a 404 - Path reflects the folder structure up to the sheet but does not include sheet content</limitations>
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. In order to fetch data about share status or ownership use list_shares. For distribution questions ('how many per person', 'breakdown by status'), numeric statistics ('any budget outliers', 'concentration risk'), or date-range overlap questions ('who is double-booked', 'which owners have overlapping engagements'), use get_sheet_aggregates instead of comparing date ranges by hand. Row-level questions — including which rows are missing a value — are answered by scanning this tool's rows, or more precisely with an IS_BLANK/IS_NOT_BLANK filter on the column. 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. Use the sheet's permalink directly when the user asks for a link to a sheet. Formula columns: columns with has_column_formula=true in available_columns are automated — their values are computed by a formula, so empty cells are expected and correct. Do NOT flag these columns as missing data.</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) - Multiple filters are AND-combined by default; set filter_join_operator to OR to match any condition - IS_BLANK/IS_NOT_BLANK do not apply to boolean columns (CHECKBOX, FLAG, STAR): those always hold an explicit true/false, so IS_BLANK returns no rows and IS_NOT_BLANK returns all rows - 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 - Predecessor cells render like the UI (3FS, 5FS +2d); ? = deleted target, ! = invalid edge. predecessor_index maps those row numbers to row_ids</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><instructions>When the user asks for a link to a sheet, use the permalink from the response.</instructions><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>
get_task_status
ChatGPT<summary>Gets the status of a task returned by another tool.</summary><instructions>Waits until the task finishes or a short time passes. If status is 'working', call again with the same taskId. Report results only when status is 'completed'.</instructions>
get_workflows
ChatGPT<summary>Lists the workflows on a sheet, including each workflow's full trigger/action tree, with pagination support</summary><limitations>- The caller must have permission to the target sheet - Reminder-type workflows are not returned - Results are ordered ascending by workflow id; use last_key (not the array length) to detect further pages - A page can contain fewer than max_items items even when more pages exist (workflows with unresolvable legacy references are omitted); rely on last_key only</limitations><instructions>- Provide the sheet_id as shown in Smartsheet - Returned workflow id values are STRINGS — pass them unchanged to enable_workflow, disable_workflow, or delete_workflow - Each item's root_node is the same public by-names tree create_workflow accepts (UPPER_SNAKE type discriminants, columns by title, people by email) — read it to understand or replicate an existing workflow - Iterate pages by passing the returned last_key as the next call's last_key; workflow trees can be large, so prefer a small max_items when you only need a few</instructions>
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 attachments from a Smartsheet. Use SHEET to get all attachments (sheet, row, and discussion-level), ROW to get attachments for a specific row, or DISCUSSION to get attachments from a specific discussion.</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) - When target_type is ROW or DISCUSSION, target_id must be provided </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_discussions
ChatGPT<summary>Retrieves discussions from a Smartsheet. Use SHEET to get all discussions (sheet-level and row-level), or ROW to get discussions for one specific row only.</summary><limitations>- Returns paginated results (default 100 per page, max 100) - Comments and attachments only included if explicitly requested - When target_type is ROW, row_id must be provided </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_portfolios
ChatGPT<summary>Retrieves a paginated list of portfolios accessible to the current user, including name, workspace ID, and permalink. Portfolios contain project templates and projects. Use this tool to discover available portfolios.</summary><limitations>- Returns basic portfolio metadata only, not full portfolio contents - Token-based pagination required for large portfolio collections</limitations><instructions>PORTFOLIO HIERARCHY: Portfolio → Project Templates →(creates) Projects - To see project templates in a portfolio: Use list_project_templates with the portfolio ID - To see projects: First get project templates, then use list_projects for each project template This tool is the STARTING POINT when user asks to list projects or project templates but hasn't specified which portfolio. Show available portfolios and ask user to select one. Use last_key from the previous response to fetch the next page.</instructions>
list_project_templates
ChatGPT<summary>Retrieves a list of project templates associated with a portfolio, including name and permalink. Each project template lives in its own workspace. Projects are created from project templates.</summary><limitations>- Requires a valid portfolio ID - Pagination parameters are accepted but currently ignored by the backend; all project templates are returned in a single response</limitations>
list_projects
ChatGPT<summary>Retrieves a paginated list of projects associated with a specific project template, including name and permalink. Projects are created from project templates inside a portfolio.</summary><limitations>- Requires a valid project template ID - Token-based pagination required for large project collections - This API lists projects for ONE project template at a time</limitations><instructions>PORTFOLIO HIERARCHY: Portfolio → Project Templates →(creates) Projects Use last_key from the previous response to fetch the next page.</instructions>
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_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 get information on who owns the asset based on the access levels, 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_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>
plan_change
ChatGPT<summary>Pre-flight analysis tool — call this before any write operation: updating rows, deleting rows or columns, or changing column schema. Returns scope analysis, practitioner-grade guidance including a staging pattern recommendation, sheet-specific cautions, and preflight questions. Idempotent — no state is changed.</summary><instructions>Call plan_change before: deleting rows or columns, updating more than one row, adding columns, or any column schema change. Present guidance.what_i_think_first first. Then surface guidance.what_you_should_know (CRITICAL before WARNING). Then guidance.worth_thinking_through. Then guidance.how_id_run_this with its prompt_template. Do not execute the write until the user explicitly confirms.</instructions><limitations>Does not execute writes. Does not block or prevent writes — it only informs. Cross-sheet reference detection is best-effort and may be incomplete for large sheets.</limitations>
query_chart
ChatGPT<summary>Query a saved chart-definition's data for visualization. Returns chart definition, data points, and styling for rendering.</summary><instructions>- This tool is ONLY for charts saved to a dashboard via add_charts_to_dashboard. - Do NOT call this after create_chart_from_prompt — that returns data inline. - Use the chartId and version returned directly by add_charts_to_dashboard. - Do NOT call get_dashboard to retrieve chart_id or version — chart widgets do not expose these fields through the public dashboard API.</instructions><limitations>- Requires chart_id and version from the add_charts_to_dashboard response. - Does NOT work with conversation message IDs. - chart_id and version cannot be retrieved via get_dashboard.</limitations>
refine_chart
ChatGPT<summary>Get suggested follow-up refinements for an existing chart in a conversation. Returns refinements with title, prompt, chartType, and type. Does NOT itself change the chart.</summary><instructions>- Use the conversation_id and message_id of the chart answer from create_chart_from_prompt. - To apply a refinement, call create_chart_from_prompt with the same conversation_id, the previous message_id, and the refinement's prompt.</instructions><limitations>- Requires an active conversation from create_chart_from_prompt. - Returns suggestions only; applying one requires a follow-up call. - The message must be a chart answer, not a question.</limitations>
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 - Do NOT use this for figurative/jargon terms in the user's question (e.g. 'watermelon', 'stale', 'zombie', 'at-risk', 'near-duplicate') unless the user names a specific known asset — these describe a data pattern to detect via get_sheet_summary/get_sheet_aggregates, not literal cell text; searching the term itself won't match even when the pattern is present.</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>
search_tools
ChatGPT<summary>Discover available tools by toolset and access type. Returns tool definitions (name, description, schema) for a specific toolset.</summary><instructions>- Use the toolset parameter to select a tool domain - Optionally filter by access_type ('read' or 'write') - The response includes an 'executors' object with the executor tool names to use for running the discovered tools - 'executors.read' is present when read-only tools are returned — use it for read operations - 'executors.write' is present when write tools are returned — use it for mutations - IMPORTANT: Tools returned by search_tools MUST be invoked via the executor tools (e.g. execute_portfolio_read, execute_portfolio_write). Do NOT call them directly via tools/call — they are only accessible through their executors. - Pass the tool name and arguments to the appropriate executor to run a discovered tool</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>- Before renaming a column, use get_columns to check existing column names on the sheet and ensure the new title does not already exist (case-insensitive). - 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_report_definition
ChatGPT<summary>Updates the definition of an existing Smartsheet report. The definition controls filters, grouping, sorting, and summarizing criteria.</summary><instructions>To update a report definition: 1. Provide the report_id of the report to update 2. Provide definition with any combination of filters, grouping_criteria, sorting_criteria, and summarizing_criteria This is a full replacement — the entire definition is replaced with what you provide. Omitting a field clears it. To preserve existing criteria, include them in the request. Column identifiers in criteria always require type. Additionally: title (regular columns), system_column_type (system columns), primary=true (primary column), or sheet_name_column=true (sheet name column).</instructions><limitations>Program (portfolio) reports cannot be modified via API. Column references must match columns that exist in the report scope.</limitations>
update_report_scope
ChatGPT<summary>Adds and/or removes source sheets or workspaces from an existing Smartsheet report. At least one of add or remove must be provided.</summary><instructions>To modify report scope: 1. Provide the report_id of the report to update 2. Provide add: list of sheets/workspaces to add (optional) 3. Provide remove: list of sheets/workspaces to remove (optional) Both add and remove can be provided in a single call. Add operations are performed before remove operations. Each item requires asset_type ('sheet' or 'workspace') and asset_id. Check add_result and remove_result in the response to verify each operation succeeded.</instructions><limitations>At least one of add or remove must be non-empty. Each of add and remove is limited to 100 items per call. Removing a sheet not in scope will return an error from the API.</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>
update_shadow_sheet_rows
ChatGPT<summary>A scenario sheet is the scenario-specific copy of a source sheet used by Scenario Planning. Update one or more rows in a scenario sheet. Each UpdateRow must include the row ID to identify which row to modify. Returns the updated rows.</summary><instructions>- Before calling this tool, confirm via get_scenario_groups (include_scenarios=true) that the owning scenario's scenario_type is not baseline. If it is baseline, do not call this tool — tell the user the scenario sheet is read-only. - Use this tool to modify existing row data in a scenario sheet within a scenario. - Each row in the rows array must include an id field identifying the row to update. - Only include fields you want to change — unspecified fields are left unchanged. - Leave include_cell_data false (the default) unless you need to read back a value the API derived rather than one you sent. The response otherwise echoes a cell for every column in the sheet for every row written, which is data you already have. - Call get_shadow_sheet first to retrieve the sheet's rows and their IDs, then call get_shadow_sheet_row to confirm current values before updating. - Refer to this resource as a "scenario sheet"; do not use internal implementation terminology when responding to the user.</instructions><limitations>- Maximum 500 rows per call. - Updates are permanent within the scenario and cannot be automatically undone. - The sheet_id must identify a scenario sheet, not a regular sheet. - Obtain the sheet_id from the source_sheet_ids field of a scenario; call get_scenario_groups with include_scenarios=true to retrieve scenarios with their source_sheet_ids. - Baseline scenario sheets (scenario_type == baseline) are read-only and must not be edited.</limitations>
update_workflow
ChatGPT<summary>Updates a Smartsheet workflow by ID - a FULL REPLACEMENT of its definition using human-readable names</summary><limitations>- This is a full replace, not a patch: the workflow becomes exactly what is sent; anything omitted from root_node is removed - sheet_id must be the workflow's CURRENT sheet - workflows cannot be moved to another sheet - Updating a workflow invalidates its in-flight approval actions (pending approval emails stop being actionable) - The caller must have permission to edit the workflow's sheet - Same tree rules as create_workflow: condition nodes carry 1 to 20 conditions AND a childNode; IF_ELSE nodes need at least one condition branch; ELSE nodes need a childNode - violations are rejected here with the offending path before anything is sent</limitations><instructions>- Read the current definition first (get_workflows), modify it, and send the COMPLETE tree back - never send a partial tree - frequency has no default here: always pass the workflow's current frequency unless deliberately changing it - Omit enabled to keep the workflow's current enabled/disabled state; pass it only to deliberately change that state - Pass expected_version (the version from a previous update_workflow, enable_workflow, or disable_workflow response) to fail safely with 409 if someone else edited the workflow in between; on 409, re-read the workflow and retry with the fresh definition - Reference columns by TITLE and people by EMAIL, exactly as in create_workflow; all type discriminants are UPPER_SNAKE_CASE - Do not include node id fields in root_node - the tree schema (and the backend) rejects them; node identity is regenerated on every edit</instructions>