Generates deterministic, fully editable Excalidraw-compatible scenes (.excalidraw) using the Excalidraw v2 schema, including native shape bindings and centered bound text, so diagrams can be opened and edited in Excalidraw.
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., "@Sketchwright Create a three-tier web app diagram and export it as an editable Excalidraw scene"
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.
Deterministic Excalidraw diagram agent, layout engine, and Model Context Protocol (MCP) server.
Status: Beta (v0.1.0). Fully functional MCP server, standalone Python engine, and CLI; production-ready for automated diagram generation.
Dimension | Specification | Evidence / Details |
Package Name |
| Defined in |
Runtime Requirement | Python | Tested on Python 3.12 ( |
Protocol Support | Model Context Protocol (MCP) 2.3.0 | 6 tools, 3 resources, 3 prompts over |
Output Formats |
| Verified reciprocal arrow bindings & multiline text containers |
Layout Algorithms | Layered (Sugiyama), Grid, Tree | Deterministic cycle breaking, 4 directions ( |
External Dependencies | Zero external LLM or cloud services required | Pure local layout and scene serialization |
Primary Entry Points |
| Module execution via |
License | MIT License | Verified in |
Related MCP server: excalidraw-diagram-agent
Sketchwright is a developer-oriented Model Context Protocol (MCP) diagram agent and standalone Python engine. It translates structured diagram specifications and lightweight textual DSL into deterministic, visually balanced, and fully editable Excalidraw-compatible scenes (.excalidraw) as well as standalone SVG.
A language model in an MCP-compatible host (such as Claude Desktop, VS Code, or Antigravity) decides what the diagram should represent; Sketchwright's deterministic engine decides how that specification is validated, positioned, routed, and serialized.
Structured intent in; validated, editable diagram scene out.
Core layout, validation, and generation capabilities require no paid model APIs, cloud accounts, API keys, or external LLM service.
Generate a complete, editable Excalidraw diagram scene in fewer than five steps:
# 1. Clone the repository
git clone https://github.com/manoj-025/sketchwright-mcp.git
cd sketchwright-mcp
# 2. Install dependencies with uv
uv sync --all-groups
# 3. Generate an Excalidraw diagram from the sample architecture
uv run sketchwright generate examples/architecture.json -o architecture.excalidraw --overwrite# 1. Clone the repository
git clone https://github.com/manoj-025/sketchwright-mcp.git
Set-Location sketchwright-mcp
# 2. Install dependencies with uv
uv sync --all-groups
# 3. Generate an Excalidraw diagram from the sample architecture
uv run sketchwright generate examples/architecture.json -o architecture.excalidraw --overwriteExpected result:
Generated diagram written to: architecture.excalidrawYou can drag and drop architecture.excalidraw directly into Excalidraw.com or open it inside the Excalidraw VS Code extension.
Model Context Protocol (MCP 2.x) Integration: Exposes 6 dedicated tools (sketchwright_create_diagram, sketchwright_update_diagram, sketchwright_validate_diagram, sketchwright_layout_diagram, sketchwright_export_diagram, sketchwright_get_capabilities), 3 resources, and 3 prompt templates over standard input/output (stdio).
Strict Stdio Discipline: Guarantees that MCP JSON-RPC protocol framing is never polluted by application logs; all diagnostics are routed strictly to sys.stderr.
Deterministic Layered Layout (Sugiyama Engine):
Cycle detection and feedback edge set condensation to guarantee termination on cyclic graphs.
Longest-path rank assignment and barycentric crossing reduction.
Multi-directional flow: Left-to-Right (LR), Right-to-Left (RL), Top-to-Bottom (TB), and Bottom-to-Top (BT).
Graceful handling of disconnected clusters, self-loops, and parallel edges.
True Excalidraw v2 Schema & Reciprocal Bindings:
Validates and generates native startBinding, endBinding, container boundElements, and centered bound text containers.
Fully editable in Excalidraw.com or the Excalidraw VS Code / Obsidian extensions.
Visual Grouping & Boundaries: Declared groups serialize with member container tracking and dashed boundary rectangles.
Incremental Diagram Mutation: Iteratively patch diagrams (add/remove nodes, prune connected edges, update labels) via stable ID matching with ambiguous-match fallback protection.
Standalone CLI & Public Python API: Complete functionality accessible as a CLI utility or embedded library without requiring an active MCP host.
Defensive Resource Limits: Enforces input payload limits (1 MB), node counts (500), edge counts (1000), label lengths (256 chars), and path traversal boundary checks.
Clean SVG Export: Standalone valid SVG renderer with <tspan> multiline text wrapping, arrow markers, and XML escaping.
Software & Cloud Architecture: Multi-tier web applications, client/server models, API gateways, database clusters.
Microservices & Data-Flow Topologies: Service meshes, message brokers, caching tiers, storage clusters.
Decision Trees & Process Flowcharts: Branching logic, validation flows, decision nodes.
State-Transition Diagrams & Cyclic Networks: Finite state machines, feedback loops, retry circuits.
CI/CD Pipelines & Roadmaps: Build, test, security audit, and deployment stages.
Shape Identifier | Visual Representation | Common Use Case |
| Standard sharp box | Services, modules, UI components, microservices |
| Rounded container | Queues, consumers, workers, terminal steps |
| Elliptical container | Start/stop states, events, terminal nodes |
| Rhombus / Diamond | Decision conditions, branching logic |
| Storage drum | Databases, caches, file storage, data lakes |
| Frameless text block | Standalone annotations, notes, titles |
Python: 3.12 or newer.
Package Manager: uv (recommended) or standard pip.
Supported Operating Systems: Windows, Linux, macOS.
# Clone the repository
git clone https://github.com/manoj-025/sketchwright-mcp.git
cd sketchwright-mcp
# Install dependencies into isolated virtual environment
uv sync --all-groups# Clone and install in editable mode with development dependencies
git clone https://github.com/manoj-025/sketchwright-mcp.git
cd sketchwright-mcp
python -m venv .venv
# Activate environment (POSIX: source .venv/bin/activate | Windows: .venv\Scripts\Activate.ps1)
pip install -e ".[dev]"Sketchwright exports a fully typed public Python API:
from sketchwright import (
generate_diagram,
validate_diagram,
layout_diagram,
export_diagram,
update_diagram,
get_capabilities,
)
spec = {
"schema_version": "1.0",
"title": "Cloud Microservice Architecture",
"layout": {"algorithm": "layered", "direction": "LR"},
"nodes": [
{"id": "gateway", "label": "API Gateway", "shape": "rectangle"},
{"id": "auth", "label": "Auth Service", "shape": "rounded_rectangle"},
{"id": "db", "label": "User Store", "shape": "cylinder"},
],
"edges": [
{"id": "e1", "source": "gateway", "target": "auth", "label": "JWT Verify"},
{"id": "e2", "source": "auth", "target": "db", "label": "SQL Query"},
],
}
# 1. Generate full Excalidraw scene
result = generate_diagram(spec, output_path="architecture.excalidraw", overwrite=True)
print(f"Valid Scene: {result.validation.is_valid}")
print(f"Canvas Size: {result.laid_out.canvas_rect.width} x {result.laid_out.canvas_rect.height}")
print(f"Total Elements: {len(result.scene['elements'])}")Expected output:
Valid Scene: True
Canvas Size: 853.0 x 310.0
Total Elements: 7See examples/hello_world.py for a complete standalone runnable script.
Sketchwright provides the sketchwright executable (and module invocation via python -m sketchwright).
Exit Code | Classification | Description |
| Success | Command completed successfully. |
| User / Validation Error | Schema validation failure, syntax error, or invalid CLI flag. |
| Internal / Filesystem Error | Unexpected runtime exception or filesystem access error. |
# Inspect version and CLI help
uv run sketchwright --version
uv run sketchwright --help
# Query runtime capabilities and limits
uv run sketchwright capabilities
# Validate a diagram specification or Excalidraw scene
uv run sketchwright validate examples/architecture.json
uv run sketchwright validate my_diagram.excalidraw
# Generate an Excalidraw scene file (.excalidraw)
uv run sketchwright generate examples/architecture.json -o web_arch.excalidraw --overwrite
# Generate an SVG file (.svg)
uv run sketchwright generate examples/flowchart.json -o flowchart.svg --format svg --overwrite
# Compute raw geometry and routing coordinates without writing a scene
uv run sketchwright layout examples/architecture.json --direction LR
# Launch the MCP server over standard input/output
uv run sketchwright mcpSample output from uv run sketchwright validate examples/architecture.json:
Validation result for architecture.json: VALIDTo register Sketchwright in an MCP client (such as Claude Desktop, VS Code, or Google Antigravity), add the following entry to your host's MCP configuration file (e.g., mcpServers object):
{
"mcpServers": {
"sketchwright": {
"command": "uv",
"args": [
"run",
"--directory",
"<PATH_TO_SKETCHWRIGHT_MCP>",
"sketchwright",
"mcp"
]
}
}
}Note: Replace
<PATH_TO_SKETCHWRIGHT_MCP>with the absolute path to your clonedsketchwright-mcpdirectory (use forward slashes/on all platforms).
Tool Name | Purpose | Key Parameters |
| Generates complete Excalidraw scene JSON from specification or text DSL. |
|
| Incrementally mutates an existing specification (add/remove nodes, edges) and regenerates scene. |
|
| Validates a diagram specification or Excalidraw scene for schema conformance and bindings. |
|
| Computes deterministic node coordinates, canvas bounds, and edge routes without serialization. |
|
| Exports a diagram specification or scene to |
|
| Returns machine-readable report of supported shapes, algorithms, directions, and limits. | None |
Resources:
schema://v1.0: Canonical JSON Schema for DiagramSpec.
capabilities://manifest: Runtime capability and limits manifest.
guide://usage: Comprehensive prompt engineering guide and diagram patterns.
Prompts:
architecture_diagram: Prompt guide for structured software architecture requests.
flowchart_diagram: Prompt guide for workflow/decision flowcharts.
dependency_graph: Prompt guide for software/package dependency graphs.
Sketchwright works out of the box with zero external configuration. Settings can be customized via environment variables (or a local .env file; see .env.example).
Explicit API / CLI Argument / Tool Parameter (highest precedence)
Diagram Specification layout block
Environment Variables (SKETCHWRIGHT_*)
Internal Default Settings (lowest precedence)
Variable | Type | Default | Description | Secret |
| string |
| Logging level ( | No |
| string |
| Default layout algorithm ( | No |
| string |
| Default layout direction ( | No |
| float |
| Intra-rank spacing between adjacent nodes in pixels. | No |
| float |
| Distance between consecutive ranks/layers in pixels. | No |
| float |
| Outer canvas margin around diagram bounds in pixels. | No |
| int |
| Maximum allowed input payload size in bytes (1 MB). | No |
| int |
| Maximum number of nodes permitted per diagram. | No |
| int |
| Maximum number of edges permitted per diagram. | No |
| int |
| Maximum permitted characters for any label. | No |
| string | unset | Path boundary: restricts file outputs to an authorized root. | No |
{
"schema_version": "1.0",
"title": "Example Web Architecture",
"layout": {
"algorithm": "layered",
"direction": "LR",
"node_spacing": 80.0,
"rank_spacing": 120.0,
"padding": 40.0
},
"style": {
"theme": "light",
"font_size": 18,
"stroke_width": 2
},
"nodes": [
{ "id": "browser", "label": "Web Browser", "shape": "rectangle" },
{ "id": "api", "label": "API Server", "shape": "rounded_rectangle" },
{ "id": "database", "label": "Database", "shape": "cylinder" }
],
"edges": [
{ "id": "e1", "source": "browser", "target": "api", "label": "HTTPS", "kind": "directed" },
{ "id": "e2", "source": "api", "target": "database", "label": "SQL", "kind": "directed" }
],
"groups": [
{ "id": "backend", "label": "Backend Tier", "node_ids": ["api", "database"] }
],
"options": {
"deterministic": true
}
}See docs/architecture/Schema.md for detailed schema specifications.
Derived from verified repository source files:
sketchwright-mcp/
├── .github/workflows/ci.yml # Cross-platform GitHub Actions CI (Linux, Windows)
├── docs/ # Comprehensive technical documentation suite
│ ├── README.md # Documentation suite index & master navigation map
│ ├── product/ # PRD, user journeys, app flows, and terminology glossary
│ │ ├── PRD.md # Product Requirements Document
│ │ ├── AppFlow.md # State inventory, CLI trees & MCP protocol lifecycles
│ │ └── Glossary.md # Canonical terminology & domain dictionary
│ ├── architecture/ # Technical specs, design tokens, schemas, APIs & ADRs
│ │ ├── TechSpec.md # System design, layout pipeline & C4 architecture
│ │ ├── Design.md # Visual identity & Excalidraw styling tokens
│ │ ├── Schema.md # Canonical specification & Pydantic data models
│ │ ├── API.md # FastMCP tool signatures & CLI contracts
│ │ └── decisions/ # Architecture Decision Records (ADRs)
│ ├── guides/ # Operational runbooks, configurations & user handbooks
│ │ ├── configuration.md # Environment variables & tuning limits
│ │ ├── Deployment.md # Build, release, PyPI publishing & client configs
│ │ ├── troubleshooting.md # Diagnostic procedures & error resolutions
│ │ └── SecurityAndCompliance.md # STRIDE threat model & security boundaries
│ └── development/ # Engineering standards, testing & code quality
│ ├── Rules.md # Engineering guidelines & code quality standards
│ └── testing.md # Test strategy, critical test cases & coverage
├── examples/ # Runnable samples and test fixtures
│ ├── architecture.json # Multi-tier microservice architecture spec
│ ├── flowchart.json # Branching process flowchart spec
│ ├── hello_world.py # Public Python API usage example
│ └── mcp-client-config.example.json # Generic MCP client host config
├── src/sketchwright/ # Core application package
│ ├── engine/ # Diagram generator and update engine
│ ├── excalidraw/ # Excalidraw serializer, validator, and SVG export
│ ├── layout/ # Sugiyama layout, geometry, and stepped routing
│ ├── mcp/ # MCP 2.x server, tools, resources, and prompts
│ ├── models/ # Pydantic v2 schemas and validation models
│ ├── parser/ # Structured JSON and text DSL parsers
│ ├── cli.py # Command-line interface subcommands
│ ├── config.py # Settings and defensive limit management
│ └── logging_config.py # Strict stdio/stderr routing
├── tests/ # Multi-level automated test suite (91 tests)
│ ├── contract/ # MCP protocol and tool discovery tests
│ ├── e2e/ # Subprocess stdio integration tests
│ ├── integration/ # Pipeline execution and determinism tests
│ └── unit/ # Unit tests for CLI, models, layout, and export
├── .env.example # Environment variable template
├── CHANGELOG.md # Version release notes (Keep a Changelog)
├── CONTRIBUTING.md # Contribution guidelines and setup steps
├── LICENSE # MIT License
├── pyproject.toml # Package manifest and tool configuration
└── SECURITY.md # Vulnerability reporting and security architectureSketchwright includes an automated test suite across unit, integration, contract, and end-to-end levels:
# Run the complete test suite (91 tests)
uv run pytest -v
# Run code style and formatting checks
uv run ruff check .
uv run ruff format --check .
# Run static type checking with Mypy in strict mode
uv run mypy src
# Validate package build
uv buildObserved test status: 91 passed in 4.19s (100% pass rate).
Approximate Font Metrics: To avoid heavy binary font rendering dependencies (such as HarfBuzz or FreeType), Sketchwright computes bounding boxes using deterministic character width heuristics. Browser rendering in Excalidraw may show minor visual variations depending on locally installed fallback fonts.
Simplified Edge Routing: Orthogonal stepped routing avoids node interiors and handles backward loops; complex multi-hop obstacle avoidance routes around rank boundaries rather than sub-pixel collision routing.
Manual Host Configuration: MCP client hosts (Claude Desktop, VS Code, Antigravity) require manual registration by appending the server configuration block to their respective configuration files.
Strict Resource Bounds: Limits input payloads to 1 MB (SKETCHWRIGHT_MAX_INPUT_BYTES), 500 nodes (SKETCHWRIGHT_MAX_NODES), 1000 edges (SKETCHWRIGHT_MAX_EDGES), and 256 characters per label (SKETCHWRIGHT_MAX_LABEL_LENGTH).
Filesystem Boundary Isolation: File writes are executed atomically using temporary files followed by atomic replacement. Traversal sequences (../) are detected and rejected. Output directory restrictions can be enforced via SKETCHWRIGHT_ALLOWED_DIR.
Zero Dynamic Code Execution: The codebase contains zero calls to eval, exec, or dynamic module loading.
Protocol Isolation: Standard output (stdout) is strictly reserved for MCP JSON-RPC protocol messages; all application logs and diagnostics are directed exclusively to stderr.
For vulnerability disclosure procedures, see SECURITY.md.
Contributions are welcome. Please read CONTRIBUTING.md for workflow instructions, code standards, and local quality check commands.
All pull requests must pass formatting (ruff format), linting (ruff check), static type analysis (mypy src), and the full test suite (pytest -v).
Distributed under the MIT License. See LICENSE for the full text.
Copyright (c) 2026 Sketchwright Contributors.
Generate an Excalidraw-compatible diagram scene JSON from a structured specification or DSL.
| Name | Required | Description | Default |
|---|---|---|---|
| text_dsl | No | ||
| overwrite | No | ||
| output_path | No | ||
| specification | No | ||
| layout_overrides | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not explain whether files are written to disk via output_path, what overwrite=true does, whether generation is non-destructive by default, or any side effects, permissions, or error behavior.
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 single sentence is front-loaded and free of filler. It is efficient, though its brevity contributes to the under-specification seen in other dimensions.
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 five-parameter generation tool with no annotations and an output schema, this description is too thin. It omits input-mode selection rules, file output behavior, overwrite semantics, and layout override behavior, leaving an agent without enough context to call it safely and correctly.
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 description coverage is 0%, and the description only vaguely maps to two of the five parameters by mentioning a structured specification or DSL. It adds no meaning for overwrite, output_path, or layout_overrides, leaving most parameters undocumented in both schema and description.
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 names a specific verb and resource: generating an Excalidraw-compatible diagram scene JSON from a structured specification or DSL. That is clear enough to distinguish it from layout/export/update siblings in broad terms, though it does not explicitly contrast those alternatives.
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?
It implies two input modes, structured specification or text DSL, but gives no guidance on when to use this tool versus sketchwright_layout_diagram, sketchwright_export_diagram, sketchwright_validate_diagram, or sketchwright_update_diagram. No prerequisites or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export a diagram specification or Excalidraw scene to .excalidraw JSON or standalone .svg.
| Name | Required | Description | Default |
|---|---|---|---|
| scene | No | ||
| format | No | excalidraw | |
| overwrite | No | ||
| output_path | No | ||
| specification | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It mentions formats but does not disclose that this likely writes to disk, how output_path and overwrite behave, what happens if the file exists, or whether either scene or specification must be supplied.
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 front-loaded sentence with no wasted words, and the verb and output formats come early. It is efficient, though its brevity contributes to gaps elsewhere.
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 five-parameter export tool with no annotations and 0% schema description coverage, the description is too thin. It omits input selection rules, overwrite semantics, output_path behavior, and the exact allowed format values.
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 description coverage is 0%, so the description must compensate. It loosely maps 'specification'/'scene' and the two formats, but says nothing about the overwrite flag, output_path, defaults, or the relationship between the five parameters.
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 uses a specific verb ('Export') and resource ('diagram specification or Excalidraw scene') and names the output formats (.excalidraw JSON or .svg). It distinguishes exporting from create/update siblings by implication, but does not explicitly contrast with them.
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?
It states what can be exported but gives no guidance on when to choose export over siblings like sketchwright_validate_diagram or sketchwright_create_diagram. It also does not clarify whether scene or specification is required or how they relate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover Sketchwright's supported shapes, layout algorithms, directions, and resource limits.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. 'Discover' strongly implies a read-only lookup and the listed categories clarify what is returned, but it does not explicitly state side-effect safety, auth requirements, or whether results are cached/static.
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?
A single front-loaded sentence with no redundant phrasing. Every listed capability category adds 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?
For a simple zero-parameter capability-discovery tool with an output schema, the description is nearly complete: it enumerates the capability categories an agent will receive. The main gap is that it does not say how this discovery step should feed into the sibling diagram tools.
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 takes zero parameters, so there is no parameter semantics to explain; the baseline for a zero-parameter tool is 4.
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?
States a specific verb ('Discover') and concrete resources (shapes, layout algorithms, directions, resource limits). It is clearly distinct in kind from the diagram-manipulation siblings, though it does not explicitly name or contrast with them.
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 is only implied by 'Discover' — an agent can infer this is a metadata lookup, but the description does not say when to call it (e.g., before create/layout), when not to, or how it relates to the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate deterministic node positions, bounding boxes, and edge routes for a diagram.
| Name | Required | Description | Default |
|---|---|---|---|
| algorithm | No | ||
| direction | No | ||
| specification | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It helpfully states that the layout is deterministic and enumerates the computed outputs, but it does not clarify whether the operation mutates stored state, requires permissions, or has side effects.
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 front-loaded sentence with no filler. Every phrase contributes to identifying the operation and its computed outputs.
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?
An output schema exists, so return values need not be explained in detail. However, the input schema has a nested specification object and undocumented optional fields, and the description does not provide enough context for an agent to invoke the tool correctly.
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 description coverage is 0%, and the description does not mention any of the three parameters. It says nothing about the required specification object, the optional algorithm parameter, or the optional direction parameter.
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 gives a specific verb, "Calculate," and a specific resource, node positions, bounding boxes, and edge routes for a diagram. It clearly identifies the layout function, though it does not explicitly distinguish itself from siblings such as validate, create, 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 implies that the tool computes diagram layout, but it gives no explicit guidance on when to use it versus create, update, validate, or export. It also does not state prerequisites, ordering, or whether a diagram must already exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Incrementally update an existing diagram specification (add/remove/rename nodes, add/remove edges) and regenerate scene.
| Name | Required | Description | Default |
|---|---|---|---|
| patch | Yes | ||
| overwrite | No | ||
| output_path | No | ||
| specification | Yes | ||
| generate_scene | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. Beyond stating that it updates incrementally and regenerates the scene, it says nothing about how patches are applied (atomic vs partial failure), what 'overwrite' destroys, whether output_path overwrites existing files, or whether permissions/validation are required before a mutation.
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?
One front-loaded sentence with the operation and its supported edits packed into a parenthetical; there is no filler. It is efficient, though the brevity contributes to the specification gaps noted elsewhere.
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 5-parameter mutation tool with nested object schemas, no annotations, and 0% schema description coverage, a single sentence is inadequate. The output schema covers return values, but patch format, overwrite/regeneration semantics, and output_path behavior are all missing.
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 description coverage is 0% and two required parameters are free-form nested objects, so the description must compensate. The parenthetical clarifies patch operations, which helps, but 'overwrite', 'output_path', and 'generate_scene' get no explanation at all, leaving three of five parameters opaque.
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?
It states a specific verb and resource ('Incrementally update an existing diagram specification') and enumerates the operations it supports (add/remove/rename nodes, add/remove edges), which implicitly separates it from sketchwright_create_diagram. However, it never names a sibling or explicitly contrasts create-vs-update, so it falls short of full differentiation.
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?
'Incrementally update an existing diagram' implies you should use this rather than recreating a diagram, but no when-to-use, when-not-to-use, or alternative routing (e.g. validate before/after, or layout after) is stated. The distinction from create_diagram is inferable but not spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a diagram specification or an Excalidraw scene JSON for schema conformance and bindings.
| Name | Required | Description | Default |
|---|---|---|---|
| scene | No | ||
| specification | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It states that validation covers schema conformance and bindings, but it does not disclose whether the operation is read-only, what happens on invalid input, whether errors are thrown or returned, or what side effects, if any, occur. Those gaps matter for an agent deciding how to handle the result.
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 front-loaded sentence that states the action, the inputs, and the validation criteria without any filler. Every element earns its place and the agent can read the core purpose immediately.
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?
An output schema exists, so the description does not need to explain return values. However, with no annotations and 0% schema description coverage, the description should clarify the relationship between the two optional parameters, such as whether one is required and how to choose between them. It is adequate but leaves important invocation details implicit.
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 description coverage is 0%, so the description must compensate. It does add meaning by mapping the two schema properties to 'diagram specification' and 'Excalidraw scene JSON', which is more informative than the bare 'specification' and 'scene' titles. However, it does not clarify that both parameters are optional, whether at least one should be provided, or whether they are mutually exclusive.
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 uses a specific verb, 'Validate', and names the two resource forms it handles: a diagram specification and an Excalidraw scene JSON. It also specifies what is checked, 'schema conformance and bindings', so the tool's function is clear, though it does not explicitly differentiate itself from sibling tools such as create, update, or layout.
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 gives no explicit guidance on when to use this tool versus siblings like sketchwright_create_diagram, sketchwright_update_diagram, or sketchwright_layout_diagram. It implies validation of a spec or scene but does not state when validation should be performed, whether it is a prerequisite for another operation, or 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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0sketchwright_create_diagramsketchwright_export_diagramsketchwright_get_capabilitiessketchwright_layout_diagramsketchwright_update_diagramsketchwright_validate_diagramScored across 6 tools
Each tool maps to a distinct stage in the diagram lifecycle: create, layout, update, validate, export, and capability discovery. The boundaries between create and layout are clarified by their descriptions, so an agent can reliably choose the right operation.
All tool names use the same sketchwright_ prefix followed by a consistent verb_noun pattern in snake_case. There are no mixed conventions or vague standalone verbs.
Six tools is well-scoped for a diagram generation server, covering creation, layout, updating, validation, export, and discovery without redundancy. Each tool has a clear, non-overlapping role.
The surface covers the core diagram lifecycle from specification creation through validation and export, including incremental updates and capability discovery. Minor gaps exist around persisted diagram management (e.g., listing or deleting saved diagrams), but these are not essential for the stated purpose.
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
Polished system design diagrams (SVG/PNG) from a tiny YAML spec, ~18x fewer tokens than raw SVG.
AI agent draws editable hand-drawn diagrams (flowchart, ER, architecture) via MCP, not static images
Create, edit and organize hand-drawn diagrams (flowcharts, ER, architecture) from any AI agent.