Skip to main content
Glama

Canvas patch

canvas_patch
Read-only

Edit an existing json (JSON Render) canvas artifact element by element instead of resending the whole spec. Use it for every change to a json dashboard already on the canvas: name the artifact_id canvas_present returned and send only the operations that change it. Operations run in order: {"op":"set","id","element":{type, props, children?}} replaces an existing element (its children are kept when element omits them); {"op":"insert","id","parent","index"?,"element"} adds a new element under parent (appended when index is omitted); {"op":"remove","id"} deletes an element and the part of its subtree nothing else uses; {"op":"move","id","parent","index"?} re-parents an element. Keep element ids stable: reuse the ids already in the spec, add new ids only for new elements, and never rename or renumber existing ones. An element is one of canvas_present's json components with the same strict props, including binding (a dataset from list_canvas_datasets), Grid layout, LineChart annotations and Stat sparkline. time ({default, options, compare?}) and filters ([{name, label, default?}]) replace the dashboard's time control and filters and make it schema_version 2, which binding, layout, annotations and sparkline need: send time with the first patch that adds one to a v1 dashboard. To turn an inline panel live, set it with a binding; to place panels, set the Grid with its layout. The result is checked like a saved canvas (at most 128 elements and 12 levels, ids start with a letter, every child declared, no cycles); an invalid patch is refused with the exact problems and nothing changes: fix them and call once more. When the artifact is saved in the canvas library, pass base_revision_id (the revision_id your last patch returned, or current_revision_id from a refusal); if the user changed the canvas since, the call is refused with the current revision and its content to re-read. Only json artifacts can be patched: for html, svg or markdown send the complete content with canvas_present. To read or change a dashboard saved in the canvas library that is not an artifact of this conversation (the user names it by its canvas id), send canvas_id instead of artifact_id: with no base_revision_id the call changes nothing and answers the dashboard's current_revision_id and current_content; then patch it with canvas_id, base_revision_id set to current_revision_id and only the operations that change it. A dashboard the user may only read is answered canvas_read_only and one they cannot open canvas_not_found: tell them so, and never present a new dashboard in its place unless they ask for one.

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": "canvas_patch"
  }
}

Input Schema

NameRequiredDescriptionDefault
timeNoReplaces the dashboard's time control, e.g. {"default":"24h","options":["1h","6h","24h","7d","30d"],"compare":false}.
titleNoA new artifact title; omit to keep the current one.
filtersNoReplaces the dashboard's filters, e.g. [{"name":"cluster","label":"Cluster"}].
canvas_idNoThe id of a dashboard saved in the canvas library, to read or change it when it is not an artifact of this conversation. Send this or artifact_id, not both.
operationsNoElement operations, applied in order.
artifact_idNoThe artifact_id of the json artifact to edit, as canvas_present returned it. Send this or canvas_id, not both.
base_revision_idNoOnly for an artifact saved in the canvas library: the revision this patch edits (the revision_id the last patch returned, or current_revision_id from a refusal).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedInput schema / properties / artifact_id / description
      Previous value: -"The artifact_id of the json artifact to edit, as canvas_present returned it."New value: +"The artifact_id of the json artifact to edit, as canvas_present returned it. Send this or canvas_id, not both."
    • addedInput schema / properties / canvas_id
      Added value: +{
      +  "description": "The id of a dashboard saved in the canvas library, to read or change it when it is not an artifact of this conversation. Send this or artifact_id, not both.",
      +  "maxLength": 64,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • removedInput schema / required
      Removed value: -[
      -  "artifact_id"
      -]
  2. Added

TDQS

A3.9/5.0
Behavior1/5

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

The description is unambiguously a mutating tool ('Edit', 'patch', 'set it with a binding', 'nothing changes' on refusal, revision bookkeeping), yet annotations declare readOnlyHint=true. That is a direct contradiction of the structured safety signal. Setting the contradiction aside, the text does disclose a great deal (validation limits of 128 elements/12 levels, refusal semantics, canvas_read_only/canvas_not_found outcomes), but the annotation conflict is disqualifying for this dimension.

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

Conciseness3/5

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

Front-loaded and nearly every clause carries information, but the entire definition is one dense wall of text with the four operation shapes, validation rules, revision protocol, and error handling all run together. Operation specs and the library-dashboard flow would be far more scannable as separated sentences, and some parentheticals (Grid layout, LineChart annotations, Stat sparkline) pad the middle.

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?

Given a 7-parameter nested-object mutation tool with no output schema, the description covers what an agent needs: operation semantics, id stability, schema_version migration, validation caps and refusal behavior, the revision-conflict recovery loop, and permission-denied outcomes. Little is missing for correct invocation.

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 coverage is 100%, so the baseline is 3, and the description genuinely adds operational meaning beyond the schema: it explains each op's ordering and child-retention behavior, that time/filters 'replace the dashboard's time control and filters and make it schema_version 2' (needed by binding, layout, annotations, sparkline), and that base_revision_id must be 'the revision_id your last patch returned, or current_revision_id from a refusal'. It does not spell out the id-stability rule's per-parameter implication for element ids beyond prose, keeping it from a 5.

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 ('Edit an existing json (JSON Render) canvas artifact element by element') and immediately contrasts the mechanism with the sibling that resends whole specs ('instead of resending the whole spec'). An agent can tell this apart from canvas_present without inspecting either 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?

Explicitly scopes usage ('Use it for every change to a json dashboard already on the canvas') and states the exclusion with the correct alternative: 'Only json artifacts can be patched: for html, svg or markdown send the complete content with canvas_present.' It further disambiguates the two entry paths (artifact_id for conversation artifacts vs canvas_id for library dashboards) and gives the exact two-step read-then-patch handshake.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.