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

# Dashboards

> Create, find, describe, clone, archive and version dashboards.

Use `search_dashboards` to find one by name and `list_dashboards` to browse or triage. `get_dashboard` is the primary read — it returns the agent-facing context summary alongside the widgets.

| Tool                                                            | What it does                 |                   |
| --------------------------------------------------------------- | ---------------------------- | ----------------- |
| [`list_dashboards`](#list_dashboards)                           | List dashboards              | Read-only         |
| [`get_dashboard`](#get_dashboard)                               | Get dashboard                | Read-only         |
| [`search_dashboards`](#search_dashboards)                       | Search dashboards            | Read-only         |
| [`create_dashboard`](#create_dashboard)                         | Create dashboard             | Additive write    |
| [`clone_dashboard`](#clone_dashboard)                           | Clone dashboard              | Additive write    |
| [`update_dashboard`](#update_dashboard)                         | Update dashboard             | Destructive write |
| [`archive_dashboard`](#archive_dashboard)                       | Archive dashboard            | Destructive write |
| [`set_dashboard_theme`](#set_dashboard_theme)                   | Set dashboard theme          | Destructive write |
| [`regenerate_dashboard_context`](#regenerate_dashboard_context) | Regenerate dashboard context | Destructive write |
| [`save_dashboard_version`](#save_dashboard_version)             | Save dashboard version       | Additive write    |
| [`list_dashboard_versions`](#list_dashboard_versions)           | List dashboard versions      | Read-only         |
| [`restore_dashboard`](#restore_dashboard)                       | Restore dashboard version    | Destructive write |

## list\_dashboards

`Read-only`

List dashboards in a workspace that you can access — the ENUMERATION tool (browse everything, triage what is empty or stale). Each row carries widgetCount, updatedAt (ISO), and the dashboard's `ownerId` + `ownerName`, so you can triage and attribute without a list\_widgets call per dashboard. Two optional PEOPLE filters, both taking a uid (from list\_workspace\_members, or from a member the user attached to their message): `ownerId` keeps only what that person owns, and `accessibleBy` only what they can see — the sharing-audit question ("what can Bob get to?"). Neither widens YOUR visibility: the result is always a subset of the dashboards you can access. To find a dashboard BY NAME OR KEYWORD, call search\_dashboards instead of listing everything and filtering the names yourself — it matches names, tags, and descriptions and ranks the hits.

## get\_dashboard

`Read-only`

Return full detail for one dashboard: metadata (including archived — true means soft-deleted), the agent-facing context summary (purpose, use cases, caveats, a plain-language interpretation per widget), all widgets, and parameters. `contextStatus` reports whether that summary is final: `ready` = current, `generating` = a regeneration is in flight and what you are reading is the previous text, `stale` = queued or failed. The primary dashboard read — for ONE widget's full config and pipeline wiring use get\_widget. To describe the dashboard or its charts qualitatively, the context summary and interpretations are enough; for actual values, rankings, or comparisons read the cached rows with get\_widget\_data (cheap — no refresh, no pipeline run). Reserve refresh\_\*/explore\_dashboard for when the user needs fresher data than the last refresh.

## search\_dashboards

`Read-only`

Keyword search across dashboard names, tags, and descriptions in a workspace. Returns only dashboards you can access. The name/keyword lookup path — reach for this instead of enumerating with list\_dashboards and filtering the names yourself (that tool is for browsing and triage). Matching is keyword/substring based — one distinctive word ("renewables") works best; multi-word queries rank dashboards matching more of the words higher. RANK ORDER IS NOT IDENTITY: when several hits tie at the top score with near-identical names, the response carries a `hint` saying so — confirm which one is actually the target (get\_dashboard / list\_widgets) before any destructive call rather than trusting the first row. If nothing matches, the dashboard may live in a DIFFERENT workspace (search each workspace from list\_workspaces before concluding it doesn't exist), or call list\_dashboards and match semantically yourself (workspaces are small).

## create\_dashboard

`Additive write`

Create a new dashboard in a workspace. You become its owner.

## clone\_dashboard

`Additive write`

Deep-copy a dashboard: every live widget with its pipeline wiring, transform, and last published rows, plus the dashboard's parameters — into a NEW dashboard you own, named '\<source> copy' unless you pass `name`. The right tool whenever the user wants a variant to edit without touching the original ("copy this and swap the country", "duplicate it for Q3"): ONE call, then edit the copy — never rebuild a dashboard by hand with create\_dashboard + add\_widget when a clone gets you there. Needs only view access to the source (archived sources clone fine; the copy is always live). NOT carried over: history, discussions, share links, and the refresh schedule's owner — a stored schedule is copied DISABLED and un-attributed, so re-enable it with set\_refresh\_cadence on the copy if you want it to keep refreshing (scheduled runs would then use YOUR connections). Returns the new dashboard's id.

## update\_dashboard

`Destructive write`

Rename or update the description of a dashboard. Requires edit access. (Scheduled auto-refresh is configured with set\_refresh\_cadence; palette/formatting with set\_dashboard\_theme.)

## archive\_dashboard

`Destructive write`

Archive a dashboard (soft-delete): hides it from discovery while keeping its widgets, parameters, data, and history intact and restorable. The platform does not hard-delete dashboards; pass restore:true to bring one back. What archiving does to the agent-facing surfaces, automatically — no follow-up cleanup call exists or is needed: list\_dashboards hides it unless includeArchived:true, and search\_dashboards / search\_widgets stop returning it and its widgets. Reads by id still work: get\_dashboard reports archived:true and still returns the stored skill summary and interpretations, and list\_widgets / get\_widget / get\_widget\_data still return the last published data — archiving hides a dashboard, it never rewrites or deletes its content. Everything that WRITES refuses while archived (add\_widget, remove\_widget / restore\_widget, set\_widget\_\*, define\_parameter / set\_parameter\_value, update\_dashboard, set\_refresh\_cadence, regenerate\_dashboard\_context), as do refresh\_pipeline / refresh\_dashboard / refresh\_stage, explore\_dashboard, and create\_share\_link — and share links already issued stop resolving (the public URL 404s) until it is restored. Scheduled auto-refresh stops running while archived (the cadence configuration is kept), so the data freezes at the last refresh. Requires edit access (owner, editor, or workspace admin).

## set\_dashboard\_theme

`Destructive write`

Override this dashboard's palette and formatting defaults on top of the workspace theme. SPARSE — you send only the keys you want to change and they replace only those keys; everything you omit keeps falling through to the workspace theme, so never send a full copy of the resolved values (a copy freezes this dashboard against later workspace changes). `palette` carries the categorical `series` array (3–12 `#rrggbb` colours, replaced wholesale — series colours are a set, not per-index edits) plus the `positive`/`negative`/`warning`/`muted` sentiment slots. `formatting` carries `locale` (BCP-47; omit it so each viewer sees their own locale), `currency` (ISO code), `dateStyle` (short | medium | long), and `decimals`. Theme values are DEFAULTS: a widget config that names its own currency or colour still wins. Pass `clear: true` to drop every dashboard override and return to the workspace theme. Use this only when a dashboard genuinely needs to look different from the rest of the workspace — the workspace theme is the right place for a house style, and it is edited in Settings, not through any tool. Requires edit access.

## regenerate\_dashboard\_context

`Destructive write`

Force-regenerate the AI CONTEXT SUMMARY for a dashboard and all its widgets — the auto-generated narrative of what the dashboard shows (purpose, use cases, caveats, a plain-language reading per widget) that get\_dashboard returns. Not related to workspace SKILLS, which are member-authored procedures (list\_skills / get\_skill); nothing here reads or writes those. Requires workspace admin. Regeneration starts immediately (no debounce); the background sweep is only the fallback if it fails. Asynchronous: the response returns started:true right away and the new text is NOT written yet. Do not time it — poll get\_dashboard until its `contextStatus` reads `ready` (it flips to `generating` here, and one pass publishes the dashboard-level context and every widget interpretation together, atomically, so `ready` means all of it is final). A read while it still says `generating` returns the PREVIOUS generation, not a partial one. `stale` means the pass failed and the background sweep will retry.

## save\_dashboard\_version

`Additive write`

Record the dashboard's current state as a version in its history right now, instead of waiting for the automatic settle window. Returns the new snapshotId (usable with restore\_dashboard). written:false means the current state already matches the latest version — not a failure; the latest entry in list\_dashboard\_versions already IS this state. Requires edit access.

## list\_dashboard\_versions

`Read-only`

List a dashboard's recorded version history, newest first: snapshotId, when it was recorded, what triggered it (manual save, automatic settle, pre-restore/pre-archive), who, and a summary of what changed. Use a snapshotId with restore\_dashboard to roll back; save\_dashboard\_version records the current state as a new version.

## restore\_dashboard

`Destructive write`

Restore a dashboard to a recorded version from its history (snapshotId from list\_dashboard\_versions). The current state is saved as a version first, so a restore is always reversible. Widgets are reconciled to the snapshot (config only — data re-fetches on the refresh that starts automatically afterwards); parameters and dashboard name/description are restored too. Stages whose MCP connection the caller no longer has fetch nothing until reconnected (reported as unresolvedConnections). Requires edit access; archived dashboards refuse.