Excaliself

Propose a drawing edit

edit_drawing

Propose edits to an existing drawing with a preview; changes apply only after the member clicks Apply in Excaliself, then return applied, discarded, pending, or stale.

Instructions

Proposes a change to an existing drawing. Nothing changes until the member clicks Apply on the drawing in Excaliself, where they see a preview; this tool then reports "applied", "discarded", or "stale". It waits up to 25 seconds for that, then returns "pending": tell the member to open the link, and call get_drawing_edit later.

Read the drawing with read_drawing first, and refer to its elements by the [id …] it shows.

add: new elements, in create_drawing's format. Arrows may join existing shapes by element id ("from", "to"). Give new shapes x/y next to the shapes they relate to (read_drawing gives positions); without x/y they are laid out beside the drawing.
change: by element id. Shapes take label, x/y (move), width/height, colors, and strokeStyle; text takes text, x/y, and strokeColor; arrows take label, strokeColor, and strokeStyle. Arrows bound to a moved shape follow it. To attach an arrow to other shapes, remove it and add a new one.
remove: element ids. A shape's label goes with it; arrows bound to it stay, unattached.

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": {
      "id": "<id>",
      "summary": "<summary>"
    },
    "name": "edit_drawing"
  }
}

Input Schema

Name	Required	Description
`id`	Yes	A drawing id from list_drawings or search_drawings.
`add`	No
`change`	No
`remove`	No	Element ids from read_drawing.
`summary`	Yes	One line the member reads before Apply, e.g. "Add a CDN in front of the API".

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.9.0Nov 7, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes well beyond the annotations, which only declare non-read-only, non-idempotent, non-destructive. The description discloses the human-in-the-loop approval gate, the preview the member sees, the four possible outcome states ('applied', 'discarded', 'stale', 'pending'), and the 25-second wait before timing out to 'pending'. No contradiction with 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.

Conciseness5/5

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

Front-loaded with the asynchronous approval behavior, then per-operation bullets. Sentences are dense with actionable detail and nothing is decorative; the add/change/remove breakdown maps directly to the schema's top-level parameters.

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?

With no output schema, the description correctly carries the burden of return values and does so explicitly, including the timeout fallback. It is only slightly incomplete on error/failure behavior and whether a batch is applied atomically.

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 60%, and the description compensates with operation-level rules the schema does not encode: how arrows bind to existing shapes via 'from'/'to', that new shapes should get x/y near related shapes else auto-layout, which fields apply per element type in 'change', that arrows follow a moved shape, and that a removed shape's arrows remain unattached. Limits like maxItems 500 and batch atomicity are left unstated.

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 ('Proposes a change to an existing drawing') and immediately clarifies the proposal semantics — nothing changes until the member clicks Apply. It is clearly distinguishable from create_drawing and read_drawing, both of which it references by name.

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 a concrete prerequisite workflow: read the drawing with read_drawing first and refer to elements by the [id …] it shows. It also routes the agent forward on a 'pending' result to get_drawing_edit and tells it to instruct the member. It stops short of explicit exclusions such as when to prefer create_drawing over an add-only edit.

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