# Dashboards ## Tools `list_dashboards` browses a workspace, or finds a dashboard by name when you pass `query`. `get_dashboard` is the primary read — it returns the agent-facing context summary alongside the widgets. `create_dashboard` with `fromDashboardId` copies one. | Tool | What it does | | |---|---|---| | [`list_dashboards`](#list_dashboards) | List or search dashboards | Read-only | | [`get_dashboard`](#get_dashboard) | Get dashboard | Read-only | | [`create_dashboard`](#create_dashboard) | Create dashboard | Additive write | | [`update_dashboard`](#update_dashboard) | Update dashboard | Destructive write | | [`archive_dashboard`](#archive_dashboard) | Archive dashboard | Destructive write | ## list_dashboards `Read-only` List or search the dashboards in a workspace that you can access. Without `query` it ENUMERATES: each row carries widgetCount, updatedAt and `ownerId` + `ownerName`, enough to triage and attribute without a list_widgets call per dashboard. With `query` it SEARCHES names, tags and descriptions, ranked (`{ results, hint? }`, each hit with `matchedOn` and `score`) — never list everything and filter the names yourself. RANK ORDER IS NOT IDENTITY: when the `hint` says near-identical names tie, confirm the target (get_dashboard / list_widgets) before any destructive call. Nothing matched: search each workspace from get_me, or list without `query` and match semantically. `ownerId` keeps what one person owns and `accessibleBy` what they can see ("what can Bob get to?"), each a uid from list_workspace_members; neither widens YOUR visibility. ## get_dashboard `Read-only` Return one dashboard in full: metadata (archived: true = soft-deleted), its context summary (purpose, use cases, caveats, a plain-language reading per widget), every widget and the parameters. `contextStatus`: ready = current, generating = a regeneration is in flight and this is the previous text, stale = queued or failed. The summary is enough to describe the dashboard; for actual values read the cached rows with get_widget include data (no refresh, no pipeline run), and for one widget's full wiring use get_widget. Refresh only when the user needs newer data than the last refresh. `url` is its address; `publicLink` and `embed` say who else can open it (set_sharing). A select with more than 25 options returns 10 with `optionsTotal` and `optionsSampled: true`; the full list is its source widget's rows, and set_parameter names the closest options when a value misses. ## create_dashboard `Additive write` Create a new dashboard in a workspace, or copy one with `fromDashboardId`; you own it. A COPY deep-copies every live widget (wiring, transform, last published rows) and the parameters into a new dashboard named '\ copy' unless you pass `name`. Copying is the right call whenever the user wants a variant to edit without touching the original ("copy this and swap the country"): ONE call, then edit the copy — never rebuild by hand. It needs only view access to the source; archived sources copy fine. NOT copied: history, discussions, the public link, and the schedule's owner — a stored schedule is copied DISABLED; re-enable it with update_dashboard's `cadence` (runs then use YOUR connections). Returns the new dashboard's id. ## update_dashboard `Destructive write` Rename a dashboard, change its description, override its palette and formatting on top of the workspace theme (`theme`, or `clearTheme: true` to drop every override), or turn its scheduled refresh on or off (`cadence`, whose description holds the schedule's rules). Only what you pass changes. Use a theme override only when a dashboard genuinely needs to look different from the rest of the workspace: the workspace theme, which an admin sets in Settings, is the right place for a house style. Requires edit access. ### `cadence` The schedule: `enabled` plus an interval, every N minutes | hours | days | weeks (minimum 15 minutes). refresh runs once, NOW; this keeps data current. MATCH THE INTERVAL TO HOW OFTEN THE SOURCE PUBLISHES. Annual/quarterly sources: weeks (daily is 365 identical fetches a year). Daily sources (exchange rates, weather, filings): a day, or hours for same-day movement. Minutes only for a live feed. A DASHBOARD schedule is free: saving attributes it to YOU — runs execute on the dashboard owner's data-source connections, and a chart one repairs with AI (at most once a day per chart) draws your usage allowance — and re-saving un-pauses one paused for credential failures or failing sources. A SCHEDULE KEEPS THE FETCH CURRENT, NOT THE WINDOW: a widget argumentTemplate with a literal end bound (end_year 2020), or a notebook data cell / vistazo.call with a literal date, re-fetches the same window every run — check get_widget before promising it stays current. A NOTEBOOK schedule is BILLED: each run restarts the notebook and runs every cell as YOU, on your data access and compute allowance; it needs edit access, runs whatever the notebook holds at run time, and a failed run is reported to you and the owner. A seat holds at most 25 scheduled dashboards and 25 notebooks per workspace. enabled:false stops scheduling, keeping the configuration. An interval repeats from its first run (the next 15-minute sweep after enabling); the reply's `note` names that weekday and UTC time. Fixed weekdays/times (calendar schedules) are set in the web app's Schedule card; toggling enabled without an interval preserves one, and passing interval/unit replaces it. The reply reports the schedule AS IT NOW STANDS — `nextRunAt` (null when it will not fire; with a `nextRunNote` the run is due on the next sweep and nextRunAt is the latest it comes), `lastRunAt`, and `pausedReason` with how to resume. get_dashboard and get_notebook return the same block. ## archive_dashboard `Destructive write` Archive a dashboard (soft delete): hidden from discovery, with its widgets, parameters, data and history kept; restore:true brings it back. Nothing hard-deletes a dashboard, and no follow-up cleanup call exists: list_dashboards hides it unless includeArchived:true and list_widgets' `query` stops returning it, while reads by id still work (get_dashboard reports archived:true; list_widgets and get_widget return the last published data). While archived every write refuses, as do refresh, explore_dashboard and turning its public link on; the public link stops resolving and scheduled refresh pauses (the cadence is kept), so its data freezes at the last refresh. Requires edit access (owner, editor, or workspace admin).