Enables AI agents to programmatically generate, edit, and view Excalidraw diagrams, featuring tools for adding shapes, text, and arrows with real-time preview and bi-directional synchronization.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Excalidraw MCP Server Create a flowchart showing how a user logs into our app"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server that empowers AI agents (like Claude, Cursor, Windsurf) to create, edit, and manage Excalidraw diagrams directly within your conversation.
Why Excalidraw? Its hand-drawn aesthetic and JSON-based format are perfect for rapid, programmable diagramming. This server bridges standard MCP clients with a local Excalidraw instance, enabling AI-powered visual thinking.
Feature | Description |
šØ Real-time Preview | Changes appear instantly in a local browser window via WebSocket |
š Smart Layout | Automatically calculates text width and binds labels to containers |
š Multi-Session | Switch between different diagrams seamlessly |
š§ Mermaid Support | Convert Mermaid syntax to Excalidraw diagrams instantly |
š¦ Export Options | Export to PNG, SVG, or JSON formats |
šļø Templates | Built-in architecture diagram templates |
Related MCP server: Excalidraw MCP Server
You don't need to clone this repo. Just configure your MCP client:
claude mcp add excalidraw -- npx -y @scofieldfree/excalidraw-mcpcodex mcp add excalidraw -- npx -y @scofieldfree/excalidraw-mcpGo to Settings > MCP ā Add New MCP Server:
Field | Value |
Name |
|
Type |
|
Command |
|
Open Cline settings and add to MCP Servers:
{
"mcpServers": {
"excalidraw": {
"command": "npx",
"args": ["-y", "@scofieldfree/excalidraw-mcp"]
}
}
}Use the Copilot CLI to interactively add:
/mcp addAlternatively, create or edit ~/.copilot/mcp-config.json:
{
"mcpServers": {
"excalidraw": {
"type": "local",
"command": "npx",
"tools": ["*"],
"args": ["-y", "@scofieldfree/excalidraw-mcp"]
}
}
}Follow the MCP Servers documentation. Add to .kiro/settings/mcp.json:
{
"mcpServers": {
"excalidraw": {
"command": "npx",
"args": ["-y", "@scofieldfree/excalidraw-mcp"]
}
}
}opencode mcp add excalidraw -- npx -y @scofieldfree/excalidraw-mcpOne-click install:
Or install via CLI:
# For VS Code
code --add-mcp '{"name":"excalidraw","command":"npx","args":["-y","@scofieldfree/excalidraw-mcp"]}'
# For VS Code Insiders
code-insiders --add-mcp '{"name":"excalidraw","command":"npx","args":["-y","@scofieldfree/excalidraw-mcp"]}'Add to your claude_desktop_config.json:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"excalidraw": {
"command": "npx",
"args": ["-y", "@scofieldfree/excalidraw-mcp"]
}
}
}Tool | Description |
| Start browser preview and open Excalidraw editor |
| Add shapes, text, arrows to the canvas |
| Modify existing element properties |
| Remove elements from canvas |
| Retrieve current diagram state |
| Convert Mermaid syntax to Excalidraw |
| Add a pre-built architecture diagram template |
| Create a new diagram or clear existing |
| Export diagram to PNG, SVG, or JSON |
| List all active diagram sessions |
| Delete a diagram session |
You say:
"Draw a flowchart with three boxes: Input ā Process ā Output"
AI uses:
start_session ā add_elements (3 rectangles + 2 arrows)You say:
"Convert this Mermaid diagram to Excalidraw:
graph LR: A[User] --> B[API Gateway] --> C[Service] --> D[(Database)]"
AI uses:
start_session ā create_from_mermaidYou say:
"Create an architecture diagram for a microservices system"
AI uses:
start_session ā add_template_architecture (or) add_elements with custom layoutāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā AI Agent (Claude/Cursor) ā
āāāāāāāāāāāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā MCP Protocol (JSON-RPC over stdio)
ā¼
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā Excalidraw MCP Server ā
ā āāāāāāāāāāāāāāā āāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāāāāāā ā
ā ā Tool Router āāāā State Store āāāā WebSocket Broadcast ā ā
ā āāāāāāāāāāāāāāā āāāāāāāāāāāāāāā āāāāāāāāāāāā¬āāāāāāāāāāā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāā
ā WebSocket
ā¼
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā Browser (Excalidraw Editor) ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāNode.js >= 18
pnpm >= 9
# Clone the repository
git clone https://github.com/Scofieldfree/excalidraw-mcp.git
cd excalidraw-mcp
# Install dependencies
pnpm install
# Start development server
pnpm devCommand | Description |
| Start dev server (backend + frontend) |
| Build for production |
| Run TypeScript type checking |
| Run ESLint |
| Create a new release version |
excalidraw-mcp/
āāā packages/
ā āāā mcp-server/ # Core MCP server + Excalidraw frontend
ā āāā src/
ā ā āāā index.ts # Entry point
ā ā āāā state.ts # Session state management
ā ā āāā http-server.ts
ā ā āāā tools/ # MCP tool implementations
ā āāā web/ # Excalidraw React frontend
āāā docs/ # Documentation
āāā package.json # Workspace configurationThe server automatically finds an available port starting from 3100. If you need a specific port, set the PORT environment variable.
Ensure you have a default browser configured. The server uses the open package to launch the browser.
Check if any firewall or antivirus is blocking WebSocket connections on localhost.
Contributions are welcome! Please read our Contributing Guide for details.
Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request
MIT Ā© Scofieldfree
Add multiple Excalidraw elements to the canvas.
Supported element types:
rectangle
ellipse
diamond
arrow
text
line
freedraw
image
frame/magicframe
iframe/embeddable
Style options:
strokeColor: e.g. #1e1e1e
backgroundColor: e.g. #D97706
fillStyle: solid/hachure/cross-hatch
strokeWidth: 1-4
roughness: 0=architect, 1=artist, 2=cartoonist
Advanced options:
label: Auto-create bound text inside shape/arrow containers
start/end: Arrow endpoint binding to new or existing elements
containerId: DEPRECATED (use label instead)
Multi-session support: Specify sessionId to target a specific session.
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | No | Session ID. If not provided, uses default session. | |
| elements | Yes | Array of elements to add |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses supported element types and options, and mentions session targeting, but fails to describe side effects, error behavior, or limits on element count.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections and bullet lists, and fairly concise. However, it could be slightly more compact without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should explain return values. It does not. Also, given the complexity of elements, it lacks constraints on ordering, idempotency, and error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 adds value by grouping options (style, advanced) and explaining label vs containerId and arrow binding, but most parameter details are already in schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Add multiple Excalidraw elements to the canvas', with a specific verb and resource. It distinguishes from siblings like delete_element and update_element.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives like create_diagram or add_template_architecture. It mentions multi-session support but lacks exclusionary criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a built-in architecture diagram template to the canvas.
This template visualizes the MCP server architecture with grouped layers and connected arrows. By default it resets the current session before adding template elements.
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | No | Session ID. If not provided, uses default session. | |
| reset | No | Whether to clear existing elements before adding the template. Default: true |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It discloses that by default the tool resets the current session before adding template elements, which is key behavioral info. However, it doesn't specify behavior when reset is false (e.g., whether it appends or merges), leaving some gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and contains no unnecessary words. Every sentence adds value: first sentence states action, second explains template content and default behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (2 params, no output schema, no nested objects), the description sufficiently covers purpose, default behavior, and template nature. It could mention what happens if reset is false, but the current info is adequate for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers both parameters with descriptions (100% coverage). The description only mentions the default reset behavior, which is already in the schema. No additional parameter meaning is added beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Add' and the resource 'built-in architecture diagram template', specifying it visualizes the MCP server architecture. It distinguishes from siblings like add_elements (which adds generic elements) and create_diagram (which creates from scratch).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when wanting the specific MCP architecture template and notes the default reset behavior, but lacks explicit when-not or alternative tool guidance. The purpose is clear but contextual usage decisions are left to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new diagram or clear an existing session.
This action will:
If a sessionId is specified, clear all elements in that session.
If no sessionId is specified, create a new session.
Reset the application state.
Usage scenarios: ā¢ Starting a new project (no sessionId specified) ā¢ Clearing an existing diagram (sessionId specified) ā¢ Creating multiple independent diagrams (specify different sessionIds each time)
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | No | Session ID. If not specified, a new session is automatically generated. If an existing ID is specified, that session is cleared. | |
| viewBackgroundColor | No | Canvas background color (default: #ffffff) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: it clears elements if sessionId provided, creates new session otherwise, and resets application state. This adequately informs the agent of the tool's side effects, though a caution about data loss could be added.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with numbered steps and bullet points for scenarios. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the parameter count and lack of output schema, the description covers the tool's behavior well. However, it omits details about what the tool returns (e.g., session ID), leaving a minor gap in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions. The description adds value by explaining the conditional behavior based on sessionId, but this is largely redundant with the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's dual function: creating a new diagram or clearing an existing session. It provides specific actions based on sessionId. However, it does not explicitly differentiate from sibling tools like 'start_session' or 'delete_diagram', though the conditional behavior is implied.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage scenarios are given (starting new project, clearing diagram, creating multiple diagrams). No explicit exclusions or alternatives (e.g., when to use 'start_session' instead) are mentioned, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create diagram elements from Mermaid syntax.
Converts Mermaid text to Excalidraw elements through connected browser client. If browser is not connected yet, request is queued and sent after websocket ready. Returns clear errors for timeout and mermaid syntax problems.
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | No | Session ID. If not provided, uses default session. | |
| mermaidDiagram | Yes | Mermaid diagram text, e.g. "graph TD; A-->B; B-->C;" | |
| reset | No | Whether to reset the current canvas before applying Mermaid result. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses important behaviors: conversion via browser, queuing if not connected, and error types. However, it does not clarify whether the tool modifies the current scene or what the return value is.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with four sentences, front-loading the core purpose. No superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and moderate complexity, the description covers conversion, connection handling, and errors. It lacks clarity on scene replacement vs. addition and success response, slightly reducing completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond the schema; it only repeats parameter purposes without extra context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool converts Mermaid text to Excalidraw elements, which is specific and distinguishes it from siblings like create_diagram and add_elements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use it (to create elements from Mermaid syntax) and mentions browser connection requirements and queuing behavior. However, it does not explicitly compare to sibling tools or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete the specified diagram session.
Note: This will completely delete the session and all its elements, and cannot be undone. If you only want to clear elements but keep the session, use create_diagram and specify the sessionId.
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | The Session ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully covers behavioral implications: 'This will completely delete the session and all its elements, and cannot be undone.'
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two short sentences plus a note. Front-loaded with the action. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description is complete. It covers the action, irreversibility, and provides an alternative use case, leaving no gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter 'sessionId' with schema description 'The Session ID to delete'. The tool description does not add further detail beyond what the schema provides. Since schema coverage is 100%, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete the specified diagram session', specifying the verb and resource. It distinguishes itself from sibling tools like 'create_diagram' and 'delete_element'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use this tool and when to use an alternative: 'If you only want to clear elements but keep the session, use create_diagram and specify the sessionId.' Also warns about irreversibility.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a specific element from the canvas.
Usage scenarios:
Remove unwanted elements
Clean up temporary elements
Delete erroneously added elements
Multi-session support: Specify sessionId to target a specific session.
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | No | Session ID. If not provided, uses default session. | |
| id | Yes | Element ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly states the destructive nature of deletion, but does not disclose whether deletion is permanent, if there are cascading effects, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (5 lines) and front-loaded with the action. Every sentence adds value, using bullet points for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers purpose, input usage, and multi-session support. It is slightly incomplete regarding return values or errors, but adequate for a simple delete tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already documented. The description adds context about session targeting but does not significantly enrich beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a specific element from the canvas, using a direct verb and specific resource. It distinguishes from sibling tools like add_elements and update_element.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage scenarios (remove unwanted, clean up temporary, delete erroneously added) and mentions multi-session support. However, it does not explicitly state when not to use this tool or contrast with update_element.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export the current diagram to a PNG, SVG, or JSON file.
Notes:
JSON format is saved directly by the server.
PNG/SVG are generated by the browser and sent back to the server to save.
Requires start_session to be called first and the browser to be connected.
Multi-session support: Specify sessionId to target a specific session.
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | No | Session ID. If not provided, uses default session. | |
| path | Yes | File path to save (including filename) | |
| format | No | Export format | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: JSON is saved directly by the server, while PNG/SVG are generated by the browser and sent back. It also notes the prerequisite session and browser connection, and multi-session targeting. This goes beyond a simple 'export' statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single opening sentence followed by three bullet-point notes. Every sentence adds value without redundancy. The main action is front-loaded, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations or output schema, the description is fairly complete: it covers prerequisites, behavior differences between formats, and multi-session support. It lacks details on expected return values or error handling, but these are minor gaps for a relatively simple export tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers all parameters with descriptions (100% coverage). The description adds minimal value for parameters, only noting that 'sessionId' targets a specific session. The format options are clear from the enum, and path is self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool exports the current diagram to PNG, SVG, or JSON. It uses a specific verb ('Export') and resource ('current diagram'), and the listed formats differentiate it from sibling tools that create, delete, or update diagrams.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: requires 'start_session' to be called first and the browser to be connected. It also explains multi-session support via 'sessionId'. However, it does not explicitly state when not to use this tool or mention alternatives, though no sibling tool directly competes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve complete information about the current diagram scene.
Returns:
List of all elements
Application state
Version number
Session ID
Usage scenarios:
Viewing current diagram content
Analyzing scene structure
Obtaining element IDs for updates/deletion
Multi-session support: Specify sessionId to query a specific session.
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | No | Session ID. If not provided, uses default session. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the return content (elements, state, version, session ID) and multi-session capability, adding value beyond the schema. No annotations are present, so it carries the full burden; it is transparent about being a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the main purpose, and uses clear sections. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and one optional parameter, the description covers key information: what is returned, when to use it, and session handling. It could be slightly more explicit about being read-only, but overall complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a description for sessionId. The description adds context ('Multi-session support: Specify sessionId') but mostly restates the schema's 'If not provided, uses default session.' Baseline is 3 for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves complete information about the current diagram scene, with a specific list of return items. It distinguishes from siblings by being a read-only retrieval tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage scenarios are provided (viewing content, analyzing structure, obtaining IDs for updates/deletion) and multi-session support is mentioned. However, it does not explicitly compare to alternatives or state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all currently active Excalidraw sessions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It indicates a read operation by using 'list', but does not disclose edge cases (e.g., empty result) or return format. For a trivial tool, this is minimally adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params, no annotations, no output schema), the one-sentence description is complete enough for an agent to understand its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema fully covers them. The description adds no parameter information, which is fine since there are none. Baseline 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all currently active Excalidraw sessions, using a specific verb ('list') and resource ('sessions'). This distinguishes it from sibling tools that focus on creation, deletion, or export.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, but the context of sibling tools implies it is for read-only listing. No exclusions or prerequisites are provided, which is acceptable for a simple list tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start browser preview and open Excalidraw editor interface.
Multi-session support:
No sessionId: Uses default session (default)
sessionId specified: Open/Create specific session
Multiple sessions can be opened simultaneously for different diagrams
After calling this tool:
Browser window opens automatically
Excalidraw editor loads
WebSocket realtime connection is established
Please pass the same sessionId when using tools like add_elements, update_element subsequently.
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | No | Session ID. If not provided, uses default session. Supports opening multiple sessions. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses key behaviors: browser window opening, editor loading, WebSocket connection establishment. It does not mention potential destructive actions, but as a session starter, destruction is unlikely.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with bullet points and numbered steps, though some redundancy exists between the first sentence and the steps. Still clear and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description covers post-call behavior adequately. It does not mention return values or error conditions, but for a simple initialization tool, this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a description for sessionId. The description adds significant meaning: default session behavior and ability to open multiple sessions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb ('Start browser preview and open Excalidraw editor interface') and resource ('Excalidraw editor'), and distinguishes it from sibling tools like add_elements by being the session initialization tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains multi-session support and provides after-call steps, but lacks explicit 'when not to use' guidance. However, the context of use for session management is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update attributes of an existing element.
Updatable attributes:
x, y: Position coordinates
width, height: Dimensions
strokeColor: Stroke color
backgroundColor: Background color
fillStyle: Fill style
strokeWidth: Stroke width
roughness: Roughness
opacity: Opacity
text: Text content (only for text type)
Multi-session support: Specify sessionId to target a specific session.
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | No | Session ID. If not provided, uses default session. | |
| id | Yes | Element ID to update | |
| updates | Yes | Attributes to update |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description details updatable attributes and multi-session support, but does not disclose behavior like atomicity, error handling, or whether partial updates are supported beyond what the schema implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the main purpose, and uses a clear bullet-point list for attributes, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing output description (no output schema), and no mention of what the tool returns upon success or failure. Adequate for a basic update tool but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes each parameter. The description adds a redundant list of updatable attributes and mentions multi-session support, but does not significantly enhance understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update attributes of an existing element' and lists specific updatable attributes, distinguishing it from siblings like delete_element or add_elements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates use for modifying existing elements via the list of updatable attributes, but provides no explicit guidance on when not to use this tool or alternatives beyond the tool's own function.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.1add_elementsadd_template_architecturecreate_diagramcreate_from_mermaiddelete_diagramdelete_elementexport_diagramget_scenelist_sessionsstart_sessionupdate_elementScored across 11 tools
Most tools have distinct purposes (adding, deleting, exporting, querying). However, 'add_elements' and 'create_from_mermaid' both add elements, though via different inputs, and 'add_template_architecture' is a specialized add. Descriptions help distinguish them, so minor ambiguity exists.
Tool names largely follow a verb_noun pattern (e.g., 'add_elements', 'delete_diagram'). 'create_from_mermaid' breaks this pattern by including a preposition, causing slight inconsistency. Otherwise consistent.
With 11 tools covering diagram creation, manipulation, querying, export, and session management, the count is well-scoped for the domain. Each tool serves a clear purpose without redundancy.
Core operations (create, read, update, delete elements and sessions, export) are covered. Minor gaps like undo/redo or advanced layout operations are absent but not critical for typical use.
Create and edit architecture diagrams from your AI agent; get an SVG and a live editable canvas.
Create, read and live-edit visual boards, Kanban plans, Gantt timelines and diagrams with AI agents.
AI agent draws editable hand-drawn diagrams (flowchart, ER, architecture) via MCP, not static images
Generate, edit, and manage Eraser diagrams and docs with AI.
