Skip to main content
Glama
bjcoombs

excalidraw-room-mcp

by bjcoombs
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

add_elements

Insert shapes, arrows, text, and labels into a live Excalidraw room from compact specs, with optional links and server-chosen placement to prevent overlaps.

Instructions

Add elements to the drawing from compact specs. Shapes take x, y, width, height and an optional label. Arrows take start/end element ids (edges are computed) or absolute points. Any element may take a link (a URL), which makes it clickable on the canvas. Later specs may reference ids of earlier specs in the same call. Pass place instead of x and y to have the server find a free slot beside an element or inside a cluster, so two agents drawing at once never overlap; the result reports the coordinates it chose. The change reaches connected peers immediately and the room's stored copy shortly after; a result line beginning NOT PERSISTED means the stored copy is behind and the server is retrying in the background.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
elementsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.7.1
    • addedInput schema / properties / elements / items / properties / place
      Added value: +{
+  "additionalProperties": false,
+  "description": "Let the server choose the coordinates. Given this, x and y are ignored.",
+  "properties": {
+    "cluster": {
+      "description": "Id of an element whose cluster to join: its group, its frame, or the nodes already placed in it. The slot search fills the cluster's footprint before growing it, and the result says when the cluster no longer fits inside the room's neighbourhood radius.",
+      "type": "string"
+    },
+    "gap": {
+      "description": "Space left around the element, in canvas px. 20 by default.",
+      "minimum": 0,
+      "type": "number"
+    },
+    "near": {
+      "description": "Id of the element to sit beside. The slot is the first free one on the chosen side.",
+      "type": "string"
+    },
+    "newCluster": {
+      "description": "Start a separate cluster: the slot is more than the room's neighbourhood radius clear of the anchor's cluster, so a mention written on one does not pull in the other. Needs near.",
+      "type": "boolean"
+    },
+    "side": {
+      "description": "Which side of the anchor to take, or 'auto' (the default) for the nearest free side.",
+      "enum": [
+        "above",
+        "below",
+        "left",
+        "right",
+        "auto"
+      ],
+      "type": "string"
+    }
+  },
+  "type": "object"
+}
  2. Changed2 schema fields changedv0.5.1
    • addedInput schema / properties / elements / items / properties / points / items / description
      Added value: +"An [x, y] pair."
    • changedInput schema / properties / elements / items / properties / points / items / items
      Previous value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "number"
-  }
-]New value: +{
+  "type": "number"
+}
  3. Changed1 schema field changedv0.4.0
    • addedInput schema / properties / elements / items / properties / link
      Added value: +{
+  "description": "URL the element links to. Excalidraw shows a link icon on it; defaults to no link.",
+  "type": "string"
+}
  4. First observedv0.1.0

TDQS

A4/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so well: it discloses the place/x-y mutual exclusion, that ids can be referenced later in the same call, that changes reach peers immediately but the stored copy is eventually consistent, and that a NOT PERSISTED result line means background retry. These async/persistence semantics are exactly the kind of trait an agent cannot infer from the schema.

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 the core action, then organized by concern (geometry, wiring, links, id referencing, placement, persistence). Six sentences is dense but each adds a distinct behavioral fact; only the placement/cluster detail runs slightly long.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single deeply-nested parameter with no output schema and no annotations, the description covers return semantics ("the result reports the coordinates it chose", NOT PERSISTED handling) and the key writing behaviors. The remaining gap is that it does not situate the tool relative to its add/update siblings, which matters in an 18-tool set.

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?

Top-level schema coverage is 0%, so the description must compensate, and it explains the non-obvious fields well: shape geometry (x/y/width/height/label), arrow wiring (start/end ids with computed edges, or absolute points), link clickability, and the full place mechanism including cluster/newCluster behavior. It leaves the many style properties (opacity, roughness, fillStyle, strokeColor, etc.) to the schema, which is acceptable since those are self-describing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Add elements to the drawing") plus a scoping qualifier ("from compact specs") that hints at a lower-level sibling. However, it never names add_raw_elements, update_elements, or translate_elements, so an agent must infer the boundary between this and those siblings rather than being told.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives solid intra-tool guidance (pass place instead of x/y, reference earlier ids, use link for clickability) but offers no tool-level routing: nothing says when to choose add_elements over add_raw_elements or update_elements, or what preconditions must hold. Usage is implied by the spec-shape narrative rather than stated.

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

Deploy Server

Other Tools