> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vistazo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Parameters

> Dashboard-level template variables that widgets read.

A parameter is referenced from a widget argument template. Defaults are the only persisted parameter state — a viewer changing one is ephemeral and never written back.

| Tool                                          | What it does        |                   |
| --------------------------------------------- | ------------------- | ----------------- |
| [`define_parameter`](#define_parameter)       | Define parameter    | Destructive write |
| [`set_parameter_value`](#set_parameter_value) | Set parameter value | Destructive write |
| [`remove_parameter`](#remove_parameter)       | Remove parameter    | Destructive write |

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