Pug

Create or update dashboard

upsert_dashboard

Destructive

Upsert creates a dashboard or edits one. It returns the dashboard's link, if the server has one, which you give to the person, and the ids of the tiles you sent, in order. To create, leave id empty and give a name and tiles. To edit, pass the dashboard's id and its update_time, from get_dashboard or your last upsert_dashboard. If someone changed the dashboard since, the call fails; read it again. A tile without an id is added and needs exactly one of spec and markdown. Tile names must differ on a dashboard, ignoring case. To change a tile, send its id and only the fields that change; spec and position are replaced whole. A tile stays insight or markdown; to switch, add a new tile and remove the old one. Tiles you leave out stay as they are. To remove a tile, list its id in remove, and only when the person asked for it. Every insight tile shows the dashboard's default_time_range and default_granularity (the last 30 days by day when unset), so work out each one with query_insights over that window first. Dashboards can't show segmentation insights or session metrics. chart applies to trends and top K only. Positions use a 12-column grid: x is 0 to 10, w is 2 to 12, and x + w is at most 12. y and h count rows of about 18px; h is at least 15 for an insight tile and 9 for a KPI or markdown tile. A tile you place can't overlap another; leave position out to put a new tile below the others. Markdown can't contain images. A dashboard with sharing on can't be edited.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "upsert_dashboard"
  }
}

Input Schema

Name	Required	Description
`id`	No
`tiles`	No
`remove`	No
`project_id`	No	The id of the project, from list_projects.
`description`	No
`update_time`	No
`display_name`	No
`default_time_range`	No
`default_granularity`	No

Output Schema

Name	Required	Description	Default
`id`	No
`url`	No
`tile_ids`	No
`update_time`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 13, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes well past the annotations (destructiveHint=true, idempotentHint=false) by disclosing optimistic-concurrency failure behavior ('If someone changed the dashboard since, the call fails; read it again'), partial-update semantics ('Tiles you leave out stay as they are'), replacement granularity ('spec and position are replaced whole'), and a hard blocker ('A dashboard with sharing on can't be edited').

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 what the tool does and returns, then proceeds through creation, editing, tile rules, and layout constraints. Dense but nearly every sentence carries an operational rule; the cost is a long run-on block with no sub-structure, which makes scanning harder than it needs to be.

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 complex 9-parameter mutation with deeply nested tile specs, the definition covers mode selection, concurrency, tile identity, type immutability, removal, layout geometry, and known limitations. An output schema exists, so return-value detail ('the dashboard's link... and the ids of the tiles you sent') is a bonus rather than a gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 11%, yet the description compensates heavily: it explains id vs update_time, exactly-one-of spec/markdown for new tiles, unique-ignoring-case tile names, chart applicability to trends/top K only, and precise position bounds (x 0–10, w 2–12, x+w≤12, h minimums per tile type). Remaining gaps are minor – project_id and the dashboard/tile description fields are never discussed in the description.

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 pair and resource: 'Upsert creates a dashboard or edits one,' then immediately splits the two modes. An agent can distinguish this from get_dashboard and list_dashboards without opening any schema.

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 mode selection rules: 'To create, leave id empty and give a name and tiles. To edit, pass the dashboard's id and its update_time, from get_dashboard or your last upsert_dashboard.' It also routes to query_insights for computing insight tiles and gates tile removal on 'only when the person asked for it.'

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

All Pug tools Inspect

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.