Skip to main content
Glama
Sign In

supermetrics

by com.supermetrics
OverviewDiscussionsAdmin

manage_dashboards

Destructive

Share live dashboards in Supermetrics Studio — self-contained pages that re-query the user's data on each view, so a shared link always shows current numbers.

Before uploading, show a STATIC inline preview (data hard-coded, no smQuery), then confirm before uploading the LIVE smQuery version. smQuery and window.fetch work only inside Studio, so a preview using them renders empty in the chat — the inline preview must hard-code the data you already fetched, and the upload must fetch via smQuery (see the 'code' param), never the hard-coded preview. After building a dashboard, offer this upload; do not just show the preview and stop. Skip the confirmation only when the user EXPLICITLY asked to publish (e.g. "put this in Studio and give me a link").

Campaign actions (pause, budget change) go in only when the user asks: add the campaign tools to allowed_tools and only the managed accounts to allowed_accounts, confirm each change in the page, and warn that viewers act on the owner's connections, so share only with people who may make those changes.

BigQuery dashboards: before writing the code, fetch supermetrics_guide(mode="dashboard_bigquery") — the response shape and allowed_accounts key differ from Supermetrics sources.

Actions:

  • 'upload': Upload a new dashboard or replace an existing one. Requires title, code, allowed_tools, allowed_accounts; description is optional. The code format (HTML or JSX) is detected automatically.

  • 'edit': Apply targeted anchor-based patches to dashboard code. Call get_dashboards first to see the current code, then send patches.

Edit patch types (pick the smallest that fits):

  • region replace (PREFER for changing a section's logic/content): {"from": "// #region charts", "to": "// #endregion charts", "replace": "// #region charts\n\n// #endregion charts"} — replaces the WHOLE region from 'from' to 'to', anchor lines INCLUDED. Write the COMPLETE new block in 'replace' and reproduce the 'from' and 'to' marker lines inside it (normally unchanged) so they survive; omitting a marker deletes it. Restating an anchor does NOT duplicate it. 'from' must be unique; 'to' is the first match after it.

  • find/replace (small unique swap): {"find": "old text", "replace": "new text"}

  • after/insert (a NEW element): {"after": "anchor text", "insert": "new content"}

  • before/insert: {"before": "anchor text", "insert": "new content"} Modifiers (find/replace only): "nth": N (target Nth occurrence), "all": true (replace all). Patches are applied sequentially and atomically.

Patchable code: When uploading, wrap each section in PAIRED region markers so edits can target them, and declare each variable/function inside the region that uses it:

  • HTML: …

  • CSS: /* #region kpi-cards /…/ #endregion kpi-cards */

  • JS: // #region chart-init … // #endregion chart-init

  • Tag key elements with data-sm attributes: data-sm="kpi-spend", data-sm="filter-date" Each anchor must be unique in the code.

Best practices:

  • Add a loading indicator (spinner or skeleton) while data is being fetched.

  • When it makes sense, add selectors (dropdowns, date pickers, toggles) that let viewers change query parameters such as date range, account, or metric.

  • Date controls: offer a genuinely flexible date range, not just a few fixed presets. smQuery's date_range_type accepts today, yesterday, this_month(_inc), last_month, this_year_inc, last_year(_inc), and the last_x_days / last_x_weeks_sun_sat / last_x_weeks_mon_sun / last_x_months / last_x_years families — substitute a number for x (e.g. last_90_days, last_3_months) and append _inc to include the current period. There is NO native quarter or year-to-date preset: deliver 'this/last quarter', 'year to date', and any viewer-picked custom range via date_range_type="custom" with start_date/end_date (YYYY-MM-DD) computed in the dashboard's own JS (derive the boundaries from new Date()). Prefer including a fully custom start/end picker alongside the presets.

  • Period comparison: when comparison is wanted, add ONE dashboard-wide comparison control and feed the SAME compare params into EVERY widget's smQuery — time-series charts too, not only scorecards. compare_type="prev_range" (previous period), "prev_year" (same period last year), "prev_year_weekday", or "custom" (with compare_start_date/compare_end_date, YYYY-MM-DD); compare_show="perc_change" (default), "abs_change", or "value". For a year-over-year time-series overlay, either use compare_type or issue a second smQuery for the prior period and plot it as an additional series.

  • Give each chart/table/KPI its own stable smQuery key (see the 'code' param) so rapidly changing a selector can't show stale data from a previous selection.

  • If an 'upload' response includes code_warnings, the board will render empty/wrong data or never refresh — fix the issue it names (a static board with no smQuery calls, or column mapping via requested_field_ids) and re-upload before sharing the board.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>"
    },
    "name": "manage_dashboards"
  }
}

Input Schema

NameRequiredDescriptionDefault
codeNoComplete dashboard code (HTML or JSX) — a self-contained page that visualizes the data. Required for 'upload'. Query data with the host-injected smQuery(tool, params); see supermetrics_guide(mode='dashboard_bigquery') for BigQuery. Wrap each section in paired region markers so 'edit' can patch it.
titleNoDisplay name of the dashboard ('upload'). If omitted or blank, a title is derived from the code (its <title>, else the first heading).
actionYes'upload' to publish a new dashboard or replace an existing one, 'edit' to apply targeted patches to dashboard code
patchesNoAnchor-based patches for 'edit'. Types: region replace, find/replace, after/insert, before/insert. Applied sequentially and atomically.
descriptionNoOptional short description of the dashboard itself (what it shows, its purpose), stored on the board and shown in the board list ('upload').
dashboard_idNoUUID of the dashboard. Required for 'edit'. For 'upload', omit to publish a new dashboard or provide to replace an existing one.
allowed_toolsNoMCP tool names the dashboard is allowed to call ('upload'). Must be an explicit list, e.g. ["data_query"]; never null or empty.
change_summaryNoOptional one-line summary of this version, shown in the dashboard changelog
allowed_accountsNoPer-data-source allow-list of the account IDs the dashboard queries ('upload'), e.g. {"AW": ["123"]}. This is a security boundary: viewers query on the owner's credentials, so list only the accounts the board uses.

Output Schema

NameRequiredDescriptionDefault
dataNo
errorNo
notesNo
successYes
business_contextNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Goes well past the annotations (destructiveHint=true, openWorldHint=true, idempotentHint=false): the description explains that smQuery/window.fetch fail outside Studio (so a naive preview renders empty), that patches apply sequentially and atomically, that omitting a region marker deletes it, that allowed_accounts is a security boundary where viewers act on the owner's credentials, and that code_warnings means the board will render empty or never refresh. That is exactly the mutation and safety context the annotations cannot convey.

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

Conciseness4/5

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

Front-loaded with purpose, then workflow, then action specs, then patch taxonomy — a sensible ordering for a complex tool. It is long and the 'Best practices' block (date_range_type families, period-comparison params) reads like authoring guidance rather than tool-selection guidance, but each item is actionable and specific rather than filler.

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 destructive, open-world, 9-parameter tool an agent needs preview/confirm rules, patch semantics, security constraints on allowed_accounts/allowed_tools, the BigQuery prerequisite, and code_warnings handling — all present. Output schema exists, and the description still flags the one response field (code_warnings) that changes agent behavior, which is appropriately scoped rather than redundant.

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?

Schema coverage is 100%, so the baseline would be 3, but the description adds substantial meaning the schema does not: the four patch types with concrete payload shapes, the marker-preservation rule for region replace, 'from' uniqueness and 'to' being the first match after it, and the find/replace-only 'nth'/'all' modifiers. It also clarifies the upload-vs-replace semantics of dashboard_id and the mandatory nature of allowed_tools.

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?

Opens with a specific verb and resource — 'Share live dashboards in Supermetrics Studio' — and immediately clarifies the defining property (pages that re-query on each view, so links stay current). The two actions ('upload' and 'edit') are named and distinguished, and the read-side sibling get_dashboards is implicitly separated by 'Call get_dashboards first to see the current code'.

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?

Explicit sequencing: show a STATIC preview, confirm, then upload the LIVE smQuery version; 'do not just show the preview and stop'; and the precise escape hatch — 'Skip the confirmation only when the user EXPLICITLY asked to publish'. It also gates the BigQuery path behind supermetrics_guide(mode="dashboard_bigquery") and gates campaign actions behind an explicit user request.

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

All supermetrics toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources