Draws hand-drawn Excalidraw diagrams, with scenes stored as real .excalidraw files that can be opened and further edited in Excalidraw (the bundled library app or excalidraw.com). Built on the official @excalidraw/excalidraw canvas, it lets an agent create and modify elements (boxes, arrows, text, generated shapes like polygons and stars, imported SVG), read its own work back structurally (describe_scene, check_scene) or visually (render_scene as PNG), and undo its writes via snapshots.
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., "@sketchdex draw me how a web request flows through a server"
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.
Give your agent a whiteboard. sketchdex.dev
Sketchdex is an MCP server that lets Claude, Codex, Cursor and any other MCP
client draw hand-drawn Excalidraw diagrams while it explains something. Scenes
are real .excalidraw files in a folder on your machine. The agent can draw,
look at what it drew, and fix it; you can open the result in the bundled
library app or on excalidraw.com and keep editing.
Built on the official @excalidraw/excalidraw package, so the canvas is the
real thing. MIT.
Needs Node 20 or newer. Rendering (render_scene) needs a Chromium-based
browser on the machine: Chrome, Chromium, Edge or Brave. Everything else works
without one.
The quickest way is to let the agent you already have do it. Paste this into any agent that can run commands:
install the sketchdex mcp server for me. run
npx -y sketchdex docs installfor the steps.
Or by hand:
Claude Code
claude mcp add --scope user sketchdex -- npx -y sketchdexCodex
codex mcp add sketchdex -- npx -y sketchdexCursor
Add to Cursor, or in ~/.cursor/mcp.json:
{
"mcpServers": {
"sketchdex": {
"command": "npx",
"args": ["-y", "sketchdex"]
}
}
}VS Code
code --add-mcp '{"name":"sketchdex","command":"npx","args":["-y","sketchdex"]}'Claude Desktop, Windsurf, Gemini CLI, anything else takes the same
mcpServers block as Cursor, or the command npx -y sketchdex as a stdio
server. npx -y sketchdex docs install has the exact file for each.
Then, in a session: draw me how the event loop works using sketchdex.
Scenes are saved to ~/Documents/sketchdex. Point them somewhere else with
--vault /path/to/folder after the package name, or SKETCHDEX_VAULT in the
server's environment. An iCloud or Dropbox folder works.
Related MCP server: excalidraw-mcp
The manual ships inside the package so an agent can answer setup questions and fix problems without anyone reading a page:
npx -y sketchdex docs [topic] prints it (topics: install, vault,
app, rendering, tools, drawing, troubleshooting, or all).
The sketchdex_docs tool returns the same text once the server is
connected, and the server instructions tell the agent to use it for
anything about setup or errors.
The same topics are MCP resources at sketchdex://docs/<topic>.
npx sketchdex appOpens the library in your browser: a grid of scenes with live previews,
search, pin, rename, duplicate, import; a full Excalidraw editor for each; a
⌥K switcher; and a History sidebar showing every agent write with the
label the agent gave it, so you can preview, keep or revert each one. The app
notices agent writes as they happen.
The same process serves the tools over HTTP at POST /mcp and as plain REST at
POST /api/agent/:op, localhost only.
Nineteen tools over stdio. The ones that matter:
Tool | Does |
| Structure, not pixels: bounds, counts, a rounded summary per element. Start here. |
| Boxes, arrows, text, generated shapes ( |
| One id and the fields that change. The read-modify-write happens server-side, so a two-line edit costs two lines. |
| Write an SVG, get hand-drawn editable elements grouped as one piece. The way to draw anything that has to look like something. |
| A real canvas render as PNG, whole scene or a region, so the agent can look at its own work. |
| Layout problems found by geometry: hidden text, overlapping labels, dangling arrows, strays. |
| The safety net. Every write snapshots the previous state first. |
| The manual by topic, so the agent can answer setup questions and fix errors itself. |
The full manual the agent reads is BRIEF.md: the element format,
the hand-drawn contract (roughness, sparse anchors, flat colour, no clip-art),
paper and ink rules, and the things that will bite.
Files are the truth. Every scene is a plain .excalidraw file. Atomic
writes (temp file, rename), deletes go to trash/, and index.json is a
cache the server rebuilds from the files if it is lost.
Every agent write is undoable. Snapshots are gzipped, capped at 20 per scene, images excluded, and never expire on their own.
Deltas, not rewrites. Edits you make in the editor while the agent works survive: writes carry a revision token and conflicting saves are merged.
Local only. No account, no upload, no telemetry. The server binds 127.0.0.1.
~/Documents/sketchdex/
├── index.json names, timestamps, pins (a cache, not the truth)
├── scenes/<id>.excalidraw the scene itself, real Excalidraw format
├── thumbs/<id>.svg library previews
├── history/<id>/ snapshots taken before agent writes, gzipped
└── trash/<stamp>-<id>.excalidrawimport { createAgentApi } from "sketchdex";
const api = createAgentApi(); // or createAgentApi("/path/to/vault")
await api.describeScene("Brain Dump");Same implementation as the MCP and REST surfaces. Works with the app closed.
git clone https://github.com/lucasr1b/sketchdex
cd sketchdex
npm install # also retunes Excalidraw's colour picker for dark paper
npm run dev # app + API + HTTP MCP on http://localhost:5173
npm run build # dist/, which the CLI and the render page need
node bin/sketchdex.js appFor an MCP client pointed at a checkout, use node /path/to/sketchdex/mcp/server.js
as the command. In a checkout the server hot-reloads its worker when a file
under server/ or mcp/ changes, so edits are live on the next tool call
without restarting the client.
npm run lint, npx tsc -p tsconfig.app.json --noEmit and npm test before
committing. The test packs the package, installs it into a clean project and
drives it through a real MCP client, including a render; CI runs it on macOS,
Linux and Windows.
AGENTS.md maps the codebase and the rules that must survive
edits. There is also a macOS desktop shell: npm run electron:dev.
New scenes are dark paper (#121212) and nothing is ever colour-inverted:
the canvas, thumbnails and renders show every hex exactly as written. Paper
colour is per scene (viewBackgroundColor).
The first render on a fresh install takes a few seconds while the browser starts; after that about a second and a half.
Set SKETCHDEX_BROWSER=/path/to/browser if the browser is somewhere unusual.
The server only answers requests whose Host is localhost and refuses cross-site writes, so a web page open in your browser cannot touch the vault. It still binds a plain local port: anything running as you on the same machine can reach it, which is the point.
In the app, ⌘K opens the scene switcher, which shadows Excalidraw's own
"add link" shortcut; use the context menu for links.
The app registers a small service worker (for install-as-app). It does no caching, but if you run another project on the same port later it will show up in that project's devtools until you unregister it.
Append elements to a scene, leaving everything already there untouched. The usual way to draw something new.
| Name | Required | Description | Default |
|---|---|---|---|
| label | Yes | Short description of what this change is doing, e.g. 'add the dog illustration'. Shown next to the snapshot in the history sidebar, which is how the user decides whether to keep or revert it. Always set it. | |
| scene | Yes | Scene id, exact name, or a unique part of the name. Use list_scenes if unsure. | |
| elements | Yes | Excalidraw elements. Any field of a real element is honoured verbatim; what you omit gets a valid default (id, index, seed, version are generated). USE THIS FOR diagrams, layout, text, boxes, arrows, and detail strokes on top of something already drawn. For anything that has to LOOK LIKE something - a character, creature, object, vehicle, logo, illustration - do NOT assemble it from shapes here. Write it as one SVG and call import_svg. Shapes stacked by hand come out as a pile of parts (fat, seamed, toy-like) every time; one SVG comes out as one drawing. Types: rectangle ellipse diamond arrow line text freedraw frame. Fields: x y width height angle, strokeColor, backgroundColor (the fill), fillStyle solid|hachure|cross-hatch, strokeWidth 1|2|4, strokeStyle, roughness 0|1|2, opacity, roundness, fontSize, fontFamily (5 hand-drawn), textAlign, groupIds, points [[0,0],[dx,dy],...] relative. y points down. TEXT WRAPS: give a text element a `width` and prose is wrapped to it with the real font metrics (height follows); no width = one line per \n, sized exactly. Never break long paragraphs by hand. THE LOOK IS HAND-DRAWN. This is Excalidraw. roughness 1 (default) on everything; native rectangle/ellipse/arrow rather than 4-point lines; sparse points with roundness {type:2} for a curve (dense points look furry, not sketchy); hand-drawn font. Detail is a few extra strokes, never more parts. COLOUR IS FLAT. Solid fills, one colour per part, and the wobbly outline does the rest - that is the Excalidraw look. Do not shade: no hachure or cross-hatch as texture, no gradients faked with stacked shapes, no drop shadows. If a part must read as darker, give it a darker solid hex. Reserve hachure/cross-hatch for something that IS hatched (a cutaway, a glass pane). PAPER AND INK. Nothing is inverted for display: every hex shows exactly as written. New scenes are dark paper (#121212). Anything drawn without a strokeColor gets ink that contrasts with the paper (#e9ecef on dark, #1e1e1e on light); describe_scene reports `background` and `ink`. Any hex is fine - character colours are character colours on any paper. SHORTHAND. label on a shape adds centred bound text; ref names an element and start/end on an arrow bind to it. Generated geometry is an element whose type is polygon|star|arc|capsule|path, e.g. {"type":"path","points":[[0,0],[40,30],[90,10]],"closed":true} smooth curve through the points polygon {sides,cx,cy,r} star {points,cx,cy,r,innerRatio} arc {cx,cy,r,from,to} capsule {x,y,width,height,radius} repeat {count,dx,dy | cols,rows | around:{cx,cy}} and mirror {axis:'vertical',at} multiply one spec evenly. These are for furniture - rings, plates, arrays - not for bodies. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it does disclose the key trait: this operation is additive and leaves existing content untouched. It says nothing about permissions, history/snapshot implications, or failure modes for an invalid scene id, so disclosure is partial but meaningful.
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?
Two short sentences with zero waste, front-loading the action and then the distinguishing non-destructive property. Nothing repeats the name or pads the text.
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 complex drawing tool the description is deliberately thin, but the exceptionally rich elements schema covers types, defaults, styling conventions, and import_svg routing, and no output schema exists to explain. The only real gap is the absence of any note on what the call returns or how the change appears in history.
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 100%, so the schema already documents label, scene, and the elements array in depth. The top-level description adds no parameter syntax or format detail beyond that, which is exactly the baseline-3 case where structured fields do the heavy lifting.
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?
Specific verb plus resource ('Append elements to a scene') with an explicit non-destructive qualifier ('leaving everything already there untouched'). That qualifier cleanly separates it from siblings like update_elements, replace_scene, and delete_elements, so an agent can pick it without opening another schema.
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 usual way to draw something new' implies this is the default entry point for adding content, which is useful framing. However, the description itself gives no explicit when-not conditions or named alternatives; the important routing guidance (use import_svg for anything that must look like a character/object) lives in the schema text, not here.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find layout problems by geometry instead of by looking: text hidden behind a filled shape drawn after it, captions running past the panel they sit in, labels too tall for their container, zero-size elements, broken arrow bindings, strays parked far off, exact duplicates. Each finding carries the element ids, so the fix is one update_elements call. Run it after a batch of drawing - it is far cheaper than a render and catches what a render would only show you if you looked closely.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max findings (default 60). | |
| scene | Yes | Scene id, exact name, or a unique part of the name. Use list_scenes if unsure. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the burden and does so well: it discloses the diagnostic (non-mutating) nature, the return shape ('each finding carries the element ids'), and the cost model relative to rendering. It does not state any permission or rate-limit caveats, but for a read-only analysis tool this covers the essentials.
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?
Front-loaded with the core purpose, then the finding list, then the workflow advice. The example enumeration is long but each entry is a distinct, useful category rather than filler. Minor length, no wasted sentences.
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, so the description correctly notes the return content (element ids) and the follow-up action. Combined with fully documented params, an agent has what it needs to invoke and act on results; only cost/limit edge behavior is left 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 100%, so both parameters (scene, limit) are already documented, including the default of 60 and the list_scenes fallback. The description adds no parameter-level syntax or format detail, so the baseline of 3 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?
States a specific verb (find) and resource (layout problems, by geometry), and enumerates concrete finding classes (occluded text, overflowing captions, oversized labels, zero-size elements, broken arrow bindings, strays, duplicates). An agent can immediately distinguish it from render_scene and update_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?
Gives clear timing ('Run it after a batch of drawing') and a direct alternative comparison ('far cheaper than a render'). It names update_elements as the remediation path. No explicit when-not guidance, but the context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Make a new scene, optionally with its starting elements.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| elements | No | Excalidraw elements. Any field of a real element is honoured verbatim; what you omit gets a valid default (id, index, seed, version are generated). USE THIS FOR diagrams, layout, text, boxes, arrows, and detail strokes on top of something already drawn. For anything that has to LOOK LIKE something - a character, creature, object, vehicle, logo, illustration - do NOT assemble it from shapes here. Write it as one SVG and call import_svg. Shapes stacked by hand come out as a pile of parts (fat, seamed, toy-like) every time; one SVG comes out as one drawing. Types: rectangle ellipse diamond arrow line text freedraw frame. Fields: x y width height angle, strokeColor, backgroundColor (the fill), fillStyle solid|hachure|cross-hatch, strokeWidth 1|2|4, strokeStyle, roughness 0|1|2, opacity, roundness, fontSize, fontFamily (5 hand-drawn), textAlign, groupIds, points [[0,0],[dx,dy],...] relative. y points down. TEXT WRAPS: give a text element a `width` and prose is wrapped to it with the real font metrics (height follows); no width = one line per \n, sized exactly. Never break long paragraphs by hand. THE LOOK IS HAND-DRAWN. This is Excalidraw. roughness 1 (default) on everything; native rectangle/ellipse/arrow rather than 4-point lines; sparse points with roundness {type:2} for a curve (dense points look furry, not sketchy); hand-drawn font. Detail is a few extra strokes, never more parts. COLOUR IS FLAT. Solid fills, one colour per part, and the wobbly outline does the rest - that is the Excalidraw look. Do not shade: no hachure or cross-hatch as texture, no gradients faked with stacked shapes, no drop shadows. If a part must read as darker, give it a darker solid hex. Reserve hachure/cross-hatch for something that IS hatched (a cutaway, a glass pane). PAPER AND INK. Nothing is inverted for display: every hex shows exactly as written. New scenes are dark paper (#121212). Anything drawn without a strokeColor gets ink that contrasts with the paper (#e9ecef on dark, #1e1e1e on light); describe_scene reports `background` and `ink`. Any hex is fine - character colours are character colours on any paper. SHORTHAND. label on a shape adds centred bound text; ref names an element and start/end on an arrow bind to it. Generated geometry is an element whose type is polygon|star|arc|capsule|path, e.g. {"type":"path","points":[[0,0],[40,30],[90,10]],"closed":true} smooth curve through the points polygon {sides,cx,cy,r} star {points,cx,cy,r,innerRatio} arc {cx,cy,r,from,to} capsule {x,y,width,height,radius} repeat {count,dx,dy | cols,rows | around:{cx,cy}} and mirror {axis:'vertical',at} multiply one spec evenly. These are for furniture - rings, plates, arrays - not for bodies. |
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 does disclose useful behavioral context inside the parameter docs — omitted element fields get valid defaults, id/index/seed/version are generated, new scenes default to dark paper (#121212) with contrasting ink. However, it says nothing about what happens to the current scene, whether the new scene becomes active, what identifier is returned, or any permission requirements.
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 tool-level description is a single, front-loaded sentence with no waste, and the scoping word 'optionally' is placed where it matters. It is arguably too lean for a creation tool, but as prose it is efficient and correctly ordered.
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 no-output-schema, no-annotation creation tool, the definition leaves gaps an agent cares about: what is returned, whether the scene becomes active, and how this differs from replace_scene. The abundant element-building guidance covers the how, but not the after-effects, so it is adequate rather than 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 50%: `elements` is documented exhaustively in the schema (types, fields, defaults, coordinate conventions, text wrapping), while `name` is undocumented in both schema and description. The description only conveys that `elements` is optional; it adds nothing about `name`, so it does not compensate for the coverage gap.
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+resource (make a new scene) and adds scope information — the scene may be created empty or seeded with elements. It is clear on its own, but it does not distinguish itself from siblings like replace_scene, add_elements, or import_svg, which an agent choosing among 18 tools would want.
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 top-level sentence gives no when-to-use guidance or alternatives. The `elements` property description does contain real routing advice (assemble shapes here for diagrams/layout, but use import_svg for anything that must look like a character/object/logo), which partially compensates, but nothing tells the agent when to create a scene versus replacing or adding to an existing one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove elements by id.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | ||
| label | Yes | Short description of what this change is doing, e.g. 'add the dog illustration'. Shown next to the snapshot in the history sidebar, which is how the user decides whether to keep or revert it. Always set it. | |
| scene | Yes | Scene id, exact name, or a unique part of the name. Use list_scenes if unsure. |
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 and supplies almost nothing: it does not say the removal is destructive or irreversible, whether a snapshot/history entry is created, whether the provided label hooks into restore_snapshot, or what happens on a bad id. One sentence covering only the mechanical action is far short of what a delete tool needs.
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 filler or redundancy. It is efficient, though its brevity here reflects under-specification rather than disciplined editing.
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 required-parameter destructive operation with no annotations and no output schema, the description omits the essentials: reversibility, snapshot/label consequences, and behavior on missing or invalid ids. An agent could call it, but not safely.
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 67%: 'label' and 'scene' have solid schema descriptions, and the description's 'by id' at least clarifies the ids array's role. With parameters mostly self-documenting in the schema, this is a baseline adequate score, but the description adds no format or behavioral detail about the identifiers 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 states a specific verb and resource ('Remove elements') plus the selection mechanism ('by id'), so an agent knows exactly what the tool does. It does not, however, contrast itself with the many similar siblings (add_elements, move_elements, update_elements, replace_scene), leaving that differentiation to the tool names.
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?
There is no guidance on when to reach for this tool versus update_elements or replace_scene, nor any prerequisite or exclusion. The agent must infer usage purely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What is on a scene, as structure rather than pixels: counts by type, overall bounds, and a rounded summary of each element with its id, position, size, text and bindings. Cheaper than read_scene and usually enough to plan an edit.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Only elements of this type. | |
| limit | No | Max elements to list (default 400). | |
| scene | Yes | Scene id, exact name, or a unique part of the name. Use list_scenes if unsure. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, and it does disclose the return shape: counts by type, bounds, and per-element id/position/size/text/bindings. It does not mention read-only guarantees, permissions, or output limits/pagination 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?
Two sentences, front-loaded with what the tool returns and followed by the cost/alternative rationale. Every clause earns its place 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 read tool with no annotations and no output schema, the description compensates well by enumerating the returned fields and cost tradeoff. It is nearly complete, missing only explicit read-only confirmation and any note on result size limits beyond the schema's limit default.
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 100%, so all three parameters (type filter, limit default 400, scene identifier) are already documented in the schema. The description adds no format or semantic detail beyond what the schema provides, matching the baseline for full 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?
States a specific verb (describe) and resource (scene) and immediately qualifies the output as structural rather than pixel data. It is clearly distinguishable from siblings like read_scene and render_scene.
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 routes against the closest alternative: 'Cheaper than read_scene and usually enough to plan an edit' tells the agent when this is preferable. It stops short of stating when read_scene is required instead, so there is no explicit exclusion condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Draw by writing SVG. THE way to draw anything that has to look like something: a character, creature, object, vehicle, logo, illustration. This is what produces good figures; stacking shapes with add_elements does not.
The result is hand-drawn, not pasted: every path becomes a real editable Excalidraw element (grouped as one piece), curves are re-spaced to hand-sized strokes and drawn with the sketchy pen, // become native shapes. Write the SVG for SHAPE, PROPORTION and COLOUR and let the canvas supply the pen - do not fake wobble or hatching in the SVG.
A recipe that works for a figure:
viewBox about 300 x 600 for a standing figure; import at width 350-450.
ONE closed path per body region - torso, each leg, each arm - tapered like a real limb (forearm ~60% of the upper arm, calf into a narrow ankle), plus head, hands, feet. Let them overlap; later paths draw on top. Then detail as separate strokes OVER the silhouette: plates, seams, webbing, a knee line. A few, not many.
Every shape: fill=<vibrant, character-accurate hex> stroke=<the scene ink from describe_scene, or a deep shade of the fill> stroke-width 2 to 2.5. Filled shapes with no stroke read as flat.
Flat colour, no shading. One solid fill per part; a darker part is a darker hex, not a hatched overlay or a shadow shape. The sketchy outline carries the drawing - texture on top of it looks overworked.
Proportion from a rule: 7-8 heads tall for heroic, 5-6 for stylised. Head first, derive the rest.
Then render_scene and LOOK; fix what is off. The first pass is usually mis-proportioned, the second is right.
Supported: path (all commands), rect, circle, ellipse, line, polyline, polygon, g, transform, /class, /, presentation attributes, text. viewBox honoured exactly. Gradients flatten to their first stop; pass holeColor to punch compound-path holes.
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | Where to place it on the canvas. Default 0. | |
| y | No | Default 0. | |
| svg | Yes | Complete SVG markup, including the <svg> element and its viewBox. | |
| step | No | Anchor spacing for curves in sketch mode, in canvas px. Default 18. Lower keeps more of the source curve; higher is looser. | |
| group | No | Group the result as one unit. Default true. | |
| label | Yes | Short description of what this change is doing, e.g. 'add the dog illustration'. Shown next to the snapshot in the history sidebar, which is how the user decides whether to keep or revert it. Always set it. | |
| scene | Yes | Scene id, exact name, or a unique part of the name. Use list_scenes if unsure. | |
| style | No | sketch (default): hand-drawn treatment - anchors re-spaced, curves as curves, roughness 1, native circles/rects. precise: every flattened vertex kept, roughness 0 - for a logo or a drawing that must be exact. | |
| width | No | Scale the artwork to this width, keeping its aspect ratio. Height follows. | |
| height | No | Optional bound on height. | |
| fillStyle | No | Fill for every filled shape. Default solid. hachure for a lighter, sketchier piece (small shapes stay solid); cross-hatch for weight. | |
| holeColor | No | Backdrop colour used to punch compound-path holes. | |
| roughness | No | 0 precise, 1 sketchy (default in sketch mode), 2 very sketchy. | |
| tolerance | No | Curve flattening, in source units. Default 3. Lower is smoother and heavier. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so: paths become real editable Excalidraw elements grouped as one piece, curves are re-spaced to hand-sized strokes, circle/ellipse/rect become native shapes, gradients flatten to their first stop, and viewBox is honoured exactly. The label/snapshot note also discloses reversibility context.
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 lead sentence is front-loaded and states the core value before the recipe. The body is long, but the bulleted recipe is dense and task-relevant rather than filler, so it earns most of its length for a complex drawing tool.
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 14-parameter mutation tool with no output schema, the description covers the workflow and result behavior thoroughly, and the schema already documents all parameters. Minor gap: it never states permissions or limits, though those are less relevant for a local canvas 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 baseline is 3, but the description adds real meaning beyond the schema: concrete guidance on import width (350-450), how style modes behave (sketchy pen vs exact), and the holeColor compound-path hole behavior. It does not restate every parameter, leaving step/tolerance to 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?
Claims a specific verb+resource ('Draw by writing SVG') and immediately scopes it ('anything that has to look like something: a character, creature, object, vehicle, logo, illustration'). It also differentiates from the sibling add_elements by name, saying stacking shapes 'does not' produce good figures.
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 routes the agent: use import_svg for representational drawing, not add_elements for shape-stacking. It adds a full when/how recipe (viewBox sizing, one path per body region, stroke rules, proportion rule) plus the render_scene-and-look loop.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Snapshots held for a scene, newest first.
| Name | Required | Description | Default |
|---|---|---|---|
| scene | Yes | Scene id, exact name, or a unique part of the name. Use list_scenes if unsure. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does disclose a genuine trait beyond structured fields – results are ordered newest first – which is useful for an agent reasoning about snapshot recency. However, it says nothing about read-only safety, result limits, pagination, or whether an empty history is possible.
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 sentence with zero filler that front-loads the resource and appends the ordering constraint. Nothing in it is redundant with the name or schema.
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 one-parameter, no-output-schema listing tool, the description covers what is returned and in what order, which is most of what an agent needs. Minor gaps remain around result volume and whether history can be empty, but the core contract is clear.
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 100% and the single 'scene' parameter is fully documented in the schema, including fallback advice to use list_scenes. The description adds no syntax, format, or matching semantics beyond what the schema already provides, so the baseline 3 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?
States the resource (snapshots held for a scene) and the ordering (newest first), so an agent knows this is a listing/read of snapshot history. It does not explicitly contrast itself with sibling tools like snapshot_scene or restore_snapshot, but the verb/resource pairing is unambiguous.
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?
No guidance on when to call this versus snapshot_scene or restore_snapshot, which are the obvious adjacent actions. The 'Use list_scenes if unsure' hint lives in the schema, not the description, and concerns parameter resolution rather than tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every scene in the vault with its id, name, element count and last-edited time. Start here.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses the shape of the result (four metadata fields per scene), which stands in for the absent output schema, but says nothing about volume, pagination, or permissions for a tool that returns 'every scene in the vault'.
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?
Two short sentences, zero waste, with the return fields front-loaded before the routing hint. Nothing could be cut without losing 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 zero-param discovery tool with no output schema, describing the returned fields is the essential missing piece and it is supplied. Only the behavior at scale (many scenes) and the read-only nature are left 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?
The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool 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?
States a clear verb+resource (list scenes) and enumerates the returned fields (id, name, element count, last-edited time), which implicitly separates it from read_scene and describe_scene, which operate on a single scene. It stops short of naming those siblings explicitly.
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?
"Start here" implies this is the orientation/discovery entry point, but no when-to-use or when-not guidance is given, and no alternative is named (e.g. use read_scene once you have an id). Usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Shift a set of elements by dx, dy in one write, keeping everything else about them. Select by ids, groupIds (an import_svg piece), a region box, or any mix. A container's label always moves with it, and an arrow bound to something that moves keeps that end attached (include the arrow itself to move it whole). Returns the new bounds of what moved.
| Name | Required | Description | Default |
|---|---|---|---|
| dx | No | Scene px to the right (negative = left). | |
| dy | No | Scene px down (negative = up). | |
| ids | No | ||
| label | Yes | Short description of what this change is doing, e.g. 'add the dog illustration'. Shown next to the snapshot in the history sidebar, which is how the user decides whether to keep or revert it. Always set it. | |
| scene | Yes | Scene id, exact name, or a unique part of the name. Use list_scenes if unsure. | |
| region | No | Everything overlapping this box moves. | |
| groupIds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses atomicity ('in one write'), preserved properties ('keeping everything else about them'), the label-follows-container side effect, the arrow-binding behavior (end stays attached, include the arrow to move it whole), and the return value (new bounds). It omits permission/auth requirements and what happens on out-of-bounds moves, keeping it from a 5.
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?
Three dense sentences, front-loaded with the core action and its atomicity. Every clause adds information — selection modes, side effects, return value — with no filler or restatement of the name.
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 7-parameter mutation tool with a nested region object and no output schema, the description covers selection, side effects, and return shape ('new bounds'), which is the key omission filled since no output schema exists. It is silent on the required 'label' history semantics (delegated to the rich schema) and on default behavior when dx/dy are omitted, a modest remaining gap.
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 71% and the description adds real meaning on top: it enumerates the four selection modes (ids, groupIds as an import_svg piece, region box, any mix) and clarifies the arrow-inclusion nuance for moving bound arrows whole. It does not restate dx/dy direction, which the schema already covers well.
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 (Shift), the exact mechanism (by dx, dy), the atomicity (in one write), and the scope (a set of elements). The dx/dy translation semantics inherently distinguish it from update_elements without needing to name the sibling.
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 explains HOW to select targets (ids, groupIds, a region box, or any mix), which is genuine selection guidance, but never states when to reach for this tool versus update_elements or add_elements/delete_elements, nor any when-not condition. Usage is implied by the 'move by translation' framing rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full, unabridged elements, filtered down to the ones you need. Use this rather than read_scene when editing a few things in a busy scene.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | ||
| type | No | ||
| limit | No | Default 100. | |
| scene | Yes | Scene id, exact name, or a unique part of the name. Use list_scenes if unsure. | |
| region | No | Only elements overlapping this box. | |
| contains | No | Only elements whose text contains this. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry behavioral weight. 'Full, unabridged' usefully signals it returns complete element data rather than a summary, but it says nothing about the default limit of 100, truncation/pagination behavior, or what happens when filters match nothing.
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?
Two short sentences, zero filler, and the distinguishing capability is front-loaded before the alternative-tool routing advice.
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 six-parameter tool with no annotations and no output schema, the description adequately covers output nature ('full, unabridged') and tool selection, but leaves limit/truncation semantics and multi-filter interaction unaddressed.
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 67%, so ids/type/limit/scene/region/contains are largely self-documented in the schema. The description only alludes to filtering generically ('filtered down to the ones you need') and adds no syntax, format, or interaction detail 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 tells the agent it returns full, unabridged elements narrowed by filters, and it explicitly names the sibling it supersedes (read_scene). The verb is implicit in the tool name rather than stated, but the resource and scope are unambiguous.
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 gives a concrete condition for choosing this over read_scene: 'when editing a few things in a busy scene.' That is real routing guidance, though it doesn't cover when read_scene is preferable (e.g., whole-scene inspection) or mention describe_scene as another alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The whole scene exactly as stored, plus the path to the .excalidraw file on disk. Large scenes run to thousands of elements, so prefer describe_scene or read_elements unless you genuinely need everything. The path is there for edits no tool here covers - take a snapshot first if you use it.
| Name | Required | Description | Default |
|---|---|---|---|
| scene | Yes | Scene id, exact name, or a unique part of the name. Use list_scenes if unsure. | |
| includeFiles | No | Include the embedded image map. Off by default: it is base64 and usually megabytes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the size/performance characteristic ('thousands of elements'), the returned artifact (on-disk path), and a mutation risk with a mitigation ('take a snapshot first'). It stops short of stating that the call itself is a pure read or describing pagination/output shape, so not fully complete, but materially richer than the structured data.
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?
Three sentences, each doing distinct work: return content, alternative routing, and the edit/snapshot caveat. Front-loaded with the core return value, though the opening sentence is a fragment and could be tightened slightly.
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 states what comes back (full scene plus file path) and warns about volume, which is what an agent needs. The remaining gap is that it never explicitly confirms the call is side-effect-free, which matters given the absence of annotations.
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 100%, so both parameters (scene and includeFiles) are already documented in the schema, including the base64/megabyte rationale for includeFiles. The description adds no parameter-level syntax or format detail beyond that, so baseline 3 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?
Names a specific operation and resource ('the whole scene exactly as stored, plus the path to the .excalidraw file on disk'), and explicitly distinguishes itself from the describe_scene and read_elements siblings by framing them as the lighter-weight alternatives. An agent can tell it apart without opening any schema.
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?
Gives explicit when-to-use guidance ('prefer describe_scene or read_elements unless you genuinely need everything'), names the condition that selects those alternatives (large scenes), and adds a safe-use rule ('take a snapshot first if you use it') for out-of-band editing. Both the selection path and the safety caveat are spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A PNG of the scene as it actually renders, so you can look at what you drew. Use it to check your own work - proportions, overlaps, whether the thing reads as the thing. Always written to a file as well as returned. A tall or wide page (long edge more than about twice the short one, and too big to fit at the asked size) comes back as a few tiles cut along its length, each with the scene box it shows, so a whole board is readable in one call; a region renders just that box, which is the way to look closely at one part. When an image is too big to travel inline you get a downscaled preview plus the file path.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | Render only these elements. | |
| scale | No | Pixel density, 1-3. Default 1. | |
| scene | Yes | Scene id, exact name, or a unique part of the name. Use list_scenes if unsure. | |
| tiles | No | Split the picture into this many tiles along its long axis (max 8). Default: chosen from the shape of the scene, 1 for anything roughly square. Pass 1 to force a single image. | |
| region | No | Render only what overlaps this box, in scene coordinates. Take the numbers from describe_scene's `bounds`. | |
| maxWidth | No | Cap the long edge in pixels. Default 1400. Above ~1200 the result is a file path instead of an inline image. | |
| transparent | No | Leave the paper out of the PNG (alpha background). For dropping a sketch onto a slide or a page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, and it discloses substantial behavior: output is always written to a file as well as returned, tall/wide pages are auto-tiled along the long axis with scene boxes, and oversized images degrade to a downscaled preview plus file path. It omits cost/latency and any error or permission behavior, so not quite exhaustive.
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?
Front-loads the core purpose in the first sentence, then layers on output/behavior details. It is somewhat dense and chatty with parenthetical asides, but every sentence conveys actionable information about output shape, so nothing is truly wasted.
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?
With 7 parameters, a nested object, no output schema, and no annotations, the description does the heavy lifting on return behavior (inline image vs. file path, tiling, preview downscale), which compensates for the missing output schema. Gaps remain around failure modes and permission/precondition behavior, but for a read-only render tool the coverage is strong.
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, but the description adds genuine meaning beyond the schema by explaining why `tiles` exists (long pages split for readability) and the practical consequence of `maxWidth` (above ~1200 you get a path instead of an inline image). It also frames `region` as the close-up mechanism rather than just a bounding box.
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 concrete verb+resource ('A PNG of the scene as it actually renders') and immediately frames the intent ('so you can look at what you drew'), which separates it from sibling validation/inspection tools like check_scene or describe_scene. An agent knows this is the visual-render tool, not a text or validation 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?
Gives clear usage context ('Use it to check your own work - proportions, overlaps, whether the thing reads as the thing') and steers to `region` for close inspection. It does not explicitly name or exclude sibling alternatives (check_scene, snapshot_scene), so this falls just short of the top bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace a scene's entire contents. Destructive by design - the previous state is snapshotted, but prefer add_elements or update_elements when you only mean to change part of it.
| Name | Required | Description | Default |
|---|---|---|---|
| label | Yes | Short description of what this change is doing, e.g. 'add the dog illustration'. Shown next to the snapshot in the history sidebar, which is how the user decides whether to keep or revert it. Always set it. | |
| scene | Yes | Scene id, exact name, or a unique part of the name. Use list_scenes if unsure. | |
| elements | Yes | Excalidraw elements. Any field of a real element is honoured verbatim; what you omit gets a valid default (id, index, seed, version are generated). USE THIS FOR diagrams, layout, text, boxes, arrows, and detail strokes on top of something already drawn. For anything that has to LOOK LIKE something - a character, creature, object, vehicle, logo, illustration - do NOT assemble it from shapes here. Write it as one SVG and call import_svg. Shapes stacked by hand come out as a pile of parts (fat, seamed, toy-like) every time; one SVG comes out as one drawing. Types: rectangle ellipse diamond arrow line text freedraw frame. Fields: x y width height angle, strokeColor, backgroundColor (the fill), fillStyle solid|hachure|cross-hatch, strokeWidth 1|2|4, strokeStyle, roughness 0|1|2, opacity, roundness, fontSize, fontFamily (5 hand-drawn), textAlign, groupIds, points [[0,0],[dx,dy],...] relative. y points down. TEXT WRAPS: give a text element a `width` and prose is wrapped to it with the real font metrics (height follows); no width = one line per \n, sized exactly. Never break long paragraphs by hand. THE LOOK IS HAND-DRAWN. This is Excalidraw. roughness 1 (default) on everything; native rectangle/ellipse/arrow rather than 4-point lines; sparse points with roundness {type:2} for a curve (dense points look furry, not sketchy); hand-drawn font. Detail is a few extra strokes, never more parts. COLOUR IS FLAT. Solid fills, one colour per part, and the wobbly outline does the rest - that is the Excalidraw look. Do not shade: no hachure or cross-hatch as texture, no gradients faked with stacked shapes, no drop shadows. If a part must read as darker, give it a darker solid hex. Reserve hachure/cross-hatch for something that IS hatched (a cutaway, a glass pane). PAPER AND INK. Nothing is inverted for display: every hex shows exactly as written. New scenes are dark paper (#121212). Anything drawn without a strokeColor gets ink that contrasts with the paper (#e9ecef on dark, #1e1e1e on light); describe_scene reports `background` and `ink`. Any hex is fine - character colours are character colours on any paper. SHORTHAND. label on a shape adds centred bound text; ref names an element and start/end on an arrow bind to it. Generated geometry is an element whose type is polygon|star|arc|capsule|path, e.g. {"type":"path","points":[[0,0],[40,30],[90,10]],"closed":true} smooth curve through the points polygon {sides,cx,cy,r} star {points,cx,cy,r,innerRatio} arc {cx,cy,r,from,to} capsule {x,y,width,height,radius} repeat {count,dx,dy | cols,rows | around:{cx,cy}} and mirror {axis:'vertical',at} multiply one spec evenly. These are for furniture - rings, plates, arrays - not for bodies. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose the critical trait: the operation is destructive but recoverable because 'the previous state is snapshotted.' That is exactly the safety context an agent needs before wiping a scene. It stops short of explaining the snapshot/restore mechanics or failure modes, so not perfect, but strong for a mutation tool.
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?
Two sentences, front-loaded with the core action followed by the destructive caveat and the alternative. Every clause earns its place with zero 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 destructive, three-parameter replace tool with no annotations and no output schema, the description plus the thorough inline schema cover purpose, destructiveness, recoverability, and alternatives. Only the restore path and edge-case behavior are left implicit, which are minor gaps given the sibling restore_snapshot.
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% and the schema itself richly documents all three parameters (label, scene, elements), so the schema does the heavy lifting. The description adds no parameter syntax or format detail beyond what the schema provides, making the baseline 3 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?
States a specific verb and resource ('Replace a scene's entire contents'), making the full-overwrite semantics unmistakable. It also explicitly names the siblings it is not (add_elements, update_elements), so an agent can route correctly without opening any schema.
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?
Provides both the when-to-use ('replace entire contents') and the when-not ('prefer add_elements or update_elements when you only mean to change part of it'), naming the alternatives explicitly. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Put a snapshot back on the canvas. This is itself snapshotted, so reverting a revert is possible.
| Name | Required | Description | Default |
|---|---|---|---|
| scene | Yes | Scene id, exact name, or a unique part of the name. Use list_scenes if unsure. | |
| snapshot | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses one non-obvious trait — the restore is itself snapshotted, making the operation reversible — but omits whether the current canvas state is overwritten/destroyed, whether prior unsaved work is lost, and whether any permission or confirmation is required.
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?
Two short sentences, the action front-loaded and the reversibility caveat second. No filler, and every sentence carries information the agent needs.
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 mutation tool with no annotations and no output schema, the description covers the action and its reversibility but leaves the snapshot parameter undefined and the overwrite semantics of the target scene unaddressed. Adequate but visibly incomplete.
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 50%: 'scene' is well documented in the schema (id, exact name, or partial name, with a pointer to list_scenes), but 'snapshot' has no description in either the schema or the description text. The description says 'a snapshot' but never clarifies whether the parameter is an id, name, or index, so it fails to compensate for the coverage gap.
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 and resource ('Put a snapshot back on the canvas'), which clearly reads as the inverse of the sibling snapshot_scene. It identifies the operation without opening the schema, though it never names the sibling it complements or contrasts with, so differentiation is implied rather than stated.
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?
No guidance on when to use this versus list_history, snapshot_scene, or replace_scene, and no prerequisites or preconditions are stated. The agent must infer that a snapshot must already exist and that list_history is the discovery path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the paper: the scene's real background colour, shown exactly as given (never inverted). The default pen for hand drawing follows it, so the next stroke in the app is visible. Elements already drawn keep their colours - recolour their ink yourself if you flip a scene from light to dark or back. New scenes start on dark paper (#121212).
| Name | Required | Description | Default |
|---|---|---|---|
| color | Yes | ||
| label | Yes | Short description of what this change is doing, e.g. 'add the dog illustration'. Shown next to the snapshot in the history sidebar, which is how the user decides whether to keep or revert it. Always set it. | |
| scene | Yes | Scene id, exact name, or a unique part of the name. Use list_scenes if unsure. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does it well: the colour is shown exactly as given and never inverted, the default pen follows it so the next stroke is visible, existing elements are unaffected, and new scenes default to #121212. It stops short of stating permissions, return value, or reversibility (though snapshot/history siblings exist).
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?
Four tight sentences, front-loaded with the core action and followed by consequences; each sentence carries a distinct warning (inversion, pen default, element persistence, default colour). Slight redundancy in 'the scene's real background colour, shown exactly as given (never inverted)'.
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 3-required-parameter mutation tool with no annotations and no output schema, the description covers the important side effects and defaults. It omits reversibility/undo behaviour and any note on failure modes, but nothing critical for correct invocation is 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?
Two of three parameters are documented in the schema (scene, label) for 67% coverage; color has no schema description, and the description adds only indirect meaning about colour behaviour rather than format or accepted values. Baseline 3 is appropriate given the schema already handles most parameter documentation.
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+resource: setting the scene's background colour, with 'paper' clearly defined as the real background colour. It is readily distinguishable from siblings like update_elements or replace_scene. Scope is unambiguous at first sentence.
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 the use case (flipping a scene from light to dark or back) and warns that existing elements keep their colours so you must recolour ink yourself, but it never names the sibling tool to use for that (e.g. update_elements) nor states when-not to use this tool. Guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The manual, for answering the user's questions and fixing problems without guessing: install on any client, where scenes are stored and how to move the vault, the library app, what rendering needs, every tool, the drawing contract, and troubleshooting for the errors that come up. No topic returns the index.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | One of: install, vault, app, rendering, tools, drawing, troubleshooting. Omit for the index; `all` for the whole manual. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses the default behavior (no topic → index) and the authoritative nature of the content, but gives no statement of read-only safety, response format, or size, which a docs tool could reasonably surface.
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?
Purpose is front-loaded and the topic list is compressed into one sentence with no filler. The single run-on sentence is a bit packed, but every clause maps to a real enum topic rather than padding.
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 one-parameter, non-annotated docs tool with full schema coverage and no output schema, the description supplies enough to call it correctly: what it returns, what the topics are, and the default. Only the relationship to sketchdex_info is left unstated.
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 100% and the schema already lists every enum value plus the "omit for index / all for whole manual" behavior, which the description largely repeats. Baseline 3 is appropriate since the schema does the parameter heavy lifting with negligible added meaning.
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 the resource ("the manual") and enumerates its contents (install, vault, app, rendering, tools, drawing, troubleshooting), making it clear this retrieves documentation by topic. It stops short of distinguishing itself from the sibling sketchdex_info, which plausibly also serves information.
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?
"For answering the user's questions and fixing problems without guessing" gives a clear use context, and "No topic returns the index" tells the agent what happens on omission. It offers no explicit when-not or alternative-tool routing, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Version of this server, where it is running from, which vault it is using, and how long this process has been alive. Use it to confirm you are talking to the build you think you are.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden. It does reveal the four pieces of state returned, which is the key behavioral fact for a diagnostic call, but it never states that the tool is read-only, side-effect free, or whether any auth is required — omissions that matter when nothing else signals safety.
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?
Two sentences, zero filler. The informational payload is front-loaded and the usage instruction follows it, so an agent gets both the 'what' and the 'why' 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?
With no output schema, the description must stand in for the return value, and it names all four fields the caller will receive. Combined with the empty input schema, an agent has everything needed to call it correctly. Only the read-only/side-effect assurance is 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?
The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify beyond the fact that it is argument-free, which is consistent with the empty 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 enumerates exactly what the tool returns — server version, run location, vault in use, uptime — which is far more specific than the name 'sketchdex_info' alone and clearly separates it from the scene-manipulation siblings. It lacks an explicit verb ('returns'/'reports'), but the resource and scope are unambiguous.
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 gives an explicit trigger: 'Use it to confirm you are talking to the build you think you are.' That is a clear context for invoking it. It does not name a when-not condition or an alternative, but no sibling tool competes for this diagnostic purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stash the current state without changing anything, so it can be restored from the history sidebar. Do this before editing a .excalidraw file directly with your own file tools - every other tool here snapshots on its own.
| Name | Required | Description | Default |
|---|---|---|---|
| label | Yes | Short description of what this change is doing, e.g. 'add the dog illustration'. Shown next to the snapshot in the history sidebar, which is how the user decides whether to keep or revert it. Always set it. | |
| scene | Yes | Scene id, exact name, or a unique part of the name. Use list_scenes if unsure. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that the operation is non-mutating ('without changing anything') and that the snapshot surfaces in the history sidebar for restore. It doesn't cover persistence, retention limits, or whether snapshots can collide, so not quite a 5.
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?
Two sentences, zero waste. The core action is front-loaded and the conditional guidance follows immediately; every clause earns its place.
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 2-param, no-output-schema tool with fully documented parameters and a clear usage trigger, this is nearly complete. A minor gap is the absence of any note on what a successful snapshot returns or whether the user must confirm it, but nothing blocks correct invocation.
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 100% and both parameters are richly documented there (label purpose, 'Always set it', scene id resolution via list_scenes). The description adds no parameter-level detail beyond this, so the baseline 3 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?
Specific verb ('stash the current state') plus resource (scene), and it immediately distinguishes itself from siblings by stating 'every other tool here snapshots on its own,' which clarifies why this one exists alongside update_elements, add_elements, etc.
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?
Gives an explicit trigger: 'Do this before editing a .excalidraw file directly with your own file tools.' It also states the implicit when-not — other tools snapshot automatically, so no manual snapshot is needed for them. The routing decision is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change named fields on existing elements. Send only what changes - {id, x: 40} moves one box and leaves its other 25 fields alone. Pass a list in elements, each carrying its id, or use ids + patch to apply one change across many.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | ||
| label | Yes | Short description of what this change is doing, e.g. 'add the dog illustration'. Shown next to the snapshot in the history sidebar, which is how the user decides whether to keep or revert it. Always set it. | |
| patch | No | ||
| scene | Yes | Scene id, exact name, or a unique part of the name. Use list_scenes if unsure. | |
| elements | No | Partial elements, each with an `id` and the fields to change. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose key merge semantics: partial updates leave the other ~25 fields untouched. It says nothing about permissions, behavior on unknown ids, or whether the change is reversible/snapshot-able (the snapshot/history system is only alluded to in the `label` schema, not the description).
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?
Three tight sentences: verb+resource first, a concrete example of partial-update semantics second, the two input modes third. No filler, and the most important constraint (send only what changes) is front-loaded.
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?
A mutation tool with nested objects, no output schema, and no annotations needs the description to cover error/edge behavior, which it does not. It is adequate for a competent caller — both input patterns are clear — but leaves the boundary with move_elements and failure modes unspecified.
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 60%, and the description adds genuine meaning beyond it by contrasting the `elements` list form with the `ids` + `patch` bulk form, which the bare schemas do not explain (`patch` has no schema description at all). It does not enumerate which element fields are patchable, only that there are ~26 of them.
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 and resource ('Change named fields on existing elements') and the word 'existing' implicitly separates it from add_elements/delete_elements. However it never distinguishes itself from move_elements, even though its own example ({id, x: 40}) is a move operation — a real overlap an agent would need resolved.
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 two invocation shapes (a list in `elements` vs `ids` + `patch`), which is useful routing between input forms. It gives no guidance on when to prefer this tool over move_elements, replace_scene, or add_elements, so the when-to-use question is only implied.
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.2add_elementscheck_scenecreate_scenedelete_elementsdescribe_sceneimport_svglist_historylist_scenesmove_elementsread_elementsread_scenerender_scenereplace_scenerestore_snapshotset_backgroundsketchdex_docssketchdex_infosnapshot_sceneupdate_elementsScored across 19 tools
Most tools target clear and distinct operations (add vs update vs delete vs move vs replace elements). There is some overlap in the reading surface (describe_scene, read_elements, read_scene) and between move_elements and update_elements, but the descriptions explicitly clarify when to use each (cheaper summary vs filtered vs full; move adds group/region selection).
Nearly all tools follow a clean snake_case verb_noun pattern (list_scenes, create_scene, add_elements, restore_snapshot). The only deviations are the namespace-style sketchdex_info and sketchdex_docs, which is a mild but coherent exception for meta tools.
19 tools is on the heavier side but justified for a full drawing/editing domain covering scenes, elements, SVG import, rendering, layout checking, background, docs and history. Each tool occupies a distinct role, though it sits near the upper bound of comfortable scoping.
The surface is broad: scene and element CRUD, SVG import, geometric validation, rendering, background control, snapshots and history restoration. Minor gaps exist (no delete_scene or group/ungroup tool), but agents can work around these with replace_scene and groupIds.
Real-time collaborative whiteboard — AI agents and humans edit the same board live over MCP.
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.
Whiteboard where any shape opens into another canvas. Claude Code and Codex plugins render plans on it.
