Skip to main content
Glama

Add elements to the board or create a new one

add_elements

Creates elements on a canvas. Creates a new canvas if room_id is omitted, or adds to the existing canvas if room_id is provided. Use cases: wireframes, UI mockups, freeform illustrations, standalone shapes, and manual layouts that Mermaid does not cover well. For diagrams Mermaid can express, use add_elements_from_mermaid instead. Element types: rectangle, ellipse, diamond, arrow, line, freedraw, text, image. Rich text: the text field supports limited HTML for text elements and rectangle/ellipse/diamond shape labels. Supports the rich-text plugin HTML subset: /, /, , , /, //, , , and . Use textAlign for left/center/right alignment; avoid unsupported HTML/CSS. TEXT IN SHAPES: use containerId on text element pointing to shape id. ARROWS: Position at EDGE of source shape. Auto-bound within 30px. Colors: strokeColor, backgroundColor (hex).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
room_idNoRoom ID of an existing canvas to add to. If the user is continuing a canvas already referenced in this conversation (by room_id, or a URL like ?room=[room_id] or /gdrive?id=[room_id]), pass it here. Omit to create a new canvas.
elementsYesArray of element definitions to create

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
urlYesCanvas room URL
isNewYesWhether a new canvas was created
room_idNoCanvas room ID
appStateYesCanvas app state (viewBackgroundColor, etc.)
elementsYesAll elements currently on the canvas
collabUrlYesCollaboration server URL for Socket.IO

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. Changed1 schema field changed
    • changedInput schema / properties / room_id / description
      Previous value: -"Room ID. If not provided, creates a new canvas. Extract from URLs as ?room=[room_id] or /gdrive?id=[room_id]."New value: +"Room ID of an existing canvas to add to. If the user is continuing a canvas already referenced in this conversation (by room_id, or a URL like ?room=[room_id] or /gdrive?id=[room_id]), pass it here. Omit to create a new canvas."
  2. Changed2 schema fields changed
    • changedInput schema / properties / elements / items / description
      Previous value: -"Per-type required fields: rectangle/ellipse/diamond → x, y (width/height default to 100). text → x, y, text (width/height auto-sized; omit or set to 0). arrow/line → x, y, points (e.g. [[0,0],[100,0]]); optionally startBinding/endBinding instead of points. image → x, y, width, height, fileId. freedraw → x, y, points. type is inferred from fields if omitted (text field → text, points → line, fileId → image, else rectangle)."New value: +"Per-type required fields: rectangle/ellipse/diamond → x, y (width/height default to 100). text → x, y, text (width/height auto-sized; omit or set to 0). rectangle/ellipse/diamond may also include text, which creates a bound label. arrow/line → x, y, points (e.g. [[0,0],[100,0]]); optionally startBinding/endBinding instead of points. image → x, y, width, height, fileId. freedraw → x, y, points. type is inferred from fields if omitted (text field → text, points → line, fileId → image, else rectangle)."
    • changedInput schema / properties / elements / items / properties / text / description
      Previous value: -"Text content. Required for type=text. Also used as arrow label when set on an arrow."New value: +"Text content. Required for type=text. For text elements and rectangle/ellipse/diamond shape labels, Supports the rich-text plugin HTML subset: <b>/<strong>, <i>/<em>, <u>, <br>, <div>/<p>, <ul>/<ol>/<li>, <a href>, <font color>, and <span style=\"color, background/background-color, font-size, font-family\">. Use textAlign for left/center/right alignment; avoid unsupported HTML/CSS. Also used as arrow label when set on an arrow."
  3. Changed3 schema fields changed
    • addedInput schema / properties / room_id
      Added value: +{
      +  "description": "Room ID. If not provided, creates a new canvas. Extract from URLs as ?room=[room_id] or /gdrive?id=[room_id].",
      +  "type": "string"
      +}
    • removedInput schema / properties / room_url
      Removed value: -{
      -  "description": "Room URL or ID. If not provided, creates a new canvas",
      -  "type": "string"
      -}
    • addedOutput schema / properties / room_id
      Added value: +{
      +  "description": "Canvas room ID",
      +  "type": "string"
      +}
  4. Changed18 schema fields changed
    • addedInput schema / properties / elements / items / description
      Added value: +"Per-type required fields: rectangle/ellipse/diamond → x, y (width/height default to 100). text → x, y, text (width/height auto-sized; omit or set to 0). arrow/line → x, y, points (e.g. [[0,0],[100,0]]); optionally startBinding/endBinding instead of points. image → x, y, width, height, fileId. freedraw → x, y, points. type is inferred from fields if omitted (text field → text, points → line, fileId → image, else rectangle)."
    • changedInput schema / properties / elements / items / properties / containerId / description
      Previous value: -"Container element ID (for text bound to shapes). Set x,y to 0,0 for auto-centering"New value: +"For type=text: ID of the shape this text is bound to. Set x,y to 0,0 for auto-centering inside the shape."
    • changedInput schema / properties / elements / items / properties / endBinding / description
      Previous value: -"For arrows: bind end point to a shape."New value: +"For type=arrow: binds the arrow end to a shape. Use instead of or alongside points."
    • addedInput schema / properties / elements / items / properties / endBinding / required
      Added value: +[
      +  "elementId",
      +  "focus",
      +  "gap"
      +]
    • changedInput schema / properties / elements / items / properties / fontFamily / description
      Previous value: -"Font family: 5=Excalifont, 6=Nunito, 7=Lilita One, 8=Comic Shanns (default: 5)"New value: +"Font family: 5=Excalifont, 6=Nunito, 7=Lilita One, 8=Comic Shanns (default: 5). Applies to text elements."
    • changedInput schema / properties / elements / items / properties / fontSize / description
      Previous value: -"Font size (default: 20)"New value: +"Font size (default: 20). Applies to text elements."
    • changedInput schema / properties / elements / items / properties / height / description
      Previous value: -"Height (default: 100)"New value: +"Height (default: 100; omit for text — auto-sized)"
    • changedInput schema / properties / elements / items / properties / label / description
      Previous value: -"For arrows: text label displayed on the arrow"New value: +"For type=arrow: text label displayed on the arrow"
    • changedInput schema / properties / elements / items / properties / points / description
      Previous value: -"Points array for arrows/lines. Relative to element x,y. Example: [[0,0],[0,100]] for vertical arrow"New value: +"Required for arrow/line/freedraw. Coordinates relative to element x,y. Example: [[0,0],[100,0]] for horizontal arrow."
    • changedInput schema / properties / elements / items / properties / startBinding / description
      Previous value: -"For arrows: bind start point to a shape."New value: +"For type=arrow: binds the arrow start to a shape. Use instead of or alongside points."
    • addedInput schema / properties / elements / items / properties / startBinding / required
      Added value: +[
      +  "elementId",
      +  "focus",
      +  "gap"
      +]
    • changedInput schema / properties / elements / items / properties / text / description
      Previous value: -"Text content (for text elements)"New value: +"Text content. Required for type=text. Also used as arrow label when set on an arrow."
    • changedInput schema / properties / elements / items / properties / type / description
      Previous value: -"Element type (e.g. rectangle, ellipse, diamond, arrow, line, freedraw, text, image)"New value: +"Element type. Inferred from fields if omitted: text field → text, points → line, fileId → image, else rectangle."
    • addedInput schema / properties / elements / items / properties / type / enum
      Added value: +[
      +  "rectangle",
      +  "ellipse",
      +  "diamond",
      +  "arrow",
      +  "line",
      +  "freedraw",
      +  "text",
      +  "image"
      +]
    • changedInput schema / properties / elements / items / properties / width / description
      Previous value: -"Width (default: 100)"New value: +"Width (default: 100; omit for text — auto-sized)"
    • changedInput schema / properties / elements / items / properties / x / description
      Previous value: -"X coordinate"New value: +"X coordinate (defaults to 0 if omitted)"
    • changedInput schema / properties / elements / items / properties / y / description
      Previous value: -"Y coordinate"New value: +"Y coordinate (defaults to 0 if omitted)"
    • changedInput schema / properties / elements / items / required
      Previous value: -[
      -  "type",
      -  "x",
      -  "y"
      -]New value: +[
      +  "x",
      +  "y"
      +]
  5. Changed7 schema fields changed
    • addedOutput schema / properties / appState / additionalProperties
      Added value: +true
    • changedOutput schema / properties / appState / description
      Previous value: -"Current app state (viewBackgroundColor, etc.)"New value: +"Canvas app state (viewBackgroundColor, etc.)"
    • addedOutput schema / properties / appState / properties
      Added value: +{
      +  "viewBackgroundColor": {
      +    "type": "string"
      +  }
      +}
    • changedOutput schema / properties / elements / description
      Previous value: -"Current scene elements for inline SVG rendering"New value: +"All elements currently on the canvas"
    • addedOutput schema / properties / elements / items
      Added value: +{
      +  "additionalProperties": true,
      +  "type": "object"
      +}
    • removedOutput schema / properties / pendingMermaid
      Removed value: -{
      -  "description": "Mermaid definition to be rendered client-side",
      -  "type": "object"
      -}
    • addedOutput schema / required
      Added value: +[
      +  "url",
      +  "isNew",
      +  "collabUrl",
      +  "elements",
      +  "appState"
      +]
  6. Changed14 schema fields changed
    • changedInput schema / properties / elements / items / properties / endBinding / description
      Previous value: -"For arrows: bind end point to a shape. REQUIRED for connected diagrams!"New value: +"For arrows: bind end point to a shape."
    • removedInput schema / properties / elements / items / properties / endBinding / properties / elementId / description
      Removed value: -"ID of shape to connect to (REQUIRED)"
    • removedInput schema / properties / elements / items / properties / endBinding / properties / focus / description
      Removed value: -"Position on edge: -1 to 1, 0=center (REQUIRED, use 0)"
    • removedInput schema / properties / elements / items / properties / endBinding / properties / gap / description
      Removed value: -"Gap from shape edge in pixels (REQUIRED, use 8)"
    • removedInput schema / properties / elements / items / properties / endBinding / required
      Removed value: -[
      -  "elementId",
      -  "focus",
      -  "gap"
      -]
    • removedInput schema / properties / elements / items / properties / locked
      Removed value: -{
      -  "description": "Lock element (default: false)",
      -  "type": "boolean"
      -}
    • changedInput schema / properties / elements / items / properties / startBinding / description
      Previous value: -"For arrows: bind start point to a shape. REQUIRED for connected diagrams!"New value: +"For arrows: bind start point to a shape."
    • removedInput schema / properties / elements / items / properties / startBinding / properties / elementId / description
      Removed value: -"ID of shape to connect to (REQUIRED)"
    • removedInput schema / properties / elements / items / properties / startBinding / properties / focus / description
      Removed value: -"Position on edge: -1 to 1, 0=center (REQUIRED, use 0)"
    • removedInput schema / properties / elements / items / properties / startBinding / properties / gap / description
      Removed value: -"Gap from shape edge in pixels (REQUIRED, use 8)"
    • removedInput schema / properties / elements / items / properties / startBinding / required
      Removed value: -[
      -  "elementId",
      -  "focus",
      -  "gap"
      -]
    • changedInput schema / properties / elements / items / properties / type / description
      Previous value: -"Element type"New value: +"Element type (e.g. rectangle, ellipse, diamond, arrow, line, freedraw, text, image)"
    • removedInput schema / properties / elements / items / properties / type / enum
      Removed value: -[
      -  "rectangle",
      -  "ellipse",
      -  "diamond",
      -  "arrow",
      -  "line",
      -  "freedraw",
      -  "text",
      -  "image"
      -]
    • removedInput schema / properties / timeout
      Removed value: -{
      -  "default": 3600,
      -  "description": "Room lifetime in seconds (default: 3600, max: 86400). Only used when creating new canvas",
      -  "type": "number"
      -}
  7. Changed6 schema fields changed
    • changedInput schema / properties / elements / items / properties / endBinding / properties / focus / description
      Previous value: -"Position on edge: -1 to 1, 0=center (default: 0)"New value: +"Position on edge: -1 to 1, 0=center (REQUIRED, use 0)"
    • changedInput schema / properties / elements / items / properties / endBinding / properties / gap / description
      Previous value: -"Gap from shape edge in pixels (default: 8)"New value: +"Gap from shape edge in pixels (REQUIRED, use 8)"
    • addedInput schema / properties / elements / items / properties / endBinding / required
      Added value: +[
      +  "elementId",
      +  "focus",
      +  "gap"
      +]
    • changedInput schema / properties / elements / items / properties / startBinding / properties / focus / description
      Previous value: -"Position on edge: -1 to 1, 0=center (default: 0)"New value: +"Position on edge: -1 to 1, 0=center (REQUIRED, use 0)"
    • changedInput schema / properties / elements / items / properties / startBinding / properties / gap / description
      Previous value: -"Gap from shape edge in pixels (default: 8)"New value: +"Gap from shape edge in pixels (REQUIRED, use 8)"
    • addedInput schema / properties / elements / items / properties / startBinding / required
      Added value: +[
      +  "elementId",
      +  "focus",
      +  "gap"
      +]
  8. Changed1 schema field changed
    • changedInput schema / properties / elements / items / properties / fontFamily / description
      Previous value: -"Font family: 1=Virgil, 2=Helvetica, 3=Cascadia (default: 1)"New value: +"Font family: 5=Excalifont, 6=Nunito, 7=Lilita One, 8=Comic Shanns (default: 5)"
  9. Changed4 schema fields changed
    • addedOutput schema / properties / appState
      Added value: +{
      +  "description": "Current app state (viewBackgroundColor, etc.)",
      +  "type": "object"
      +}
    • addedOutput schema / properties / collabUrl
      Added value: +{
      +  "description": "Collaboration server URL for Socket.IO",
      +  "type": "string"
      +}
    • addedOutput schema / properties / elements
      Added value: +{
      +  "description": "Current scene elements for inline SVG rendering",
      +  "type": "array"
      +}
    • addedOutput schema / properties / pendingMermaid
      Added value: +{
      +  "description": "Mermaid definition to be rendered client-side",
      +  "type": "object"
      +}
  10. First observed

TDQS

A4.5/5.0
Behavior4/5

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

The annotations only indicate non-readonly and non-destructive, which is consistent with the description's 'creates' language. The description adds meaningful behavioral context beyond the annotations: the room_id behavior, arrow auto-binding within 30px, rich-text HTML subset, and color handling. This goes well beyond the minimal hints, though it doesn't cover every edge case.

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?

The description is fairly long but well-structured with clear section headers (Rich text, TEXT IN SHAPES, ARROWS, Colors). The main purpose is front-loaded. Some redundancy exists with the schema (e.g., the HTML subset is repeated), but each section provides useful guidance. Overall, it earns its length without being bloated.

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?

Given the tool's complexity (multiple element types, rich text, arrow binding, canvas creation), the description covers key aspects well: usage context, element types, rich-text constraints, arrow positioning, and color format. An output schema exists, so return values are not needed. Minor gaps include lack of coordinate system explanation and the textAlign reference without a schema parameter, but the description is still highly complete for a complex tool.

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 baseline is 3. The description enriches this by explaining when room_id should be used, elaborating on the element types and their inferred defaults, explaining containerId for bound text, and detailing arrow binding behavior. It adds value over the schema descriptions, though some details (like textAlign) are mentioned in the description but not present as a schema property.

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?

The description clearly states the tool creates elements on a canvas and distinguishes between creating a new canvas or adding to an existing one via room_id. It explicitly names the sibling tool add_elements_from_mermaid and explains when to use that instead, making the purpose and scope unambiguous.

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?

Provides explicit 'when to use' guidance with concrete use cases (wireframes, UI mockups, freeform illustrations, etc.) and directly says 'For diagrams Mermaid can express, use add_elements_from_mermaid instead.' It also explains when to pass room_id versus omit it, giving clear alternatives.

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.

TDQS

A4.4/5.0
Disambiguation5/5

Each tool has a clear, distinct purpose: add_elements for manual creation, add_elements_from_mermaid for Mermaid-based creation, delete/query/update for lifecycle operations, and get_guide for workflow guidance. The overlap between the two creation tools is explicitly resolved in descriptions, leaving no ambiguity.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern: add_elements, add_elements_from_mermaid, delete_elements, get_guide, query_elements, update_elements. The modifier 'from_mermaid' extends the base pattern without breaking consistency, and all verbs are clear (add, delete, get, query, update).

Tool Count5/5

With 6 tools, the set is well-scoped for a canvas/diagram server, covering creation, query, update, delete, and guidance. This is within the ideal 3-15 range, and each tool earns its place without redundancy or bloat.

Completeness4/5

The toolset provides solid CRUD coverage for canvas elements (add, query, update, delete) plus a Mermaid import option and usage guidance. A minor gap is that there is no explicit tool to list existing canvases/rooms; agents must rely on prior room_id, which could be a friction point in new sessions, but core workflows are fully supported.

Resources