smartsuite_add_dashboard_widget
Add a widget to a dashboard tab using one of 19 predefined types. Default templates auto-fill position, size, and configuration for quick setup, with optional custom params.
Instructions
Add a widget to a dashboard tab. Requires readwrite/admin mode AND SMARTSUITE_ENABLE_SCHEMA_WRITE=true. Supply dashboardId, widgetType, and optionally tabId (defaults to the first tab), name, position {x,y}, size {width,height}, and params. VALID widgetType values — content: text-block-widget, heading-widget, simple-banner-widget, hero-widget, faq-widget, divider-widget; data: list-view-widget, card-view-widget, kanban-view-widget, calendar-view-widget, timeline-view-widget, chart-widget, pivot-widget, summary-card-widget, progress-widget, comparison-widget, filter-widget, record-details-widget, data-schema-widget; other: spacing-widget, button-row-widget, webpage-widget, record-picker-widget, countdown-widget, world-clock-widget (these last six have no auto-fill template — supply params). LAYOUT: x/width are column units (4 = full width), y/height are pixels. If you omit position/size, the widget gets its natural per-type default size (e.g. summary-card/progress/comparison are width 1, height 128; charts width 2; list/calendar width 4) — so metric cards render at the right height. If you omit position, the widget is appended BELOW existing widgets on the tab (not stacked at 0,0, which would overlap/hide widgets) — set position only to place deliberately (e.g. side-by-side metric cards need explicit x). The widget is created with a valid accent color and non-null description/collapsed defaults so the UI highlight-color editor works; pass color (hex) to choose the accent. PARAMS is widget-type-specific and passed through as-is. It is now OPTIONAL: if you omit params, the tool fills a minimal valid template for the widget type (data widgets default to showing the dashboard's own application with sensible default fields), so any of the 19 types can be created with just dashboardId + widgetType. Supply params only to customize — e.g. text-block/heading {content:}, divider {color}, data widgets {solution, application, source, ...window objects, filters, fields}. To customize a data widget precisely, describe an existing widget of the same type (smartsuite_describe_dashboard includeWidgets:true) and adapt it. The response includes filledFromTemplate:true when a default template was used. SUMMARY-CARD (metric) notes: the number renders in params.color — keep it a visible accent (never white/#FFFFFF, or it is invisible on the light card); function_type is count|sum|avg|min|max (avg, NOT "average"); the card needs the drill_in skeleton + appearance/size/mode the template provides; height 156 (128 clips padding). CHART: params must include totals, benchmarks, advanced_options, and categories or it 400s (the template includes them).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Widget name/title (optional). | |
| size | No | Size {width, height} — width is column units, height is pixels. Default {width:4, height:200}. | |
| color | No | Optional accent color (hex, e.g. "#3A86FF"). Defaults to a valid color so the UI highlight-color editor works. | |
| tabId | No | Tab id to place the widget on (default: first tab). | |
| params | No | Widget-type-specific configuration, passed through. Data widgets need a source; copy the shape from an existing widget of the same type. | |
| position | No | Grid position {x, y} — x is column units, y is pixels. Default {0,0}. | |
| widgetType | Yes | One of the 19 valid widget types (content or data) listed in the tool description. | |
| dashboardId | Yes | The dashboard (report) ID. |