Smartsheet US

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

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

<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

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

debug_harness

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

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

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

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

explain_chart

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

find_in_sheet

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

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

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

get_chart_definition

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

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

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

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

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

<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 - Filters use AND logic only - Column names are case-sensitive (use get_columns to get exact names)</limitations>

get_sheet_aggregates

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

<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) - Filters use AND logic only - 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_summary

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

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

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

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

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

list_workspaces

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

plan_change

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

query_chart

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

refine_chart

<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

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

search_tools

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

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

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

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

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

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

Create discussions, and add, update, or delete comments and discussions. Do NOT call this tool until you have called search_tools(toolset="discussions", 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.

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

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

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