Excaliself

Import scene

import_scene

Creates a new drawing from an Excalidraw scene JSON file and returns its link. Use it to turn saved .excalidraw files into editable Excaliself drawings.

Instructions

Creates a NEW drawing from an Excalidraw scene: the JSON of a .excalidraw file, as Excalidraw's "Save to file" writes it, with images inline in "files". Returns its link. To draw from a description instead, use create_drawing.

Up to 50,000 elements and 20 MB of element JSON; images up to 20 MB in all. The whole call must stay under 4 MB; send a large scene as JSON text, not an object. Images with no entry in "files" open as placeholders.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "scene": "<scene>"
    },
    "name": "import_scene"
  }
}

Input Schema

Name	Required	Description	Default
`name`	No	Default "Untitled".
`scene`	Yes	The .excalidraw file: its JSON text, or that JSON as an object, with "elements", and "files" for images.
`space`	No	Default "private". Ignored with folderId: a drawing takes its folder's Space.	private
`folderId`	No	Put it in this folder (see list_folders).

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.11.0Nov 10, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Annotations only cover the read/write/idempotency profile, and the description goes well beyond them with concrete operational limits: 50,000 elements, 20 MB of element JSON, 20 MB of images, a 4 MB whole-call cap, and the requirement to send large scenes as JSON text rather than an object. It also discloses a silent degradation behavior — images with no entry in 'files' open as placeholders — which an agent could not infer from the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and the alternative route are front-loaded in the first sentence, with constraints and edge cases following in a second paragraph. It is dense but every sentence carries a distinct constraint; the limits paragraph is slightly packed with numbers but not padded.

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

Completeness4/5

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

For a mutation tool with no output schema, it still states the return value ('Returns its link'), size and element ceilings, the payload encoding rule, and placeholder behavior for missing image files. It does not cover failure modes when limits are exceeded or any permission/space-membership requirements, which are the remaining gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all four parameters and sets the baseline at 3. The description adds real operational meaning for the 'scene' parameter (either JSON text or an object, matching Excalidraw's own file format) and a non-obvious encoding rule for large payloads, which is more than restating the schema.

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

Purpose5/5

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

States a specific verb and resource ('Creates a NEW drawing') plus the exact input format ('the JSON of a .excalidraw file, as Excalidraw's "Save to file" writes it'). It also distinguishes itself from create_drawing by naming the alternative path, so an agent can pick correctly without opening either schema.

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

Usage Guidelines4/5

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

Gives an explicit when-not with the alternative: 'To draw from a description instead, use create_drawing,' and points to list_folders for the folderId parameter. It lacks guidance on related decisions such as choosing space vs folder or re-importing an existing drawing, but the primary routing question is answered.

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