Smartsheet US

<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 the user can write to. Folder and 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, and (3) a short title. If the user has not specified a destination, ask which workspace 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 or workspace name to an id, use the `search` tool (or `list_workspaces` / `browse_workspace` 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>

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

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

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

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

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

<summary>Internal test harness for validating MCP client capabilities. Tests timeout behavior, SSE progress notifications, and connection resilience. Internal use only — not exposed to customers.</summary><instructions>Call with a duration and optional flags to test specific MCP behaviors. Defaults to a silent wait (worst-case timeout test). Enable send_progress to test SSE keepalive with notifications every 10s.</instructions>

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

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

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

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

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

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

<summary>Explain how a chart or metric 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/metric 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 an answer (chart or metric), not a question.</limitations>

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

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

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

<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_chart_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_chart_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_chart_to_dashboard response. - Does NOT work with conversation message IDs. - chart_id and version cannot be retrieved via get_dashboard.</limitations>

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

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

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

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

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

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

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

<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.**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.</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>

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

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

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

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

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

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

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

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

<summary>Retrieves a list of workspaces from Smartsheet with pagination support.</summary><instructions>Use last_key from previous response to fetch next page</instructions>

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

<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_chart_to_dashboard. - Do NOT call this after create_chart_from_prompt — that returns data inline. - Use the chartId and version returned directly by add_chart_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_chart_to_dashboard response. - Does NOT work with conversation message IDs. - chart_id and version cannot be retrieved via get_dashboard.</limitations>

<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 an answer (chart or metric), not a question.</limitations>

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

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