Skip to main content
Glama
SmartSuiteFoundry

SmartSuite MCP Server

by SmartSuiteFoundry
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

smartsuite_add_dashboard_widget

Adds a configurable widget to a SmartSuite dashboard tab. Specify dashboard, widget type, optional tab, position, size, and params; requires read/write or admin mode.

Instructions

SOME TYPES HAVE NO AUTO-FILL TEMPLATE and fail with a 400 unless you supply params: countdown-widget needs {target_date:"YYYY-MM-DD", target_time:"YYYY-MM-DDThh:mm:ss" (a FULL datetime, not a clock time), display_days/display_hours/display_minutes}; heading-widget and text-block-widget need {content: } — a plain string is rejected with "Expected a dictionary". The other 19 types create from widgetType alone. 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

TableJSON Schema
NameRequiredDescriptionDefault
nameNoWidget name/title (optional).
sizeNoSize {width, height} — width is column units, height is pixels. Default {width:4, height:200}.
colorNoOptional accent color (hex, e.g. "#3A86FF"). Defaults to a valid color so the UI highlight-color editor works.
tabIdNoTab id to place the widget on (default: first tab).
paramsNoWidget-type-specific configuration, passed through. Data widgets need a source; copy the shape from an existing widget of the same type.
positionNoGrid position {x, y} — x is column units, y is pixels. Default {0,0}.
widgetTypeYesOne of the 19 valid widget types (content or data) listed in the tool description.
dashboardIdYesThe dashboard (report) ID.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.9.8

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint:false, so the description carries the behavioral burden and does it thoroughly: required write-enable flag, the 400 failure mode for auto-fill-less types, the 'Expected a dictionary' rejection, append-below-existing default placement, accent-color/description defaults so the UI editor works, and the filledFromTemplate:true response flag. This is far beyond what the annotation conveys.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Almost every sentence carries useful detail, but it is delivered as one sprawling ALL-CAPS-laced paragraph with clear repetition — the no-auto-fill/params requirement is stated at the top and again in the 'other' list, and params-optional is restated multiple times. Front-loading is decent, but structure and de-duplication could be much tighter for a description of this length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with 8 params (incl. nested objects), no output schema, and no meaningful annotation coverage, the description supplies everything an agent needs: auth/mode requirements, defaults, failure modes, per-type param shapes, and the meaning of the return flag. Nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description adds substantial meaning the schema lacks: the enumerated valid widgetType values grouped by content/data/other, per-type params requirements, layout unit semantics (x/width = columns, y/height = pixels), per-type default sizes, and summary-card/chart-specific requirements (function_type values, required chart keys, height 156).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb + resource ('Add a widget to a dashboard tab') and clearly distinguishes itself from siblings like smartsuite_update_dashboard_widget, smartsuite_remove_dashboard_widget, and smartsuite_normalize_dashboard_widgets. An agent can identify the operation without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when params must be supplied ('countdown-widget needs... heading-widget and text-block-widget need...'), when they can be omitted ('the other 19 types create from widgetType alone'), and routes the agent to smartsuite_describe_dashboard for precise customization. Prerequisites (readwrite/admin mode AND SMARTSUITE_ENABLE_SCHEMA_WRITE=true) are called out up front.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools