define_parameter
Destructive write
Create or update a dashboard parameter definition. Parameters are template variables referenced in a widget’s argument template as {{ params.<key> }} and injected at refresh time. key is the unique template handle within the dashboard; re-defining an existing key updates it. type is select | multi_select | date | datetime | date_range | text | integer | decimal | boolean. Provide options for static select choices (plain strings, or {value,label} pairs when the stored value differs from the display label — e.g. value “KEN”, label “Kenya”), or source to populate options dynamically from a parameter_source tool invocation’s rows. STATIC OPTIONS ARE NOT VALIDATED against any data source — whatever you write becomes a selectable value, and a bad one fails only later, inside a refresh. When option values feed a fetch argument (country codes, indicator ids, tickers), VERIFY them before defining the parameter: call_connection_tool once against the source’s own lookup/search tool, or explore_dashboard with params overrides (it runs the pipelines ephemerally and publishes nothing). Never hand-write ids of a class the source’s schema tells you not to guess — a dropdown is not an exemption from that rule. Static vs sourced: prefer static options for a small, stable, already-verified set; use source when the list is large, data-driven, or you would otherwise be transcribing ids by hand. Relative expressions (“today-14”, “today-1mo/mo”) are DATE-TYPED ONLY — date, datetime, date_range. integer and decimal parameters take a plain number and have no relative form; for a rolling integer-period window (“the last 5 years”) use the open-ended-fetch / transform-slice recipe described in set_widget_pipeline instead of inventing an expression here. Creating a parameter REQUIRES exactly one default intent: value (a concrete default), defaultEmpty: true (explicitly start unfiltered — right for multi_selects and boolean filters that begin open), or defaultRule (‘all’ | ‘first’, sourced selects only — resolves once options populate). Defaults are authored ONLY through these tools; the app’s filters panel is a viewer/override surface with no defaults path. Pass order to control the filters-panel position — author related parameters in logical reading order (Start before End, coarse before fine); without it they sort alphabetically by label, which inverts natural sequences. Values are validated against the type on write (a date_range whose start resolves after its end is rejected). Requires edit access.
set_parameter_value
Destructive write
Set a dashboard parameter’s DEFAULT value — the only persisted parameter state. Defaults define the published baseline: scheduled and manual refreshes render widget templates with them, and every viewer lands on them when opening the dashboard (viewers’ own filter changes are ephemeral and never stored; the filters panel has NO defaults path — this tool is the only one). Shape follows the parameter type: text→string, integer/decimal→number, boolean→true|false|null (null = don’t filter), date→ISO string OR a relative expression, datetime→ISO datetime, date_range→{start,end} (each endpoint ISO or relative), select→string, multi_select→string[]. Relative date expressions are Grafana-style date math resolved in UTC at each refresh: today or now, optional +N/-N offset with unit d|w|mo|y (default d), optional /unit rounding to the start of the unit (weeks start Monday) — e.g. “today-90” (rolling 90 days ago), “today-1mo/mo” (first day of last month). Prefer relative expressions for defaults like “the last 90 days” so they move with the clock instead of going stale. THE TRADEOFF: changing a default RE-BASELINES the dashboard — the next refresh publishes at the new value and every viewer lands on it, so this is an edit to what the dashboard shows, not a private view. It is also the ONLY way to switch a parameter through the API: a viewer’s own filter selection is ephemeral UI state with no tool behind it. To try a value WITHOUT re-baselining, pass it to explore_dashboard’s params instead (ephemeral, publishes nothing). Requires edit access.
remove_parameter
Destructive write
Remove a dashboard parameter definition by key. Widget templates referencing it will render it empty thereafter. Requires edit access.