Skip to main content
Glama

Inkscape Live

inkscape_live
Destructive

Drive the open Inkscape document live over D-Bus to edit SVG, run actions, apply effects and manage selections in place without recreating the file.

Instructions

Drive the RUNNING Inkscape GUI — the user's already-open document — live over D-Bus.

Work on the open document IN PLACE; do not recreate it. Prefer Inkscape's own live tools over hand-writing SVG: use apply_action for actions (it finds the app, window or document scope itself, so undo/redo work too) and inkscape_extension run_live WITH NO PARAMS for filters/effects like drop shadow and blur — select the target first, then call it; that is the only run_live mode that sees the live document and selection. (Passing params renders on an empty canvas and suits generator extensions only.) (The inkscape_gradient tool is headless/file-based — not for the live doc.) Use edit_xml (raw-SVG set_attr/append/insert_*/remove/replace, targeted by XPath, multi-node capable) for everything else, e.g. editing gradients on the live doc — it is the reliable persisting edit path. execute_inkex does NOT persist mutations; don't use it to edit.

Every op acts on Inkscape's ACTIVE document and reports which one that was in data.active_document. window_id cannot route — Inkscape 1.4 has no focus-window action — so it is an assertion: leave it at 0 to accept the active document, or pass a window number to have the call REFUSE when more than one document is open and the target is therefore ambiguous. Check active_document before any destructive edit; auto-save writes to disk.

Operations: ping, get_document_xml, get_selection, set_selection, insert_svg, delete_selected, apply_action, list_actions, open_file, save_snapshot, edit_xml, path_edit, path_offset, inspect_selection/layers/defs/view/pages/element, execute_inkex, rasterize.

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": {
      "operation": "<operation>"
    },
    "name": "inkscape_live"
  }
}

Input Schema

NameRequiredDescriptionDefault
targetNo
payloadNo
operationYes
window_idNo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv2.0.0

TDQS

A4.5/5.0
Behavior5/5

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

Annotations already flag destructiveHint=true and non-idempotent, but the description adds what annotations cannot: every op targets Inkscape's ACTIVE document and reports it in data.active_document, window_id cannot route and instead acts as an ambiguity assertion, and auto-save writes to disk. It also warns that execute_inkex mutations do not persist — a critical behavioral distinction that is invisible in structured fields.

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?

Front-loaded with the core purpose and the live-vs-headless distinction before any detail, and every section earns its place. It is dense though: nested parentheticals and a long multi-clause sentence about window_id make it heavier than necessary, and the trailing operation list is a bare enumeration.

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?

An output schema exists, so the reference to data.active_document rather than a return-value spec is appropriate, and the mutation/persistence model is covered. The gap is operation-level coverage: of 21 enumerated operations, only apply_action, edit_xml, and execute_inkex get real explanation, while path_edit, path_offset, rasterize, set_selection, and the inspect_* family are named but never characterized, leaving an agent to guess their preconditions.

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

Parameters3/5

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

Schema description coverage is 0%, so the description must compensate. It does an excellent job on window_id (default 0 = accept active document; nonzero = refuse when multiple docs are open) and hints at operation semantics for apply_action, edit_xml, and execute_inkex, but 'target' and 'payload' are never defined — the reader must infer which operations consume them and in what format. Partial compensation, not full.

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?

Opening line states a specific verb, resource, and channel: 'Drive the RUNNING Inkscape GUI — the user's already-open document — live over D-Bus,' and immediately contrasts with headless siblings ('The inkscape_gradient tool is headless/file-based — not for the live doc'). An agent can distinguish this from inkscape_gradient and inkscape_extension 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.

Usage Guidelines5/5

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

Gives explicit routing rules: use apply_action for actions (with the note that it resolves scope itself and works for undo/redo), use inkscape_extension run_live with NO params for filters/effects after selecting the target, use edit_xml for everything else, and avoid execute_inkex for edits because it does not persist. It also names the excluded tool (inkscape_gradient) and the excluded run_live mode (passing params).

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