A
licenseNot graded
qualityC
maintenanceEnables LLMs to programmatically generate, edit, and convert SVG images using the SVGMaker API and save them to the local filesystem.
106 npm
87
MIT
inkscape-mcp
by jjjsood
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., "@inkscape-mcpOpen my logo.svg and change the fill to blue."
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.
inkscape-mcp
A Model Context Protocol (MCP) server that makes Inkscape / SVG documents agent-ready — inspect, edit safely, validate, render, and export vector graphics from any MCP client.
inkscape-mcp exposes a small, strongly-typed tool surface over your SVG documents. An LLM agent
can open a drawing, read its structure, recolour and re-letter objects, transform geometry, render
previews, and export production assets — all headless-first and reversible by construction.
Every mutating operation runs on a working copy, takes a snapshot, and records an Operation Record,
so nothing the agent does touches your originals or can't be undone.
Table of contents
Related MCP server: inkscape-mcp
Why
LLM agents are good at reasoning about what should change in a drawing ("make the logo blue, bump the heading to 24 px, export a 512 px icon") but bad at safely poking at raw XML or driving a GUI. A naive "run this Inkscape command" tool is dangerous: it can overwrite originals, shell out unsafely, or silently corrupt a file with no way back.
inkscape-mcp solves that with a bounded, typed API: each capability is its own small tool
with explicit parameters and a declared risk class. Simple structural edits go through a direct
lxml DOM layer; rendering, export, and complex geometry go through the Inkscape CLI. Originals
are never mutated, every change is snapshot-backed and reversible, and subprocess calls use
argument lists — never shell strings.
Highlights
88 typed tools across read, validate, render, export, optimize, safe-edit, element-creation, defs/grouping, path-geometry, snapshot, save, and live groups.
Headless-first. No GUI required; the Inkscape binary is used only for render / export / geometry, and the server probes the runtime instead of assuming a version.
Reversible by construction. Every mutating op = pre-mutation snapshot + before/after preview
Operation Record.
restore_snapshotrolls back.
Originals are sacred. Documents open into tracked working copies. Nothing writes over the source file; saving goes to a new path, and overwrites are gated behind explicit approval.
Risk-classed. Each tool declares
low/medium/high/restricted; the policy layer enforces it (high-risk needs a per-operation approval token; restricted never ships in the MVP).Sandboxed. Workspace-root jail, path normalization + symlink guard, input/output/export size limits, per-process timeouts, safe XML parsing (no entity expansion), no network, no arbitrary extension execution.
MCP resources expose document structure (summary / tree / layers / objects / styles / fonts / assets) and the runtime capability matrix as addressable URIs.
How it works
MCP client (Claude, etc.)
│ STDIO / JSON-RPC
▼
FastMCP app ──► typed @mcp.tool functions (risk-classed, validated args)
│
├─ direct-DOM engine (lxml) → structure read + safe edits
├─ Inkscape CLI adapter (arg-list) → render / export / geometry
├─ snapshot engine → pre-mutation copy + reversible restore
├─ Operation Records → audit trail of every mutation
└─ workspace sandbox → path/size/timeout/XML safetyopen_documentcopies your SVG into a tracked workspace document and hands back an opaquedoc_id. The original file is never opened for writing again.Read tools / resources inspect that working copy — tree, layers, styles, fonts, assets.
Edit tools mutate the working copy through the pipeline: take a snapshot → apply the change → render a before/after preview → write an Operation Record. All medium-risk and reversible.
Render / export tools shell out to the Inkscape CLI (argument lists only) and drop artifacts into the workspace artifacts / exports directories as workspace-relative paths.
save_document_aswrites the working copy to a new file (validated before and after). Overwriting an existing file is a separate, approval-gated high-risk path.
Requirements
Python ≥ 3.12 and
uv.Runtime deps (installed by
uv sync): FastMCP 3.x, lxml, and Pillow (the focused live before/after visual diff,live_diff_view, uses Pillow to pixel-diff frames and draw the annotation overlay).Inkscape on
PATHfor the render / export / geometry tools (developed and tested against Inkscape 1.4.x). Read / edit / validate tools work without it.Probe your install with
inkscape --version/inkscape --action-list, or run thediagnose_runtimetool.
At least one workspace root configured (see Configuration) — the sandbox refuses to touch anything outside it.
Install & quickstart
The package exposes one console script, inkscape-mcp → inkscape_mcp.server:main, which starts the
FastMCP app over STDIO. Install it via uvx (one-shot), pipx (persistent), or from source.
Not on PyPI yet — install from source / git (same package, same script). Bare-name
uvx inkscape-mcp/pipx install inkscape-mcpwill work once published.
# uvx — run without installing (from a local checkout; the repo root holds pyproject.toml):
uvx --from /abs/path/to/inkscape-mcp inkscape-mcp
# uvx — straight from git:
uvx --from "git+https://github.com/jjjsood/inkscape-mcp.git" inkscape-mcp
# pipx — persistent install of the console script:
pipx install /abs/path/to/inkscape-mcp
# from source (development / dogfooding):
cd inkscape-mcp # the repo root
uv sync # install runtime + dev dependencies
uv run pytest # run the test suite
uv run inkscape-mcp # start the STDIO MCP serverThe launched server waits on stdin for MCP JSON-RPC (an MCP host drives it). Confirm it boots with
inkscape-mcp </dev/null or uv run python -c "from inkscape_mcp.server import main". Full install
matrix (incl. the claude mcp add form): docs/install/install.md.
Quality gates:
uv run ruff check --fix .
uv run ruff format .
uv run mypy srcTests that need a real Inkscape binary are marked
@pytest.mark.inkscape. They auto-skip when noinkscapeis onPATH(centralpytest_collection_modifyitemshook intests/conftest.py), so the suite is green on a host without Inkscape; they run normally when the binary is present. Force-skip explicitly withuv run pytest -m "not inkscape".
CI. .github/workflows/ci.yml runs ruff + ruff-format
mypy + pytest on Linux/macOS/Windows (headless + the cross-platform live-transport suite), the full suite incl. real-Inkscape tests on Linux, and a packaged
pipx-install STDIO boot smoke on all three OSes, plus a full-surface MCP smoke (ci_surface_smoke.py) that asserts the registered primitive counts (99 tools / 7 prompts / 16 resources) and reads every resource over an in-memory client. CI helper scripts live inscripts/(ci_diagnostics.py,ci_boot_smoke.py,ci_surface_smoke.py).
Evals. evals/ holds a deterministic, CI-runnable tool-usability harness that
makes "agent-friendly" measurable without a live LLM: tool_selection_scenarios.json is a labelled
set of natural-language asks (mirroring the intent catalog below), and run_eval.py drives the
server's own discovery layer (how_do_i / intents.py) to report
per-group + overall tool-selection accuracy and out-of-scope flagging (uv run python evals/run_eval.py, --json for the report dict). tests/test_eval_harness.py gates it against
regressions; the scenario schema is runner-agnostic. An OPTIONAL, report-only live-agent runner
(run_live_eval.py) reuses the SAME dataset + scorer to capture real tool-call traces +
turn count via a pluggable AgentDriver (deterministic ReplayDriver by default; the real MCP+LLM
path is off unless --driver real / INKSCAPE_MCP_EVAL_DRIVER=real) and never gates CI.
Connecting an MCP client
The server speaks MCP over STDIO. Point any MCP-capable client at the inkscape-mcp console
script. Ready-to-copy host configs live in examples/
(claude_desktop_config.json,
mcp.json); full per-host instructions (Claude Desktop, Claude Code +
claude mcp add, generic STDIO) are in
docs/install/host-configs.md. Example client config:
{
"mcpServers": {
"inkscape": {
"command": "uvx",
"args": ["--from", "/absolute/path/to/inkscape-mcp", "inkscape-mcp"],
"env": {
"INKSCAPE_MCP_WORKSPACE_ROOTS": "/absolute/path/to/your/svgs"
}
}
}
}(With a pipx install, use "command": "inkscape-mcp", "args": [].) To dogfood straight from a
source checkout, point a host at uv run --directory /abs/path/to/inkscape-mcp inkscape-mcp once
uv sync has run. Map any platform/feature gap with the
compatibility matrix and
troubleshooting docs.
Configuration
All configuration is environment-driven (no config file needed). The sandbox is the only required
setting — without a workspace root the server has nothing it is allowed to touch. The same table (and
the claude mcp add / generic-host forms) is in
docs/install/host-configs.md.
Env var | Default | Purpose |
| (none) | Required. OS-path-separated list of directories the server may read/write. Everything else is rejected. |
|
| Max size of an input SVG. |
|
| Max raster dimension for render/export. |
|
| Max size of a produced artifact. |
|
| Per-Inkscape-process timeout (seconds). |
|
| Max concurrent Inkscape subprocesses. |
|
| Snapshots retained per document. |
|
| Snapshot age retention. |
|
| Hard cap on snapshots per document. |
|
| Hard cap on snapshot bytes. |
|
| Artifact age retention. |
|
| Total artifact byte budget. |
|
| Per-document artifact byte budget. |
|
| Max frames in the per-session live render cache (LRU). Floored. |
|
| Total byte budget for the live render cache (LRU eviction). Floored. |
|
| Frame-coalescing latency budget: a repeated identical-key render within this window returns the just-cached frame instead of re-rendering. |
|
| Age retention for loop/live render frames, pruned by the explicit retention sweep (boot + |
|
| Total byte budget for loop/live render frames (newest kept), pruned by the explicit sweep. |
|
| Master gate for live mode. On by default (operator-chosen); set a falsy value ( |
| (none) | Optional explicit path to the live helper's rendezvous file (otherwise discovered under the Inkscape user data dir / temp dir). |
| (built-in defaults) | OS-path-separated list of Inkscape Action ids added to the built-in allowlist. Server-side, never client-supplied; cannot remove a default or open arbitrary passthrough. Each Action must also exist in the version-keyed capability map to run. |
| (empty) | OS-path-separated list of Inkscape extension ids added to the (empty) execution allowlist. Discovery is read-only and unaffected. |
|
| Advanced-mode gate for the |
|
| Engine transport for render/export/path/boolean/action-chain (ADR-007). |
|
| Max concurrent warm shell workers when |
|
| Seconds before an idle warm shell worker is reaped. Floored at 1. |
|
| Tool-disclosure profile. |
|
| Tool-DESCRIPTION mode, orthogonal to |
Tool reference
89 tools. Risk classes: low (read / render / export / quality / Action discovery) · medium
(write-new / element-creation / defs-grouping / style / text / transform / web-optimize / typed batch; reversible)
· high (overwrite / delete / path geometry / Action chains / raw Action; approval-gated) ·
restricted (live helper install).
Mutating tools return an EditResult carrying the operation_id, snapshot id, and a before/after
preview.
Conventions (param + path naming). Single-object tools take object_id; multi-object tools take
object_ids. A caller-chosen write target is dest_path (a file) or out_dir + name_prefix (a
directory); a relative dest_path/out_dir anchors to the workspace root, never the process
CWD, and is sandbox + symlink checked (path rejected: outside workspace otherwise). Every
artifact-producing tool returns a workspace_relative_path (root-relative, opens directly with no
find/stat) alongside the managed artifact_path; no absolute host path ever appears in a result
(sec.12). The four raster tools (render_preview / capture_frame / export_document /
export_object) also return the PNG inline as an MCP image block when it is under the inline
byte threshold (≈5 MiB; tune via max_output_bytes, opt out with inline=False) — view that
image; do NOT Read the returned path. Because the path is root-relative to the server's
workspace (a client Read resolves it against its own CWD and fails), the inline text payload omits
the path entirely (it carries a note); the resolvable path stays in structured_content for
programmatic use. changed on a mutating result is decided in ONE place — the edit pipeline canonical-serializes
the document before and after the mutation. A real change reports changed: true with a linked snapshot +
Operation Record; a genuine no-op (e.g. replace_color matching nothing, normalize_viewbox on a
valid viewBox, set_fill to the colour already present, a second fit_to_content) reports
changed: false, empty operation_id/snapshot_id, and writes no snapshot and no Operation Record —
nothing happened, so nothing clutters the snapshot list or the audit trail.
MCP ToolAnnotations. Every tool also carries machine-readable MCP annotations —
readOnlyHint, destructiveHint, idempotentHint, openWorldHint, and a human title — derived
from ONE central map (src/inkscape_mcp/tool_annotations.py) keyed off the tool's existing risk
class, applied as a post-registration pass at boot. readOnlyHint follows the risk class directly
(low ⇒ read-only); destructive (overwrite/delete/outline), idempotent (pure re-set), and open-world
(host probes + live_*) sets are explicit in that one module. A client reads read-vs-write,
destructiveness, and idempotency without parsing docstring prose; titles are static labels only (no
host path, sec.12). Adding a tool with a Risk class: docstring line auto-annotates it.
Tags + progressive disclosure. Every tool also carries exactly one domain tag —
create / edit / transform / paths / export / live / actions / system / quality —
and one risk tag (low / medium / high / restricted), stamped from ONE central map
(src/inkscape_mcp/tool_tags.py) by the same boot pass. The two EXISTING operator flags then drive
tag-based exclusion so a default client sees a smaller core surface and opts into the advanced /
live groups (FastMCP disable(tags=…) visibility transforms — they only NARROW tools/list, never
widen it):
Flag | Default | Off → hides |
|
| every |
|
| the ADR-003 hatch group: |
So the default surface (live on, advanced off) exposes the core 86 tools; turn advanced mode on
to add the paths/actions geometry + Action surface (full 98), or turn live off to drop the live
group (66 with both off). The self-describing list_capabilities.tool_count / tools[]
report the active post-filter surface, since they read the same mcp.list_tools() the transforms
filter. The generated llms.txt manifest still documents the FULL catalog (generated with both flags
forced on).
Minimal core profile. For a still-smaller default model-context footprint, the opt-in
INKSCAPE_MCP_TOOL_PROFILE env (full default · core) narrows tools/list further to a curated
essential authoring set — the document / find / create / style / transform / export /
snapshots modules (open/inspect/find/create-*/style/transform/export/snapshot). Spike finding: the
default 85-tool surface is ~76k tokens of tools/list every turn; the 40-tool core set is ~31k —
a ~60% per-turn saving. The profile only NARROWS within the flag-allowed surface (it disables the
non-core tools by name; it can never expose a tool the live/advanced flags hide — sec.12 / ADR-003),
reuses the same disable(...) machinery, and is idempotent + re-evaluatable. A stray value floors to
full. tool_count / tools[] report the active surface; llms.txt still documents the FULL
catalog (generated with profile full). Everything outside core stays reachable by selecting full.
System & diagnostics — low
Tool | Signature | Description |
|
| Probe the local Inkscape + Python runtime fresh and return the capability matrix (version, actions, export formats, DBus/live, inkex, fonts) — plus the curated |
|
| Return the cached capability matrix (probed once, then reused). Includes an additive |
|
| Map a natural-language goal to the concrete tool name(s) that achieve it (best match first: |
|
| Read-only on-disk size + sha256 of one sandboxed artifact → |
|
| Set variant of |
Document — low (create is medium)
Tool | Signature | Description |
|
| Open an SVG into a tracked workspace working copy; returns an opaque |
|
| Create a blank, tracked working-copy document from scratch — no source file required. |
|
| Refresh a working copy from its source under the same |
|
| Aggregate inspection: tree, layers, styles, fonts, external assets, and an addressable |
|
| Read-only filter over a document's addressable objects (AND semantics) → |
Compose / adopt SVG — high (approval-gated), reversible
Tool | Signature | Description |
|
| Replace the whole working copy with an agent-composed SVG string (root must be |
|
| Insert an agent-composed SVG fragment (one element subtree) under |
|
| Lay out N different assets in a |
|
| Place an existing document OR one named object INTO another document at |
Validation — low
Tool | Signature | Description |
|
| Validate a loaded document; returns structured, machine-readable findings. Includes a per-text-element glyph-coverage check ( |
|
| Machine-readable quality report: wraps the |
|
| Quality-report a set in one read-only call: per-doc |
Render & export — low
Every render/export result carries a stale: bool staleness signal: False on a freshly
produced artifact (it reflects the current working copy); reserved to flag a previously-returned
artifact that the working copy has since outgrown (full mtime tracking is a follow-up — see).
Render/export results also self-certify content truth, computed in-process at produce time
(no pdffonts/pdfimages/mutool shell-out, no Pillow subprocess): a raster (PNG) result carries
opaque_px (drawn non-transparent pixel count) + all_blank so "the render actually drew something"
is checkable from the result; a PDF result carries is_vector (no embedded raster image) +
fonts_outlined (no embedded font — text outlined to paths), true vector when both hold. Each field is
additive and None for outputs it does not apply to (or when verification was skipped).
Tool | Signature | Description |
|
| Render a PNG preview of the whole document into the artifacts dir, returned inline as an MCP image block by default (view it; do NOT |
|
| Export the whole document to PNG / PDF / SVG in the exports dir (or a sandbox-checked |
|
| Export a single object (by id) clipped to its bounding box; reports the actual clipped raster size + the same content-truth fields. The id is charset-validated and never passed raw to Inkscape. |
|
| Capture the next numbered PNG screenshot in a per-run frame series ( |
|
| List the frames of a |
Export profiles & batch — low
Tool | Signature | Description |
|
| Web asset set: one PNG raster plus one plain SVG. Pass |
|
| Multi-size square PNG icon set from the source document. Over-cap and ≤0 sizes give distinct error messages. |
|
| Print-oriented vector PDF of the whole document; applies and reports print-specific export settings (so output differs from a plain PDF and is auditable). |
|
| Run a typed list of export specs ( |
|
| Batch-export a set in one call: runs |
Optimize — medium, reversible
Tool | Signature | Description |
|
| Web-optimize the working copy: strip editor metadata / namespaced attrs / comments, drop unreferenced |
|
| Web-optimize a set in one call: runs |
Snapshots — low
Tool | Signature | Description |
|
| Snapshot the current working copy and index it. |
|
| List a document's snapshots in order, with metadata. |
|
| Revert the working copy to a chosen snapshot; returns |
|
| Apply the retention policy (keep-N / keep-days + hard caps), deleting superseded snapshots and orphaned Operation Records, and the document root's loop/live render frames by age + byte budget (never a frame referenced by a Live Operation Record). Never touches the working copy or original. Explicit maintenance sweep — also runs once at boot; never triggered implicitly by a mutating tool. |
Style edits — medium, reversible
Tool | Signature | Description |
|
| Set fill colour (and optional fill opacity). Colour is validated; CSS-injection punctuation rejected. |
|
| Set stroke colour, width, and/or opacity. |
|
| Set element-level opacity ( |
|
| Replace one colour with another across the document (or within |
|
| Apply many |
Text & object edits — medium, reversible
Tool | Signature | Description |
|
| Replace the text content of a |
|
| Set font-family / font-size / font-weight (at least one required) on text objects. Returns |
|
| Duplicate an object/group in place, inserting the clone right after the original. |
|
| Replicate an object into an N×M grid (clone |
|
| Change an object's |
|
| High risk, reversible: remove objects by id from the DOM → |
Typed batch edit — medium (max over members), reversible
Tool | Signature | Description |
|
| Batch: apply an ordered list (≤ 64) of TYPED edits — a discriminated union over the existing DOM ops ( |
|
| Selector → op: declarative bulk edit without a code hatch — resolves a target SET via the EXISTING |
Element creation — medium, reversible
Direct-DOM (ADR-005) shape primitives — one small typed tool per shape (no catch-all
add_element(tag, attrs) per ADR-002/003). Each inserts into an optional parent_id (must exist)
or the document default parent (first inkscape:groupmode="layer", else the root), and returns a
CreateResult (the EditResult extended with object_id + an analytic bbox; bbox is None for
path/text whose geometry is not analytically cheap). Every value is strictly validated (finite
numbers, charset-safe ids, control-char-scrubbed text, command/charset-allowlisted path d).
Tool | Signature | Description |
|
| Insert a |
|
| Insert a |
|
| Insert an |
|
| Insert a |
|
| Insert a closed |
|
| Insert an open |
|
| Insert a |
|
| Insert a |
Defs, gradients & grouping — medium, reversible
Gradient defs land in the document <defs> (auto-created as the first child if absent); the returned
id is usable as a url(#id) paint. Grouping/structure tools reorganize existing objects.
Tool | Signature | Description |
|
| Add a |
|
| Add a |
|
| Insert an empty |
|
| Wrap existing objects (≥ 1, must exist) in a NEW |
|
| Move an object under a new parent (rejects a descendant/self parent; coordinate space may shift). |
|
| Insert a |
Transforms — medium, reversible
Tool | Signature | Description |
|
| Translate by |
|
| Scale by |
|
| Rotate by |
|
| Set canvas |
|
| Normalize or repair the root |
|
| Set the root |
Path geometry — high (approval-gated), dry-run by default, reversible
Destructive path operations that run through the Inkscape engine (select-by-id;<action>
arg-lists, never a shell string), not direct DOM (ADR-005). Every tool is HIGH risk: a real change
requires a non-empty approval_token; dry_run (typed param, default True) validates the
targets and reports which object ids + which Inkscape Action would run, writing nothing. Each
applied op is snapshotted + recorded + before/after-previewed (reversible). Object ids are
validated (argv-safe charset + must exist) before reaching the engine.
Tool | Signature | Description |
|
| Simplify path(s) ( |
|
| Union ≥2 paths into one ( |
|
| Subtract the upper path(s) from the lowest ( |
|
| Combine ≥2 paths into one multi-subpath path ( |
|
| Break a compound path into its subpaths ( |
|
| Outline each stroke into a filled path ( |
|
| Remove redundant/degenerate path data ( |
Actions & extensions — discovery low; chain execution high (approval-gated)
A controlled way to use Inkscape Actions without an open-string passthrough (ADR-003). Discovery
is probe-driven (reuses inkscape --action-list); an execution surface is built from a typed,
ordered chain of ActionSteps — never a raw string. Every step is validated against the
server-side allowlist (INKSCAPE_MCP_ACTION_ALLOWLIST, env-additive onto built-in defaults —
never client-supplied) and a versioned Action capability map (persisted at
<root>/.inkscape-mcp/action-maps/<version>.json, keyed by detected Inkscape version) so an Action
absent on the host is refused cleanly. Chain execution runs through the Inkscape engine (arg-lists,
shell=False) over the working copy and is snapshotted + recorded + before/after-previewed. The
single-Action raw escape hatch (run_raw_action, ADR-003) reuses the same gates behind an
opt-in, OFF-by-default advanced-mode switch (INKSCAPE_MCP_RAW_ACTION_ENABLED).
Tool | Signature | Description |
|
| Discover the host's actual Action surface + the allowlisted/available subsets; persists the version-keyed capability map. |
|
| List the server-side allowlisted extension set + probe notes (diagnostic; nothing executes; empty by default). |
|
| Dry-run: validate a typed |
|
| High risk: run a validated chain over the working copy via the mutating pipeline (snapshot + Operation Record + before/after preview, reversible). Requires a non-empty |
|
| High risk, advanced mode (OFF by default). The ADR-003 escape hatch: run ONE allowlisted Action (typed |
Save — medium / high (approval-gated)
Tool | Signature | Description |
|
| Save the working copy to a new file (validated before & after). New file = medium risk. Overwriting an existing file requires |
Live mode (read / write / view loop) — on by default (operator-chosen)
Control of a running Inkscape, cross-platform via a transport abstraction (extension-socket
bridge on any OS; DBus org.gtk.Actions an optional Linux fast-path). Gated by
INKSCAPE_MCP_LIVE_ENABLED (default on; set falsy to opt out); absent/unsupported transports are
reported cleanly, never as errors. No-freeze: the socket bridge is a modal inkex
effect extension (freezes the GUI for the whole session); the Linux DBus path runs in Inkscape's own
main loop and does not freeze the GUI — live_connect(prefer="no_freeze") selects it on Linux for
viewport, style/transform writes, and a structured export-to-file read (live SVG/PNG/active-doc).
Selection-id reads stay on the (modal) socket path; Windows/macOS live stays modal (best-effort).
The command schema is a fixed enum (wire protocol v5) — no arbitrary code or raw Action
passthrough (ADR-003). Adds semantic write: the three mutating tools are HIGH risk and require
an explicit approval_token, each producing a Live Operation Record with before/after canvas
renders; live never mutates unapproved. Adds the view loop: view-only viewport/region tools and
structured perception — live_get_scene pairs each rendered frame with a machine-readable
LiveScene (active-doc ref, selection ids + bboxes, viewport, canvas size, visible-object summary
reusing the headless ObjectInfo shape) so the agent reasons over structure, not pixels (ADR-006) —
plus change detection: live_wait_for_change polls a CHEAP server-hashed state token (revision +
selection + viewport — never the full doc or a PNG) on a bounded, cancelable wait so the loop renders
ONLY on change (including the user's own GUI edits), never busy-rendering. And a focused visual
diff: live_diff_view reuses a mutation's captured before/after frames, pixel-diffs them to a
changed-region bbox, and emits ONE annotated overlay (changed bbox + selection outline) linked back to
the Live Operation Record — a targeted diff, not two raw whole-window screenshots.
View/perception/change/diff tools are LOW risk — no document mutation, no Operation Record, no approval.
Finally, the loop orchestrator live_session_step frames ONE perceive→decide→act→observe
iteration: it captures the LiveScene + frame (perceive), the agent picks ONE typed semantic act from
a FIXED set (apply/insert_svg/set_text — each 1:1 with an write engine, no raw-Action/code),
routes it through run_live_mutation (HIGH + approval_token + Live Operation Record — the SAME
write path, zero new authority per ADR-006), then captures an after-scene + a focused live_diff_view
(observe). With no act it is perceive-only (no record). It is bounded + cancelable by construction —
a single step is one iteration; the agent drives the loop by re-calling it (there is no server-side
autonomous runner). The live_canvas_assist Prompt is the §4.1 entry point that orients the agent
on this loop.
Tool | Signature | Risk | Description |
|
| low | Report every live transport probed on this host (not assumed by OS), the best read-capable one, and whether the helper is installed. |
|
| medium | Connect over the best-ranked transport; records the chosen transport + active document. |
|
| low | Current session state: enabled, connected, active transport, available transports. Never raises. |
|
| low | Tear down the live session (the X1 disable switch). Idempotent. |
|
| restricted | Install the shipped extension-socket helper into the Inkscape user extensions dir. Gated by the master switch. |
|
| restricted | AUTO-ARM the socket helper: install it (idempotent) then launch a headful Inkscape with the helper effect auto-invoked via |
|
| low | Identity of the document open in the live instance. |
|
| low | Current selection as object ids. |
|
| low | Per-object detail for the selection (reuses the headless |
|
| low | Rasterize the live canvas to a PNG under the live artifacts dir. Optional region/bbox (all four together) + |
|
| low | Control the live canvas viewport: |
|
| low | Capture one live frame: the rendered PNG plus a structured |
|
| low | Block until the live state changes or the bounded timeout elapses. Polls a CHEAP server-hashed state token (revision + selection + viewport — never the full doc or a PNG; |
|
| medium | Save the live document as a new tracked workspace document (atomic write, never overwrites; Operation Record + snapshot). |
|
| high | Apply a validated style and/or simple transform to the live selection (reuses semantics). Approval-gated; Live Operation Record + before/after render. |
|
| high | Insert a safe-parsed SVG fragment into the running document. Approval-gated; recorded + rendered. |
|
| high | Replace the selected text object's content (length/control-char guarded). Approval-gated; recorded + rendered. |
|
| low | Export just the current live selection to a PNG under the live artifacts dir (read-only feedback, no record). |
|
| low | Produce a FOCUSED, annotated before/after visual diff of a live op — not two raw window screenshots. REUSES the op's |
|
| low when perceive-only / high when it acts | Run ONE perceive→decide→act→observe loop iteration. PERCEIVE = |
The helper extension can also be installed without the server via the dynamic installers in
scripts/: install-live-helper.sh (Linux / macOS / Windows under Git Bash or WSL)
and install-live-helper.ps1 (native Windows PowerShell). Both resolve the Inkscape user
extensions dir at runtime (inkscape --user-data-directory, with INKSCAPE_PROFILE_DIR and an
OS-aware fallback) and do not require the master gate.
Resource reference
Read-only MCP resources addressable by URI. Document resources are templated on doc_id.
URI | Description |
| Cached runtime capability matrix, including the authoritative MCP tool surface ( |
| Curated goal→tool intent map ( |
| Index of open documents and their concrete per-doc resource URIs (discoverable via |
| Index of registered MCP prompts (name + one-line purpose + arguments, from the live |
| Top-level document summary. |
| Element tree. |
| Layer list. |
| Object inventory. |
| Style usage. |
| Fonts referenced. |
| External assets / references. |
| Live-session state (enabled / connected / transport). Clean when no session. |
| Current live selection (object ids). Empty when no session. |
| Current live frame's structured metadata: the |
| Latest live change state: the current cheap state token + classified deltas ( |
| Recent Live Operation Records: what each mutation changed, approval, before/after renders. Paths are workspace-relative or opaque ( |
Prompt reference
MCP Prompts orient the agent on how to use the tool surface safely; they grant no capability of their own (architecture §4.1).
Prompt | Args | Description |
|
| Entry point for the live-view co-pilot loop. Orients the agent to drive a running Inkscape toward |
|
| Orients the agent on producing web-ready assets (optionally optimize + quality-check first, then |
|
| Orients the agent on producing a multi-size square PNG icon set via |
|
| Orients the agent on producing a print-ready vector PDF via |
|
| Orients the agent on recoloring to a brand/theme palette via |
|
| On-ramps the generative loop toward |
|
| On-ramps the OBJECT-TARGETED restyle loop toward |
Try asking your agent to…
Natural-language asks and the tool(s) each exercises. This catalog is aligned with the same
curated goal→tool map that powers the how_do_i tool and the intents section of
list_capabilities (src/inkscape_mcp/intents.py) — so the doc, the
discovery tool, and the runtime matrix never diverge. Don't know which tool fits? Just ask
how_do_i("…") with the goal in words and it returns the same mapping. For the full create→render→
export workflow, snapshots/reversibility, and the risk/approval model see the
agent-usage guide.
Generate / draw
"Draw a rectangle / circle / line on a new canvas." →
create_document,create_rect,create_circle,create_line"Add a text label." →
create_text"Add a gradient fill (linear or radial)." →
add_linear_gradient,add_radial_gradient,set_fill"Group these objects together." →
group_objects,create_group
Edit
"Make this shape blue / change its fill." →
set_fill"Change the stroke / outline and opacity." →
set_stroke,set_opacity"Swap one colour for another across the whole document." →
replace_color,apply_palette"Move / scale / rotate an object." →
move_object,scale_object,rotate_object"Delete these objects by id." (HIGH-risk, approval-gated, reversible) →
delete_object"Resize the canvas or fit it to the content." →
resize_canvas,fit_to_content,normalize_viewbox"Simplify / clean up these paths." (HIGH-risk, dry-run first) →
simplify_path,cleanup_paths"Union / subtract these shapes." (HIGH-risk) →
boolean_union,boolean_difference,combine_paths
Inspect
"Open this SVG and tell me what's in it." →
open_document,inspect_document"Find the red shapes / all text / objects by id." →
find_objects"Is this document valid? Give me a quality report." →
validate_document,quality_report"Audit a whole icon system for consistency (viewBox/stroke/id naming)." →
quality_report_set"What's the byte size / sha256 of this file (or this set)?" →
stat_artifact,stat_artifacts"What can this server do?" →
list_capabilities,how_do_i
Export
"Export a 512 px PNG (or a preview)." →
export_document,render_preview"Export just this one object." →
export_object"Export a whole icon set / many sizes at once." →
create_icon_set,export_batch"Lay out a 12-icon system as a contact/spec sheet in one call." →
compose_grid"Export / optimize a whole set of documents at once." →
export_set,optimize_set"Make the SVG smaller for the web." →
svg_web_optimize"Export web-ready / print-ready assets." →
export_web_profile,export_print_profile"Save it to a new file." →
save_document_as
Live
"Snapshot / undo / restore the document state." →
create_snapshot,list_snapshots,restore_snapshot"Connect to my running Inkscape and work on the open canvas." →
live_connect,live_get_scene,live_apply_to_selection
Safety model
The server is built to be safe to hand to an autonomous agent:
Workspace sandbox. Every path is normalized and resolved; symlinks are guarded; access outside the configured workspace root(s) is rejected before any I/O.
Originals untouched. Documents are opened as working copies. No tool overwrites the source;
save_document_aswrites elsewhere, and overwriting an existing file needs explicit approval.Reversibility. Mutating tools snapshot first and emit an Operation Record;
restore_snapshotrolls the working copy back to any indexed snapshot. An explicit retention sweep (boot-time +prune_snapshots) bounds snapshot growth without ever pruning the baseline or the live head.Risk policy.
low/mediumare permitted;highrequires a per-operationapproval_token(minted out of band, bound to one operation — never an ambient flag a model can set);restricted(code / network / fs-escape) never ships in the MVP.Subprocess hygiene. The Inkscape CLI is always invoked with argument lists, never shell strings. Object ids and formats are charset-validated before reaching the binary.
Resource limits. Input/output/export size caps, per-process timeouts, and a concurrency cap.
Safe XML. Parsing disables entity expansion and external-entity resolution (no XXE / billion laughs). No network access. No arbitrary extension execution.
Stable errors. Tools raise
ToolErrors with host-path-free public messages; full detail goes to stderr logs only (stdout is the MCP channel).
Project layout
src/inkscape_mcp/
server.py # FastMCP app + STDIO entry point (register_tools wires every module)
config.py # process Settings + operator-tunable limits (env-driven)
registry.py # doc_id <-> path registry; opens working copies, never mutates originals
operations.py # Operation Record model + persistence (ADR-004)
snapshots.py # snapshot engine + reversible restore
retention.py # snapshot + live-frame retention/cleanup (keep-N/keep-days/hard caps + live-frame
# age/byte caps; explicit boot sweep + prune tool — never implicit)
validate.py # read-only validation engine
quality.py # read-only quality report (wraps validate + inspect + optimizer counts)
logging_setup.py # stderr-only structured logging (stdout reserved for MCP STDIO)
document/ # direct-DOM inspection engine (summary/tree/layers/styles/fonts/assets)
edit/ # safe-edit engines: dom.py (lxml primitives + shared SAFE_ID_RE), pipeline.py
# (snapshot + before/after preview + Operation Record wrapper; risk-classed),
# style.py, text_object.py, transform.py, create.py (element-creation
# + defs/gradients + grouping engines), optimize.py (web-optimize: strip editor
# cruft + drop dead structure + reduce coord precision; reversible), paths.py
# (HIGH-risk path geometry via the Inkscape engine — arg-list Actions →
# safe-parse → DOM-replace)
actions/ # controlled Action surface: capability_map.py (version-keyed Action map +
# discovery, persisted under action-maps/), chains.py (typed ActionStep chains →
# allowlist+map validation → arg-list --actions argv → engine; no raw passthrough;
# reused by the run_raw_action escape hatch)
render/ # Inkscape CLI render/export engine (cli.py) + export profiles (profiles.py) +
# bounded typed batch export (batch.py: item cap + byte budget + dry-run) +
# in-process content-truth verifier (verify.py: PDF is_vector/fonts_outlined,
# raster opaque_px/all_blank — no pdffonts/Pillow subprocess)
engine/ # ADR-007 opt-in warm `inkscape --shell` engine: process.py (one supervised
# worker — read-until-prompt framing, per-command timeout+kill, crash/idle reap),
# manager.py (per-working-copy worker pool, serialized, LRU, freshness reopen),
# ops.py (shell export/action composition). Gated by INKSCAPE_MCP_ENGINE_MODE=shell
# with an automatic per-call CLI fallback; render/paths/chains route through it.
live/ # live read + live write + live view: transport ABC + capability-aware
# backend selection, extension-socket + DBus backends, protocol.py wire schema
# (v3: read + semantic write + view-only commands, region/scale render),
# session manager, render/sync, edit.py (write + view engine reusing semantics
# + bounded view validators), records.py (Live Operation Records + approval gate),
# scene.py (LiveScene), diff.py (focused visual diff), loop.py (perceive→decide→act→observe orchestrator — composes the above, zero new authority),
# cache.py (bounded LRU render cache keyed (doc_revision, viewport, scale) +
# coalescing budget; freshness via the revision key), helper_extension/ (runs inside
# Inkscape). Gate on by default.
prompts/ # MCP Prompts (architecture §4.1): live.py (live_canvas_assist — live-view loop entry
# point), library.py (export/recolor orientation prompts), authoring.py
# (compose_artwork / restyle_artwork — generative on-ramp prompts)
resources/ # MCP resource templates (runtime caps, document/{id}/..., live/{session,selection,operations})
runtime/ # Inkscape capability probe
tools/ # typed @mcp.tool modules: system, document, validate, quality, export,
# profiles, export_batch, optimize, snapshots, style,
# text_object, create (element-creation + defs/gradients + grouping),
# transform, paths (path geometry), actions (discovery +
# Action chains + run_raw_action), save, live (read + write)
workspace/ # sandbox/path safety, limits, risk policy, safe XML parse, subprocess wrapper
scripts/ # install-live-helper.sh (Linux/macOS/Git-Bash) + .ps1 (Windows): copy the live
# helper extension into Inkscape's user extensions dir, resolved dynamically;
# gen_llms_txt.py: regenerate llms.txt / llms-full.txt from the live registry
llms.txt # GENERATED LLM index (one line + risk class per tool); do not hand-edit
llms-full.txt # GENERATED full manifest (full descriptions + key params + prompts + resources)
evals/ # deterministic tool-usability harness: tool_selection_scenarios.json +
# run_eval.py (drives how_do_i/intents; reports tool-selection accuracy). ruff-checked.
# run_live_eval.py: OPTIONAL report-only live-agent runner (same dataset/scorer).
examples/ # ready-to-copy MCP host configs (claude_desktop_config.json, mcp.json)
tests/ # pytest; Inkscape-dependent tests marked @pytest.mark.inkscapeInstall / config / compatibility / troubleshooting docs: docs/install/.
Driving the server from an agent (create→render→export loop, snapshots, risk/approval gate, tool
selection): docs/agent-usage-guide.md.
Development
Stack: Python ≥ 3.12 ·
uv· FastMCP 3.x ·lxml· Pillow (live visual diff) · Inkscape CLI (per-call, plus an opt-in warminkscape --shellengine — ADR-007) · STDIO transport.Conventions: small typed tools (no portmanteau /
run_action(string)), risk-classed, mutating ops emit Operation Records and never overwrite originals, subprocess via arg-lists. SeeCONTRIBUTING.mdfor the full contributor workflow + conventions.Lint / format:
ruff(selectsE,F,I,B,UP,S,RUF;S603/S607are intentionally ignored because the Inkscape CLI adapter needs subprocess — safety enforced by arg-lists + review).Types:
mypy --strictoversrc.Tests:
pytest; mark Inkscape-binary tests with@pytest.mark.inkscape.
uv run pytest # full suite
uv run pytest -m "not inkscape" # skip tests needing the Inkscape binary
uv run ruff check --fix . && uv run ruff format .
uv run mypy srcLicense
MIT © Johannes Sood
Available Tools
87 toolsadd_linear_gradientAdd linear gradientA
Add a <linearGradient> to the document <defs> (created if absent).
When to use: defining a directional colour fade to paint with. For a centred/radial fade use
add_radial_gradient; after defining, apply it via set_fill(doc_id, ids, "url(#grad-id)").
Key params: stops is a list of {offset, color, opacity?} (≥ 1): offset a 0..1 number or
0%..100% percentage, color a validated colour, optional opacity in [0, 1]. The vector runs
(x1, y1) -> (x2, y2) (numbers or percentages; default a left-to-right sweep).
Return shape: CreateResult — object_id is the gradient id (use as url(#id) paint),
bbox=None (a def, not a drawn shape), plus the pipeline fields.
Example: add_linear_gradient(doc_id, [{"offset": 0, "color": "#fff"}, {"offset": 1, "color": "#3366cc"}])
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium (reversible write-new on the working copy; original untouched).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| x1 | No | 0% | |
| x2 | No | 100% | |
| y1 | No | 0% | |
| y2 | No | 0% | |
| stops | Yes | ||
| doc_id | Yes | ||
| object_id | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| bbox | No | |
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| object_id | Yes | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, destructiveHint=false), description adds risk class 'medium (reversible write-new on working copy; original untouched)', advises rendering before trusting, and mentions restore_snapshot as revert option. This provides valuable behavioral context.
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?
Well-structured with clear sections: purpose, when-to-use, parameter details, return shape, example, and risk note. Every sentence adds value without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a gradient-adding tool: describes return shape (CreateResult with object_id and bbox=None), provides usage example, risk assessment, and verification steps. Output schema exists but description sufficiently explains output.
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?
With 0% schema description coverage, the description compensates by explaining stops parameter in detail (offset, color, opacity) and vector coordinates (x1,y1 to x2,y2) with defaults. Not every parameter is fully detailed (doc_id implied, object_id not mentioned), but the essential semantics are covered.
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?
The description clearly states the tool adds a <linearGradient> to the document <defs>, with a specific verb and resource. It distinguishes from sibling add_radial_gradient by explicitly contrasting usage.
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?
Explicitly states when to use (directional colour fade) and when not (centred/radial fade, recommending add_radial_gradient). Provides a usage example and mentions applying the gradient via set_fill, giving clear context for selecting this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
add_radial_gradientAdd radial gradientA
Add a <radialGradient> to the document <defs> (created if absent).
When to use: defining a centred/radial colour fade to paint with. For a directional fade use
add_linear_gradient; after defining, apply via set_fill(doc_id, ids, "url(#gradient-id)").
Key params: stops is a list of {offset, color, opacity?} (≥ 1), as for the linear gradient.
Centred at (cx, cy) with radius r (numbers or percentages; default a centred 50% circle);
fx / fy optionally set the focal point.
Return shape: CreateResult — object_id is the gradient id (use as url(#id) paint),
bbox=None, plus the pipeline fields.
Example: add_radial_gradient(doc_id, [{"offset": 0, "color": "#fff"}, {"offset": 1, "color": "#000"}])
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium (reversible write-new on the working copy; original untouched).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| r | No | 50% | |
| cx | No | 50% | |
| cy | No | 50% | |
| fx | No | ||
| fy | No | ||
| stops | Yes | ||
| doc_id | Yes | ||
| object_id | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| bbox | No | |
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| object_id | Yes | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A4.7/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes return shape (CreateResult with object_id and pipeline fields), warns about rendering before trusting, and classifies risk as medium (reversible write-new). This adds context beyond annotations, though no auth or rate limit details.
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?
Compact yet comprehensive: one paragraph with clear sections (action, usage, key params, return shape, example, risk warning). Every sentence adds value, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema, the description covers everything needed: what it does, when to use, parameter details, return shape, example, and safety warning. No gaps for an agent to misuse.
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?
With 0% schema description coverage, the description compensates well by explaining stops (with format), cx, cy, r, fx, fy and their defaults. An example is provided. However, doc_id and object_id are not explained, but they are standard parameters.
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?
The description clearly states it adds a radialGradient to the document defs, and distinguishes from the sibling tool add_linear_gradient by specifying when to use each.
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?
Explicitly specifies when to use (centred/radial colour fade), when not to (directional fade -> use add_linear_gradient), and how to apply the gradient afterwards with set_fill.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
apply_editsApply edits (batch)ADestructive
Apply an ordered list of typed DOM edits to a document as ONE atomic, reversible operation.
When to use: making SEVERAL edits to one document in a single call (draw + style + arrange,
re-theme + rename, …) instead of N separate tool round-trips. Each member is the SAME typed
edit the dedicated tool exposes — apply_edits adds atomicity + one snapshot, not new
authority. For a single edit, call the dedicated tool (set_fill, move_object, …); for path
geometry or cross-document composition use those tools directly (they are NOT batchable).
Key params: edits is a non-empty, ordered list (max 64) of typed edits, each tagged by an op
field that selects its schema — e.g. {"op": "create_rect", "x": 0, "y": 0, "width": 100, "height": 60, "fill": "#3366cc"}, {"op": "set_fill", "object_ids": ["logo"], "color": "red"},
{"op": "move_object", "object_id": "logo", "dx": 10, "dy": 0}. Supported ops mirror the typed
DOM tools: set_fill / set_stroke / set_opacity / replace_color / apply_palette /
replace_text / set_font / duplicate_object / rename_object / delete_object (high) /
move_object / scale_object / rotate_object / resize_canvas / normalize_viewbox /
tile / create_rect / create_circle / create_ellipse / create_line / create_polygon /
create_polyline / create_path / create_text / create_group / group_objects /
reparent_object / create_use / add_linear_gradient / add_radial_gradient. Validation is
two-phase: ALL members are validated before any mutation (one bad edit leaves the document
byte-identical), then applied in order with all-or-nothing rollback on any failure. If ANY
member is high-risk (a delete_object edit) the WHOLE batch is HIGH and requires a non-empty
approval_token; otherwise it is medium.
Render and look before you trust the edit: a batch changes several things at once, so call
render_preview (or live_render_view in live mode) afterwards and inspect the result before
relying on it — and restore_snapshot(doc_id, snapshot_id) reverts the whole batch in one step.
Return shape: BatchEditResult — the pipeline fields for the single batch operation
(operation_id, snapshot_id, changed, before/after preview; reversible) PLUS edit_count
and the effective risk_class.
Example: apply_edits(doc_id, [{"op": "create_rect", "x": 0, "y": 0, "width": 100, "height": 60, "fill": "#eee", "object_id": "bg"}, {"op": "create_text", "x": 10, "y": 30, "text": "Hi"}])
Risk class: medium (effective risk is the MAX over members; a delete_object member escalates
the batch to high and requires approval_token). Reversible via the single pre-batch snapshot.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| edits | Yes | ||
| doc_id | Yes | ||
| approval_token | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| edit_count | Yes | |
| risk_class | Yes | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the annotations: it describes atomicity, reversibility, two-phase validation (validate-then-apply), all-or-nothing rollback, risk classification (medium vs high based on delete_object), requirement for approval_token for high risk, and the snapshot mechanism for revert. Annotations only indicate destructiveHint: true; the description enriches this with detailed operational behavior.
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?
The description is well-structured and front-loaded with the core purpose, then usage guidance, parameter details, validation, risk, and return shape. However, it is relatively verbose; while every sentence adds value, a slightly more condensed presentation could be achieved without losing clarity. Still, it's highly effective and organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (batch edits with many op types), the description is remarkably complete: it covers purpose, when to use, parameter semantics, validation behavior, risk levels, return shape (BatchEditResult with pipeline fields), and includes an example. The schema and annotations are supplemented well, and the description leaves no major gaps for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for top-level parameters, so the description bears the full burden. It thoroughly explains the `edits` parameter: a non-empty ordered list (max 64) of typed edits, each with an `op` field, lists all supported ops, and provides examples. It also explains `approval_token` context (required for high risk). This adds extensive meaning beyond the schema's raw structure.
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?
The description clearly states: 'Apply an ordered list of typed DOM edits to a document as ONE atomic, reversible operation.' It distinguishes from siblings by specifying that for a single edit use the dedicated tool, and for path geometry or cross-document composition use those tools directly. This provides a specific verb+resource and differentiates from alternatives.
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?
The description explicitly includes a 'When to use' section: 'making SEVERAL edits to one document in a single call... instead of N separate tool round-trips.' It also states: 'For a single edit, call the dedicated tool... for path geometry or cross-document composition use those tools directly (they are NOT batchable).' This gives clear when-to-use and when-not-to-use guidance, referencing alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
apply_paletteApply paletteADestructive
Apply many from -> to colour replacements in a single reversible operation.
When to use: re-theming / rebranding a document's colours in one shot. For a single colour swap
use replace_color; to recolour specific objects use set_fill / set_stroke.
Key params: mapping maps each source colour to its replacement; every key AND value is
strictly colour-validated UP FRONT — a typo'd or non-colour entry (e.g. notacolor) is rejected
with a ToolError BEFORE any mutation, op record, or snapshot is created. Each reuses
the replace_color matching logic. scope_ids, if given, confines all replacements to those
elements' subtrees.
Return shape: EditResult — operation_id, snapshot_id, changed (a real before/after
content diff), before/after preview; the whole palette is applied under one snapshot
(reversible).
Example: apply_palette(doc_id, {"#ff0000": "#3366cc", "#00ff00": "#66cc33"})
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes | ||
| mapping | Yes | ||
| scope_ids | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations show destructiveHint=true; description adds validation fails before mutation, single snapshot for reversal, risk class, and return shape. Discloses preview recommendation.
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?
Well-structured with sections, but slightly lengthy. Front-loaded with purpose. Each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, parameters, return shape, error handling, risk, and preview recommendation. Output schema exists, so return is explained. Complete for a complex mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, description explains mapping validation (typod colors rejected with ToolError), scope_ids confinement, and provides example. Fully compensates.
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?
Clear verb+resource: 'Apply many colour replacements in a single reversible operation.' Distinguishes from siblings like replace_color, set_fill, set_stroke.
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?
Explicit when-to-use: 're-theming / rebranding a document's colours in one shot.' Provides alternatives: for single swap use replace_color; for specific objects use set_fill/set_stroke.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
capture_frameCapture frameARead-only
Capture the next numbered PNG screenshot in a per-run frame series.
When to use: documenting a scripted edit sequence step-by-step. For a one-off check use
`render_preview`; to gather a finished series use `list_frames`.
Key params: `series` (sanitized; defaults to `run`) groups frames into a folder under
`artifacts/frames/<series>/`; the index is derived from the filesystem (highest existing
`frame-NNN` + 1) — monotonic, survives a restart, never clobbers. `label` is folded into the
frame name. Renders the whole canvas exactly like `render_preview` (no UI chrome). INLINE RASTER
: the PNG is returned inline by default (gated by max_output_bytes); inline=False
returns only the structured result.
Return shape: `FrameResult` — `artifact_path` / `workspace_relative_path` (same value),
`format`, `width_px`/`height_px`, `series`, `frame_index` (1-based), `stale`. With an inline
image, a `ToolResult` carrying the same fields plus the image block.
Example: `capture_frame(doc_id, series="cleanup", label="after-simplify")`
Risk class: low (render to the managed artifacts dir; no original overwrite, no Operation
Record).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| label | No | ||
| doc_id | Yes | ||
| inline | No | ||
| series | No | ||
| width_px | No | ||
| max_output_bytes | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| stale | No | |
| doc_id | Yes | |
| format | Yes | |
| series | Yes | |
| width_px | Yes | |
| height_px | Yes | |
| frame_index | Yes | |
| artifact_path | Yes | |
| workspace_relative_path | Yes |
TDQS
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark as readOnlyHint=true and destructiveHint=false; description adds details like rendering full canvas without UI chrome, indexing behavior (monotonic, survives restart, no clobber), and risk class (low, no overwrite). No contradiction with 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?
Well-structured with sections (purpose, when to use, key params, return shape, example, risk). Slightly lengthy but all information is valuable and front-loaded. Could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters and output schema, description covers indexing, artifact path, return shape (FrameResult fields), inline vs. structured, and risk. Example provided. Completeness is high.
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 has 0% description coverage, but description explains key parameters: series (sanitized, defaults to run), label (folded into name), inline (controls output), and max_output_bytes. Width_px is not elaborated, so not fully exhaustive.
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?
Clearly states the tool captures the next numbered PNG screenshot in a per-run frame series. Distinguishes from siblings by mentioning render_preview for one-off checks and list_frames for gathering series.
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?
Explicitly provides when to use (documenting scripted edit sequences) and when not to, with alternatives: render_preview for one-off, list_frames for finished series.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
check_live_supportCheck live supportARead-only
Report which live transports are available on this host (read-only; no connection).
When to use: checking live readiness before live_connect. To install the socket helper use
live_install_helper; for the full runtime matrix use list_capabilities.
Key params: none. Probes the extension-socket bridge (any OS) and the DBus fast-path (Linux/BSD) independently — never assuming one by OS. Safe regardless of whether live mode is enabled or a session is running.
Return shape: LiveSupport — live_enabled, any_available, best_transport,
helper_installed, per-transport transports probes (best-first), and notes.
Example: check_live_support()
Risk class: low (read-only probe).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| notes | No | |
| platform | Yes | OS platform string (linux/darwin/windows). |
| transports | No | Per-transport probe results, ranked best-first. |
| live_enabled | Yes | Master gate state (X1; default on). |
| any_available | Yes | Whether any transport is available right now. |
| best_transport | No | Best read-capable available transport, or null. |
| helper_installed | Yes | Whether the extension-socket helper is installed under a data dir. |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds significant context: probes extension-socket and DBus independently, safe regardless of live mode, and no session assumption. No contradictions.
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?
Well-structured with bullet points, front-loaded purpose, and every sentence adds value. Efficient use of words with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, rich annotations, and output schema reference, the description is complete: covers usage, behavior, return shape, example, and risk class.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100%. The description explains that no params are needed, and adds value by describing the probe behavior and return shape.
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?
The description clearly states the tool reports which live transports are available, specifies it's read-only and no-connection, and distinguishes from siblings like live_connect, live_install_helper, and list_capabilities. It uses a specific verb and resource.
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?
Explicitly states when to use ('checking live readiness before live_connect') and lists alternatives ('live_install_helper', 'list_capabilities'). Provides clear context and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
compose_gridCompose gridA
Lay out N DIFFERENT assets in a grid (contact / spec sheet) in ONE reversible call.
When to use: building a multi-asset sheet — one cell per DIFFERENT document or object — in a
single call (no per-asset loop, no lxml subtree extract). To repeat ONE object into a grid use
tile; to graft a single composed subtree use insert_svg_fragment.
Key params: supply EXACTLY ONE source mode — doc_ids (one whole document per cell) OR
object_ids together with source_doc_id (objects from one document per cell). The grid fills
ROW-MAJOR over rows x cols cells of size cell (user units); fewer assets than cells leaves
trailing cells empty. Each asset is deep-copied (every id re-minted, intra-clone refs rewritten,
no id clashes), wrapped in a <g> translated to its cell origin and, with scale_to_fit
(default True), uniformly DOWN-scaled to fit cell - 2*padding (never upscaled).
gap/padding (default 0) space the cells. target_doc_id composes INTO an existing document;
omit it to create a new blank document sized to the whole grid. Bounded: rows*cols ≤ the
engine cell cap; the asset count must not exceed the cell count.
Return shape: ComposeGridResult — an EditResult (one operation_id + one pre-mutation
snapshot for the whole sheet, reversible via restore_snapshot) plus target_doc_id (the new
id when a blank doc was created), rows/cols, and cells (the ordered placement plan: per
asset its grid coords, new cell-group id, and a short source label).
Example: compose_grid(3, 4, 64, doc_ids=["d1","d2",...,"d12"]) lays a 12-icon system into a
3x4 sheet in one call.
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium (creates a new tracked document or composes into one; sources never mutated).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| gap | No | ||
| cell | Yes | ||
| cols | Yes | ||
| rows | Yes | ||
| doc_ids | No | ||
| padding | No | ||
| object_ids | No | ||
| scale_to_fit | No | ||
| source_doc_id | No | ||
| target_doc_id | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| cols | Yes | |
| rows | Yes | |
| cells | Yes | |
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| target_doc_id | Yes | |
| preview_before | No |
TDQS
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses deep-copy, scaling behavior, grid fill order, cell bound, reversibility, risk class; annotations are minimal so description carries full burden and excels.
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?
Well-structured with sections (purpose, when to use, key params, return, example, caution). Slightly verbose but every sentence adds value; no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complexity (10 params, output schema exists), description covers purpose, usage, behavior, parameter semantics, return shape, and risk. Output schema handles return details.
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?
Adds meaning beyond schema: explains source mode (doc_ids vs object_ids+source_doc_id), scale_to_fit default, gap/padding, target_doc_id. With 0% schema coverage, description compensates well but not every param is detailed.
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?
Specifies verb 'compose', resource 'grid of different assets', scope 'one reversible call', and distinguishes from siblings 'tile' and 'insert_svg_fragment'.
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?
Explicitly states when to use (multi-asset sheet) and when not (use 'tile' for repeating one object, 'insert_svg_fragment' for single subtree), plus key param guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_circleCreate circleA
Create a <circle> centred at (cx, cy) with radius r (> 0).
When to use: drawing a circle / disc. For an oval use create_ellipse; for a box use
create_rect.
Key params: r > 0; inserted into parent_id (must exist) or the document default parent;
object_id to pin the id. Optional fill / stroke / stroke_width paint it in
this call (validated like set_fill / set_stroke; default None = unpainted).
Return shape: CreateResult — object_id (new id), analytic bbox, plus the pipeline fields
(operation_id, snapshot_id, changed, before/after preview).
Example: create_circle(doc_id, 50, 50, 25, fill="red")
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium (reversible write-new on the working copy; original untouched).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| r | Yes | ||
| cx | Yes | ||
| cy | Yes | ||
| fill | No | ||
| doc_id | Yes | ||
| stroke | No | ||
| object_id | No | ||
| parent_id | No | ||
| stroke_width | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| bbox | No | |
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| object_id | Yes | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A4.7/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it creates a new element, mentions reversibility via restore_snapshot, and risk class medium. Adds context beyond 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?
Organized with clear sections: purpose, usage, params, return, example, safety. Every sentence adds value, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary aspects: function, parameters, return shape, example, safety. Output schema exists for return values, and the description completes the picture.
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?
Explains key parameters like r>0, cx, cy, fill, stroke, stroke_width, parent_id, object_id with validation notes. With 0% schema coverage, it compensates well, though doc_id is only in example.
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?
The description clearly states it creates a `<circle>` with center (cx,cy) and radius r. It distinguishes from siblings by mentioning alternatives for ovals and rectangles.
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?
Explicitly says 'When to use: drawing a circle / disc' and provides alternatives. Lacks explicit when-not but gives sufficient context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_documentCreate documentA
Create a blank, tracked working-copy document from scratch — NO source file required.
When to use: starting fresh authoring with the create_* / compose tools when there is no SVG
to open. To open an EXISTING file use open_document; to set the whole SVG body afterwards use
set_document_svg.
Key params: width / height are the page size in user units (both > 0). viewBox is an
optional explicit "minx miny w h" box (a 0 0 width height box is synthesized when omitted,
so the document is never viewBox-less). background is an optional validated colour (hex /
rgb() / hsl() / named keyword — never CSS-injectable) painted as a full-page rect; omit for
a transparent page. The generated document is validate_document-clean.
Return shape: OpenDocumentResult (same as open_document) — doc_id (addresses a fully
tracked working copy: snapshots, reversibility, reload) and summary.
Example: create_document(800, 600, background="#ffffff")
Risk class: medium (creates a new tracked document; no existing state mutated).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| width | Yes | ||
| height | Yes | ||
| viewBox | No | ||
| background | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| summary | Yes | Top-level document summary (viewBox / page / size / counts). |
TDQS
A4.7/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds significant context: 'Risk class: medium (creates a new tracked document; no existing state mutated),' explains the generated document is validate_document-clean, and mentions the output shape and tracking features. It could be slightly more concise, but adds value beyond 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?
The description is well-structured with clear sections: summary, usage, key parameters, return shape, example, and risk class. Every sentence adds value, though it is a bit long. A minor trim would make it more concise, but still effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 params, no enums, and an output schema, the description covers everything: parameter details, default behavior (viewBox synthesis), return shape references (OpenDocumentResult), risk class, and even an example. It is complete for an agent to understand and use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/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 fully. It does: explains width/height are in user units (>0), viewBox is optional with format 'minx miny w h' and synthesized default, background is validated colour types with anti-injection. This adds essential meaning beyond 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?
The description explicitly states 'Create a blank, tracked working-copy document from scratch — NO source file required.' and distinguishes from siblings like open_document and set_document_svg, making the purpose very clear and specific.
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?
The description provides a clear 'When to use' section: 'starting fresh authoring...when there is no SVG to open.' It also states when not to use: 'To open an EXISTING file use open_document; to set the whole SVG body afterwards use set_document_svg.' This gives explicit guidance with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_ellipseCreate ellipseA
Create an <ellipse> centred at (cx, cy) with radii rx / ry (> 0).
When to use: drawing an oval / ellipse. For a perfect circle use create_circle; for a box use
create_rect.
Key params: rx / ry > 0; inserted into parent_id (must exist) or the document default
parent; object_id to pin the id. Optional fill / stroke / stroke_width paint
it in this call (validated like set_fill / set_stroke; default None = unpainted).
Return shape: CreateResult — object_id (new id), analytic bbox, plus the pipeline fields
(operation_id, snapshot_id, changed, before/after preview).
Example: create_ellipse(doc_id, 50, 50, 30, 18, fill="#0a0")
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium (reversible write-new on the working copy; original untouched).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cx | Yes | ||
| cy | Yes | ||
| rx | Yes | ||
| ry | Yes | ||
| fill | No | ||
| doc_id | Yes | ||
| stroke | No | ||
| object_id | No | ||
| parent_id | No | ||
| stroke_width | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| bbox | No | |
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| object_id | Yes | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-readOnly and non-destructive, and the description adds significant behavioral context: it's a write-new operation on the working copy, reversible, medium risk. It also recommends using render_preview to verify, which aligns with the annotations and provides actionable safety information.
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?
The description is well-structured with sections (purpose, usage, key params, return shape, example, risk). While it is relatively long, every sentence adds value and is front-loaded with essential information. Could be slightly trimmed but overall effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 parameters, 5 required, output schema exists), the description covers all necessary aspects: creation semantics, parameter constraints, optional styling, return shape, example, and risk/revert guidance. It provides complete context for correct usage.
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?
With 0% schema description coverage, the description compensates well by explaining all key parameters (cx, cy, rx, ry, fill, stroke, stroke_width, parent_id, object_id) and their constraints. Only doc_id is not explicitly described but is clear from context. It adds meaning beyond the bare schema types.
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?
The description states the tool creates an `<ellipse>` element with specific parameters (cx, cy, rx, ry). It clearly distinguishes from sibling tools `create_circle` (for perfect circles) and `create_rect` (for boxes), providing a clear and specific verb-resource mapping.
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?
Explicitly states 'When to use: drawing an oval / ellipse' and directs to alternatives for other shapes. It also provides constraints (rx/ry > 0, parent_id must exist) and a risk classification, offering thorough usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_groupCreate groupA
Create an empty <g> group inside parent_id (must exist) or the document default parent.
When to use: making an EMPTY group to populate later. To wrap EXISTING objects in a new group
use group_objects; to move one object into an existing group use reparent_object.
Key params: parent_id (must exist) or the document default parent; object_id to pin the id.
Return shape: CreateResult — object_id is the new group id, bbox=None (empty), plus the
pipeline fields (operation_id, snapshot_id, changed, preview).
Example: create_group(doc_id)
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium (reversible write-new on the working copy; original untouched).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes | ||
| object_id | No | ||
| parent_id | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| bbox | No | |
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| object_id | Yes | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses behavior beyond annotations: return shape (`CreateResult` with fields), reversibility via `restore_snapshot`, risk class medium, and warning to render before trusting. No contradictions with 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?
Well-structured: action, usage guidelines, key params, return shape, example, warning. Every sentence adds value without repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary aspects: purpose, usage, parameters, return shape, example, and risk. Output schema exists, so description focuses on key points, and example provides minimal but sufficient guidance.
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?
Adds meaning beyond schema: `parent_id` must exist, `object_id` is for pinning the id. Schema coverage is 0%, so description compensates well, though `doc_id` is not elaborated (but is obvious).
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?
The description clearly states it creates an empty `<g>` group inside a parent. It distinguishes from siblings by specifying when to use `group_objects` and `reparent_object` for wrapping existing objects or moving one object.
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?
Explicitly states when to use (making an empty group to populate later) and when not to use (alternatives for wrapping or moving objects). Includes a risk class and advice to render before trusting, providing clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_icon_setCreate icon setARead-only
Export a multi-size square PNG icon set from the source document.
When to use: producing a standard square icon set in one call. For a responsive web bundle use
export_web_profile; for arbitrary batch specs use export_batch.
Key params: sizes is the list of square px sizes (defaults to 16, 32, 48, 64, 128, 256). Each
must be a positive integer no greater than the configured pixel cap; an out-of-range or
non-positive size is rejected before Inkscape runs and no partial set is written. out_dir
writes the set into a caller-chosen dir — a relative out_dir anchors to the
workspace ROOT and is sandbox-checked (out-of-workspace rejected "path rejected: outside
workspace"); name_prefix tags each file.
Return shape: ProfileExportResult — profile, applied_settings, and artifacts (each
carries its requested_size_px, a workspace_relative_path, and content-truth
opaque_px/all_blank).
Example: create_icon_set(doc_id, sizes=[16, 32, 64], out_dir="dist/icons")
Risk class: low (export to a sandbox-checked dir; no original overwrite).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sizes | No | ||
| doc_id | Yes | ||
| out_dir | No | ||
| name_prefix | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| profile | Yes | |
| artifacts | Yes | |
| applied_settings | Yes |
TDQS
A4.7/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that out-of-range sizes are rejected before Inkscape runs, out_dir is sandbox-checked, and no partial set is written. Describes return shape and risk class. Adds value beyond annotations which already indicate readOnlyHint=true and destructiveHint=false.
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?
Well-organized with sections: purpose, when to use, key params, return shape, example, risk. Every sentence earns its place; no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters, presence of output schema, and annotations, description covers usage, param details, output format, example, and risk. Fully sufficient for an agent to understand and invoke correctly.
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?
With 0% schema coverage, description explains key parameters: sizes constraint (positive integer ≤ cap), out_dir anchoring to workspace root, name_prefix tagging. Adds meaning beyond bare 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?
Clearly states 'Export a multi-size square PNG icon set from the source document.' Distinguishes from siblings export_web_profile and export_batch by specifying when to use each.
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?
Explicitly provides when-to-use: 'producing a standard square icon set in one call.' Directs to alternatives for other needs, giving clear usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_lineCreate lineA
Create a <line> from (x1, y1) to (x2, y2).
When to use: a single straight segment. For a multi-segment open run use create_polyline; for
a closed shape use create_polygon.
Key params: endpoints (x1, y1) / (x2, y2); inserted into parent_id (must exist) or the
document default parent; object_id to pin the id. Optional stroke / stroke_width
paint the segment in this call (a line is unfilled by nature, so no fill; validated like
set_stroke; default None = unpainted).
Return shape: CreateResult — object_id (new id), analytic bbox (the segment's axis-aligned
extent), plus the pipeline fields (operation_id, snapshot_id, changed, preview).
Example: create_line(doc_id, 0, 0, 100, 100, stroke="black", stroke_width="2")
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium (reversible write-new on the working copy; original untouched).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| x1 | Yes | ||
| x2 | Yes | ||
| y1 | Yes | ||
| y2 | Yes | ||
| doc_id | Yes | ||
| stroke | No | ||
| object_id | No | ||
| parent_id | No | ||
| stroke_width | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| bbox | No | |
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| object_id | Yes | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=false and destructiveHint=false. The description adds context: risk class 'medium (reversible write-new)', mentions rendering and revert options, and explains that the original is untouched. This goes well beyond 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?
The description is well-structured but slightly verbose. It front-loads purpose and usage, then details parameters, return shape, example, and risk. However, the return shape explanation is somewhat redundant given the output schema exists, and there is minor repetition (e.g., 'render and look before you trust'). Still clear and effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters, 5 required, 0% schema coverage, and the presence of an output schema, the description covers everything: purpose, usage, parameter details, return type with field explanations, example, risk classification, and post-usage actions. It is exceptionally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description fully compensates. It explains each parameter (x1, y1, x2, y2, doc_id, stroke, stroke_width, object_id, parent_id), notes that line is unfilled (no fill), and describes default behavior (unpainted, parent_id default). This adds critical meaning.
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?
The description clearly states it creates a line segment with specific endpoints (x1,y1 to x2,y2). It distinguishes from sibling tools like create_polyline (multi-segment open) and create_polygon (closed shape), fulfilling the need for specificity.
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?
Explicitly tells when to use: 'a single straight segment'. Provides direct alternatives: use create_polyline for multi-segment open runs and create_polygon for closed shapes. This gives clear decision guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_pathCreate pathA
Create a <path> with the validated d data string.
When to use: freeform / bezier / curve geometry from a d string. For simple primitives prefer
create_rect / create_circle / create_polygon; to edit an existing path's geometry use the
paths tools (simplify_path, combine_paths, ...).
Key params: d validated against a strict charset (digits, whitespace, ,, ., sign,
exponent, SVG path command letters only) and length-bounded; geometry is NOT fully parsed; into
parent_id (must exist) or the document default parent. Optional fill / stroke /
stroke_width paint it in this call (validated like set_fill / set_stroke;
default None = unpainted).
Return shape: CreateResult — object_id (new id), bbox=None (paths are not analytically
measured), plus the pipeline fields (operation_id, snapshot_id, changed, preview).
Example: create_path(doc_id, "M0 0 L100 0 L50 80 Z", fill="#222")
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium (reversible write-new on the working copy; original untouched).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| d | Yes | ||
| fill | No | ||
| doc_id | Yes | ||
| stroke | No | ||
| object_id | No | ||
| parent_id | No | ||
| stroke_width | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| bbox | No | |
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| object_id | Yes | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses multiple behavioral details beyond annotations: d validation (strict charset, length-bounded, not fully parsed), optional paint parameters validated like set_fill/set_stroke, default unpainted, parent_id requirement, return shape with bbox=None, and risk class 'medium reversible write-new'. The annotations only indicate readOnlyHint=false and destructiveHint=false, so the description carries the full burden and does so thoroughly.
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?
The description is well-structured with clear sections (When to use, Key params, Return shape, Example, Render advice, Risk class). It is slightly lengthy but every section adds value. Front-loading the main purpose helps quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all necessary aspects: purpose, usage conditions, parameter behavior, return shape with example, risk assessment, and integration with sibling and preview tools. Given the tool's complexity and the presence of an output schema (mentioned), the description is highly complete.
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?
With 0% schema description coverage, the description explains most key parameters: d (validation details), parent_id (must exist or default), fill/stroke/stroke_width (optional, validated, default None). However, doc_id and object_id are not explicitly described, leaving a minor gap. Overall, it adds significant meaning beyond the raw 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?
Clearly states the verb 'create' and resource 'path', with explicit differentiation from sibling tools like create_rect, create_circle, and editing paths via simplify_path. The description includes specific when-to-use guidance, making the purpose unmistakable.
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?
Provides explicit when to use (freeform/bezier/curve geometry) and when not (prefer primitives for simple shapes; use paths tools for edits). Includes a recommendation to render and inspect via render_preview before trusting the edit, and mentions restore_snapshot for reversion. This offers clear context for safe and appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_polygonCreate polygonA
Create a closed <polygon> from points (≥ 1 (x, y) pairs).
When to use: a closed many-sided shape (triangle, hexagon, ...). For an OPEN run use
create_polyline; for curves use create_path.
Key params: points ≥ 1 (x, y) pairs; inserted into parent_id (must exist) or the document
default parent; object_id to pin the id. Optional fill / stroke / stroke_width
paint it in this call (validated like set_fill / set_stroke; default None = unpainted).
Return shape: CreateResult — object_id (new id), analytic bbox (extent of the points),
plus the pipeline fields (operation_id, snapshot_id, changed, preview).
Example: create_polygon(doc_id, [(0, 0), (50, 0), (25, 40)], fill="#fc0")
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium (reversible write-new on the working copy; original untouched).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fill | No | ||
| doc_id | Yes | ||
| points | Yes | ||
| stroke | No | ||
| object_id | No | ||
| parent_id | No | ||
| stroke_width | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| bbox | No | |
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| object_id | Yes | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (write, not destructive), description adds risk class (medium, reversible write-new), warns to render before trusting, and notes that changes are reversible via restore_snapshot.
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?
Well-structured into sections (purpose, usage, params, return, example, caution, risk), each sentence adds value, no redundancy, front-loaded with core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage guidelines, all parameters, return shape, example, and risk; sufficient for an agent to correctly select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, description explains points as at least one (x,y) pair, parent_id must exist or uses default, object_id to pin id, and fill/stroke/stroke_width validated like set_fill/set_stroke with defaults.
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?
Explicitly states creation of a closed `<polygon>` from points, and distinguishes from siblings by specifying that create_polyline is for open runs and create_path for curves.
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?
Provides a 'When to use' section with explicit alternatives for open runs and curves, and mentions that parent_id must exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_polylineCreate polylineA
Create an open <polyline> from points (≥ 1 (x, y) pairs).
When to use: a connected open run of segments. For a CLOSED shape use create_polygon; for a
single segment use create_line; for curves use create_path.
Key params: points ≥ 1 (x, y) pairs; inserted into parent_id (must exist) or the document
default parent; object_id to pin the id. Optional fill / stroke / stroke_width
paint it in this call (validated like set_fill / set_stroke; default None = unpainted).
Return shape: CreateResult — object_id (new id), analytic bbox (extent of the points),
plus the pipeline fields (operation_id, snapshot_id, changed, preview).
Example: create_polyline(doc_id, [(0, 0), (50, 20), (100, 0)], stroke="blue")
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium (reversible write-new on the working copy; original untouched).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fill | No | ||
| doc_id | Yes | ||
| points | Yes | ||
| stroke | No | ||
| object_id | No | ||
| parent_id | No | ||
| stroke_width | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| bbox | No | |
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| object_id | Yes | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate the tool is not read-only and not destructive. The description adds valuable behavioral context: it creates a new object, inserts into a parent, optionally paints, and notes the risk class as 'medium (reversible write-new).' It also advises rendering a preview before relying on the edit, which goes beyond 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?
The description is well-structured and concise: first line states purpose, then usage guidance, key parameters, return shape, an example, and finally safety advice. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 params, output schema present), the description covers all essential aspects: purpose, usage context, parameter details, return format, concrete example, and risk mitigation. It feels fully complete for an agent to use correctly.
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?
The input schema has 7 parameters with 0% description coverage. The description compensates by explaining key parameters: points must be ≥1 (x,y) pairs, parent_id must exist or default to document, object_id pins the id, and fill/stroke/stroke_width are optional. However, doc_id is not explained beyond being required. Overall, it adds significant meaning over the raw 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?
The description states exactly what the tool does: 'Create an open <polyline> from points (≥ 1 (x, y) pairs).' It clearly names the resource and action, and differentiates from siblings by specifying when to use create_polygon, create_line, or create_path instead.
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?
The description provides explicit when-to-use guidance: 'a connected open run of segments.' It also gives specific alternatives for closed shapes, single segments, and curves, making it easy for the agent to choose the correct tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_rectCreate rectangleA
Create a <rect> at (x, y) sized width / height (> 0), with optional corner radii.
When to use: drawing a rectangle / square / box. For an ellipse use create_circle /
create_ellipse; for a freeform shape use create_path.
Key params: width / height > 0; rx / ry optional corner radii; inserted into parent_id
(must exist) or the document default parent (first layer, else root); object_id to pin the id.
Optional fill / stroke / stroke_width paint the shape IN THIS CALL — validated
exactly like set_fill / set_stroke (colour or url(#id); CSS length) — so no mandatory
second styling call (default None = unpainted, prior behaviour).
Return shape: CreateResult — object_id (new id), analytic bbox, plus the pipeline fields
(operation_id, snapshot_id, changed, before/after preview).
Example: create_rect(doc_id, 10, 10, 100, 60, rx=8, fill="#3366cc")
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium (reversible write-new on the working copy; original untouched).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | ||
| y | Yes | ||
| rx | No | ||
| ry | No | ||
| fill | No | ||
| width | Yes | ||
| doc_id | Yes | ||
| height | Yes | ||
| stroke | No | ||
| object_id | No | ||
| parent_id | No | ||
| stroke_width | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| bbox | No | |
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| object_id | Yes | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A4.6/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate write operation (readOnlyHint false) but not destructive. Description adds context: 'reversible write-new', validation of fill/stroke like set_fill/set_stroke, and advice to preview before trusting. However, annotations already convey the basic safety profile.
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?
Description is well-structured with core purpose, usage, params, return, example, risk. Front-loaded but includes some redundancy (e.g., validation detail). Efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 12 parameters, output schema exists, and annotations provide base info, the description adds all needed context: return shape, example, risk class, validation behavior. No 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 0%, but description explains key parameters: width/height >0, rx/ry optional, parent_id must exist, object_id pins id, fill/stroke validated like set_fill. Provides meaningful guidance beyond raw schema types.
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?
Description clearly states it creates a `<rect>` element with position, size, and optional radii. Distinguishes from siblings like create_circle, create_ellipse, create_path by explicitly naming alternatives.
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?
Explicitly states when to use ('drawing a rectangle / square / box') and when not (ellipse, freeform). Also provides risk class and revertibility advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_snapshotCreate snapshotARead-only
Snapshot the current working copy of a document and index it.
When to use: checkpointing before a risky edit so you can roll back. To browse checkpoints use
list_snapshots; to roll back use restore_snapshot. (Mutating tools auto-snapshot; this is an
explicit, manual checkpoint.)
Key params: optional label tags the snapshot (length-bounded; over the cap is rejected).
Return shape: SnapshotInfo — the new snapshot_id plus its metadata.
Example: create_snapshot(doc_id, label="before cleanup")
Risk class: low (write-new snapshot; original untouched).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| label | No | ||
| doc_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| seq | Yes | |
| file | Yes | |
| label | No | |
| created_at | Yes | |
| size_bytes | Yes | |
| snapshot_id | Yes | |
| operation_id | No |
TDQS
A4.1/5.0
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description claims a write operation ('write-new snapshot') while annotations declare readOnlyHint=true, creating a direct contradiction. Despite providing additional context like risk class, the inconsistency severely undermines transparency.
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?
Four sentences, well-structured with clear sections (purpose, usage, params, return shape, risk). No unnecessary words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, when to use, key params, return shape (SnapshotInfo with metadata), example, and risk class. Despite annotation contradiction, the description itself is complete for what the tool does.
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?
With 0% schema coverage, the description adds meaningful detail: label is optional, length-bounded, and over-cap results in rejection. The example demonstrates usage. Could mention doc_id type/format but overall compensates well for schema gaps.
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?
The description clearly states the verb 'snapshot the current working copy of a document and index it,' specifying both action and resource. It distinguishes itself from sibling tools list_snapshots and restore_snapshot by stating its purpose.
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?
Explicit guidance on when to use (checkpointing before risky edits) and when not to (browsing or rollback should use other tools). Also notes that mutating tools auto-snapshot, so this is an explicit manual checkpoint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_textCreate textA
Create a <text> element anchored at (x, y) holding text.
When to use: adding a new label / caption. To change EXISTING text content use replace_text;
to restyle its font use set_font.
Key params: text is length-bounded and rejects control characters other than tab / newline /
carriage return (stored as a text node, no markup injection); inserted into parent_id (must
exist) or the document default parent. Optional fill / stroke / stroke_width
paint the glyphs in this call (validated like set_fill / set_stroke; default None =
unpainted). For font family/size/weight use set_font.
Return shape: CreateResult — object_id (new id), bbox=None (text is not analytically
measured), plus the pipeline fields (operation_id, snapshot_id, changed, preview).
Example: create_text(doc_id, 20, 40, "Hello", fill="#111")
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium (reversible write-new on the working copy; original untouched).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | ||
| y | Yes | ||
| fill | No | ||
| text | Yes | ||
| doc_id | Yes | ||
| stroke | No | ||
| object_id | No | ||
| parent_id | No | ||
| stroke_width | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| bbox | No | |
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| object_id | Yes | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses text constraints (length-bounded, no control chars except tab/newline/carriage return), parameter validation (fill/stroke like `set_fill`/`set_stroke`), return shape, and risk class medium (reversible write-new). No contradiction with 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?
Well-structured with labeled sections (When to use, Key params, Return shape, Example, Caution). Every sentence adds value without redundancy. Concise yet comprehensive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters (4 required), output schema exists, and annotations present, the description covers all critical aspects: creation effect, parameter details, return format, example, and safe usage advice. Fully complete for agent selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description explains key parameters: `text` constraints, `parent_id` default behavior, `fill`/`stroke`/`stroke_width` painting semantics, and `x`/`y` as anchor. Provides example using `fill` parameter.
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?
The description clearly states it creates a `<text>` element at specific coordinates. It distinguishes from sibling tools like `replace_text` and `set_font`, providing precise purpose.
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?
Explicitly says when to use (adding new label/caption) and when not (for existing text use `replace_text`, for font use `set_font`). Includes caution to render before trusting and mentions reversibility via `restore_snapshot`.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_useCreate use referenceA
Create a <use href="#href_id"> referencing an existing same-document object.
When to use: instancing / cloning an existing element so edits to the original propagate. To
deep-COPY (independent) use duplicate_object; to grid-repeat use tile.
Key params: href_id MUST name an existing element (safe-id charset, required to exist);
external / javascript: / url(...) references are rejected — only a same-document #id. Into
parent_id (must exist) or the document default parent. Placement (translate-scaling trap):
<use> applies x / y as a translation BEFORE its transform, so scale(2) + x="10"
shifts by 20 — prefer EITHER x / y alone OR fold the translation into transform
(e.g. translate(10,0) scale(2)); do not mix x / y with a scaling transform.
Return shape: CreateResult — object_id is the new <use> id, bbox=None, plus the pipeline
fields (operation_id, snapshot_id, changed, preview).
Example: create_use(doc_id, "logo", x=200, y=0)
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium (reversible write-new on the working copy; original untouched).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | ||
| y | No | ||
| doc_id | Yes | ||
| href_id | Yes | ||
| object_id | No | ||
| parent_id | No | ||
| transform | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| bbox | No | |
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| object_id | Yes | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond annotations. It details the return shape (CreateResult with fields), the translate-scaling trap (x/y as translation before transform, warning not to mix with scaling transform), validation (only same-document #id, rejected external/javascript/url), and risk class (medium, reversible write-new). Annotations already indicate write and non-destructive, which is consistent.
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?
The description is well-structured, starting with purpose, then usage guidelines, key params with warnings, return shape, example, and safety advice. It is front-loaded with essential information. While it is relatively long, every sentence adds value, and the organization makes it easy to parse. A slight trim could improve conciseness, but it remains highly effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters, complex SVG behavior, and an output schema, the description is exceptionally complete. It covers the placement trap, validation rules, return shape, and provides a concrete example. The advice to use render_preview and restore_snapshot further ensures safe usage. All aspects necessary for correct invocation are addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Given 0% schema description coverage, the description comprehensively explains key parameters: href_id must name existing element, parent_id must exist or default, x/y translation behavior, and transform usage with the scaling trap. It also notes default parent, object_id optional, and includes an example. This fully compensates for the lack of schema descriptions.
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?
The description clearly states 'Create a `<use href="#href_id">` referencing an existing same-document object' and distinguishes from siblings by specifying alternatives for deep-copy (duplicate_object) and grid-repeat (tile). The verb and resource are specific, and the tool's unique role in SVG instancing is well-defined.
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?
Explicit 'When to use' context is provided: 'instancing / cloning an existing element so edits to the original propagate.' It also gives clear when-not-to-use examples: 'To deep-COPY (independent) use duplicate_object; to grid-repeat use tile.' Additionally, it advises to render and inspect before trusting, and mentions restore_snapshot for reversion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delete_objectDelete objectADestructive
Delete objects by id from a document in ONE reversible, snapshot-backed operation.
When to use: dropping one or more existing elements (e.g. stray seed paths) without a Read +
set_document_svg full-document rebuild. Get ids from find_objects / inspect_document. To
MOVE an object into another group use reparent_object; to rename rather than remove use
rename_object.
Key params: object_ids is a non-empty list of ids to remove; an id that is not present is
silently skipped (deleting an already-absent object is a successful no-op, not an error). The
document root cannot be deleted. Because deletion is HIGH risk, a real removal requires a
non-empty approval_token (minted out of band, bound to this one operation); without it the
policy gate refuses the op and nothing is written.
Return shape: DeleteResult — all EditResult fields (operation_id, snapshot_id,
changed, before/after preview; the edit lands on the working copy only, reversible via
restore_snapshot) PLUS affected_ids, the ids that were actually removed. When NONE of the
ids existed the call is a genuine no-op: changed=False, empty operation_id/snapshot_id,
and affected_ids=[] (no snapshot or Operation Record written).
Example: delete_object(doc_id, ["seed1", "seed2"], approval_token="…")
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: high (delete; approval-gated, reversible via pre-op snapshot — original untouched).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes | ||
| object_ids | Yes | ||
| approval_token | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| snapshot_id | Yes | |
| affected_ids | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds significant behavioral details beyond annotations: deletion is reversible, silently skips non-existing ids, cannot delete document root, requires approval_token, and return shape details. Annotations already indicate destructiveHint=true, so no contradiction.
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?
Well-structured, front-loads purpose, then usage guidelines, parameter details, return shape, example, and caution. Slightly long but all content is useful; no wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists, description explains return shape (DeleteResult with all EditResult fields plus affected_ids) and edge cases. Also provides risk class and safety steps (render preview, restore_snapshot). Fully adequate.
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 has 0% description coverage, but description provides substantial meaning: object_ids as non-empty list with silent skip behavior, approval_token required for high risk (minted out of band), and doc_id implied. This compensates well for the bare 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?
Clear verb+resource: 'Delete objects by id from a document in ONE reversible, snapshot-backed operation.' Distinguishes from reparent_object and rename_object, providing explicit alternatives.
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?
Explicitly states when to use (dropping elements without full rebuild), when not to use (moving or renaming), and where to get ids (find_objects/inspect_document). Also covers prerequisites like approval_token for high risk operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
diagnose_runtimeDiagnose runtimeARead-only
Probe the local Inkscape + Python runtime fresh and return the capability matrix.
When to use: to FORCE a fresh probe (e.g. after installing Inkscape/fonts). For a cheap cached
read use list_capabilities; for live-transport detail use check_live_support.
Key params: none. Re-runs the probe every call and refreshes the cache that list_capabilities
and inkscape://runtime/capabilities serve.
Return shape: Capabilities — Inkscape version, available actions, export formats, data dirs,
inkex, DBus/live transport availability, fonts, the curated intents map, and the authoritative
MCP tool surface (tool_count + tools: name + one-line purpose + risk class, from the live
registry). Missing backends are reported in notes, never crashed.
Example: diagnose_runtime()
Risk class: low (read-only probe).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| notes | No | Human-readable degradation messages (e.g. 'inkscape not found'). |
| tools | No | The authoritative MCP tool surface: each entry is {name, purpose, risk}, sourced from the live FastMCP registry. Counts only `@mcp.tool`s (not resources or prompts). Populated by the tools/system layer before serving; empty on a raw probe. |
| actions | No | Action ids from `inkscape --action-list` (enumeration only; not executable). |
| intents | No | Curated natural-language goal → tool(s) map: each entry is {goal_pattern, tools, how_to, group}. The same data the read-only `how_do_i` tool matches against; surfaced here so an agent can browse the whole map. Guidance only — executes nothing, no raw-action hatch (ADR-003). Host-independent (not probed). |
| probed_at | Yes | UTC ISO-8601 timestamp of when this probe ran. |
| font_count | No | Font faces reported by `fc-list` (0 ⇒ fontconfig broken/absent). |
| inkex_path | No | Path to bundled `inkex/__init__.py`, or null if not found. |
| tool_count | No | Authoritative number of registered `@mcp.tool`s. Equals `len(tools)` and the live `mcp.list_tools()` count — one unambiguous number so agents stop deriving it. Populated from the live FastMCP registry, not probed from Inkscape. |
| export_types | No | Export-type tokens parsed from the `--export-type=` list in inkscape --help. |
| inkex_version | No | `__version__` read from inkex sources (NOT imported), or null if unknown. |
| meets_minimum | No | Whether the detected version is >= MINIMUM_VERSION (1, 3, 0). |
| user_data_dir | No | Inkscape user data directory (`--user-data-directory`). |
| python_version | Yes | Interpreter version running this server. |
| inkscape_binary | No | Absolute path to the Inkscape binary, or null if absent. |
| system_data_dir | No | Inkscape system data directory (`--system-data-directory`). |
| dbus_session_bus | No | Whether DBUS_SESSION_BUS_ADDRESS is set (session bus present). |
| has_path_actions | No | Whether any `path-*` action is present. |
| inkscape_version | No | Raw version string reported by `inkscape --version`. |
| has_export_actions | No | Whether any `export-*` action is present. |
| has_object_actions | No | Whether any `object-*` action is present. |
| has_select_actions | No | Whether any `select*` action is present. |
| inkscape_available | Yes | Whether an Inkscape binary was found and ran. |
| shell_mode_available | No | Whether `inkscape --shell` (the headless shell engine/ADR-007) can run here. True when an Inkscape binary is present (shell mode ships on all supported 1.x). Whether the warm engine is USED is the separate INKSCAPE_MCP_ENGINE_MODE gate. |
| dbus_inkscape_present | No | Whether an `org.inkscape.Inkscape*` name is on the session bus right now. |
| inkscape_version_tuple | No | Parsed (major, minor, patch) version, or null if unparsable. |
| live_extension_socket_available | No | Whether the live helper extension is installed under a data dir (unshipped). |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral details beyond annotations: re-runs every call, refreshes cache, reports missing backends in notes without crashing, and clarifies risk class as low. This complements the readOnlyHint and destructiveHint annotations with actionable context.
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?
The description is well-structured: purpose sentence, usage guidelines, key params, return shape, example, and risk class. Every sentence is informative and concise, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (runtime probe with multiple outputs) and the presence of an output schema, the description fully explains the return shape (version, actions, formats, etc.) and side effects (cache refresh). It is complete for agent decision-making.
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?
With zero parameters and 100% schema coverage, the description adds minimal but helpful confirmation ('Key params: none'). This avoids ambiguity, though it does not add extensive new meaning beyond 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?
The description clearly states it probes the local runtime and returns a capability matrix, using specific verbs ('probe') and noun ('capability matrix'). It distinguishes from siblings by explicitly naming alternatives: list_capabilities (cached) and check_live_support (live-transport detail).
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?
The description explicitly says when to use ('to FORCE a fresh probe') and gives alternatives ('for a cheap cached read use list_capabilities'). It also states key params are none, providing clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
duplicate_objectDuplicate objectA
Duplicate an object or group in place, inserting the clone right after the original.
When to use: copying one object once. To copy into a grid use tile; to instance via <use>
use create_use; to change an id without copying use rename_object.
Key params: the clone re-ids every contained id uniquely and rewrites its internal references so
it is self-consistent. An optional new_id (validated safe and unused) names the clone's top
element; otherwise a suffixed id is generated.
Return shape: EditResult — operation_id, snapshot_id, changed, before/after preview; the
new top id is reported in the summary. Lands on the working copy only (reversible).
Example: duplicate_object(doc_id, "icon", new_id="icon_copy")
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium (reversible write-new on the working copy; original untouched).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes | ||
| new_id | No | ||
| object_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant behavioral context beyond annotations: the clone re-ids every contained id, rewrites internal references, generates a validated safe new_id, and is reversible (lands on working copy only). Also gives risk class 'medium (reversible write-new)'. No contradiction with 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?
Well-structured with clear sections: main function, when to use, key params, return shape, example, and caution. Every sentence adds value without redundancy. Efficient for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, behavior, parameters, return shape (EditResult with summary), example, and safety note. Despite having an output schema, the description adds context about what to expect (e.g., 'the new top id is reported in the summary'). No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage; the description compensates by explaining what each parameter does: 'the clone re-ids every contained id uniquely... an optional `new_id` (validated safe and unused) names the clone's top element; otherwise a suffixed id is generated.' Includes an example call.
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?
The description uses a specific verb+resource: 'Duplicate an object or group in place, inserting the clone right after the original.' It distinguishes from siblings by naming alternatives (tile, create_use, rename_object) later in the description.
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?
Explicitly provides when-to-use ('copying one object once') and when-not-to-use with clear alternatives: 'To copy into a grid use `tile`; to instance via `<use>` use `create_use`; to change an id without copying use `rename_object`.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
export_batchExport batchARead-only
Run a bounded batch of typed export specs in one call (dry-run by default).
When to use: exporting many sizes/formats/objects in one call. For a single export use
export_document / export_object; for a standard icon set use create_icon_set.
Key params: specs is a typed list (each: format png/pdf/svg, optional width_px, optional
object_id for a single object). Bounded: at most a fixed number of specs per call and a
total-output byte budget (byte_budget, default: the per-document artifact budget).
dry_run=True (DEFAULT) validates and returns the plan + projected sizes + within_budget,
writing nothing; dry_run=False refuses cleanly if the projection exceeds the budget. out_dir
writes into a caller-chosen dir — relative anchors to the workspace ROOT,
sandbox-checked (out-of-workspace rejected "path rejected: outside workspace"); name_prefix
tags each file.
Return shape: BatchResult — item_count, per-item entries (each with a
workspace_relative_path on a real run), projected/actual total size, and within_budget.
Example: export_batch(doc_id, [{"format": "png", "width_px": 256}], dry_run=False)
Risk class: low (artifact-only export to a sandbox-checked dir; composes the engine).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| specs | Yes | ||
| doc_id | Yes | ||
| dry_run | No | ||
| out_dir | No | ||
| byte_budget | No | ||
| name_prefix | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| items | No | |
| doc_id | Yes | |
| dry_run | Yes | |
| item_count | Yes | |
| byte_budget | Yes | |
| within_budget | Yes | |
| actual_total_bytes | Yes | |
| projected_total_bytes | Yes |
TDQS
A4.2/5.0
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description contradicts the readOnlyHint annotation (true) by detailing that dry_run=False writes files to the workspace. This is a serious inconsistency; the description itself is otherwise transparent about behavior, but the contradiction forces a score of 1.
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?
The description is front-loaded with the core action in the first line, well-structured with sections for usage, parameters, return shape, and example. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, no schema descriptions, presence of output schema), the description covers purpose, usage context, parameter details, return shape, example, and risk class. It is comprehensively informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining each parameter's purpose, including format options, optional fields, default values, and special behaviors like byte_budget and sandbox-checked out_dir.
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?
The description clearly states the tool exports a bounded batch of typed export specs. It distinguishes from sibling tools like export_document and export_object for single exports and create_icon_set for icon sets, making the purpose specific and unambiguous.
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?
Explicitly states when to use (exporting many sizes/formats/objects in one call) and when not to (single exports or standard icon sets), naming alternatives. Provides clear guidance on dry-run vs real execution and budget constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
export_documentExport documentARead-only
Export the whole document to PNG, PDF, or SVG.
When to use: producing a final file of the whole document. For one object use export_object;
for many sizes/formats at once use export_batch; for a web/print bundle use the profile tools.
Key params: format is one of "png"/"pdf"/"svg" (others rejected). PNG honors width_px
(pixel-capped before Inkscape runs); PDF/SVG are vector and ignore it. out_dir writes
into a caller-chosen dir — a relative out_dir anchors to the workspace ROOT and is
sandbox-checked (out-of-workspace is rejected with "path rejected: outside workspace");
name_prefix tags the filename. INLINE RASTER: a PNG is returned inline by default
(gated by max_output_bytes); PDF/SVG are never embedded; inline=False opts out.
Return shape: ExportResult — artifact_path / workspace_relative_path (same value),
format, width_px/height_px (TRUE size for PNG, None for vector), stale. With an inline
image, a ToolResult carrying the same fields plus the image block.
Example: export_document(doc_id, "png", width_px=1024)
Risk class: low (render/export to a sandbox-checked dir; no original overwrite).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes | ||
| format | Yes | ||
| inline | No | ||
| out_dir | No | ||
| width_px | No | ||
| name_prefix | No | ||
| max_output_bytes | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| stale | No | |
| doc_id | Yes | |
| format | Yes | |
| width_px | Yes | |
| all_blank | No | |
| height_px | Yes | |
| is_vector | No | |
| opaque_px | No | |
| artifact_path | Yes | |
| fonts_outlined | No | |
| workspace_relative_path | Yes |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes sandbox-checked directory, inline behavior, format-specific parameter handling, and return shape. Annotations only indicate readOnly hint; description adds crucial behavioral context beyond 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?
Well-organized with sections for purpose, usage, key params, return shape, example, and risk class. Every sentence is informative and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 7 parameters and output schema, the description covers return shape, inline image handling, parameter behavior, and risk class. It is comprehensive for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description thoroughly explains key parameters (format, width_px, out_dir, name_prefix, inline, max_output_bytes) with constraints and behaviors, adding significant meaning.
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?
The description clearly states 'Export the whole document to PNG, PDF, or SVG,' specifying the verb, resource, and supported formats. It distinguishes from siblings like export_object, export_batch, and profile tools.
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?
Explicitly states when to use: 'producing a final file of the whole document' and lists alternatives for one object, batch, or bundle, providing clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
export_objectExport objectARead-only
Export a single object (by id) to PNG, PDF, or SVG.
When to use: exporting one object, clipped to its own bbox (get the id from find_objects). For
the whole document use export_document; for many at once use export_batch.
Key params: object_id must exist and match the safe SVG-id charset (else rejected before it
reaches Inkscape). format is one of "png"/"pdf"/"svg". out_dir writes into a
caller-chosen dir — a relative out_dir anchors to the workspace ROOT and is sandbox-checked
(out-of-workspace is rejected with "path rejected: outside workspace"); name_prefix tags the
filename. INLINE RASTER: a PNG is returned inline by default (gated by
max_output_bytes); PDF/SVG never embedded; inline=False opts out.
Return shape: ExportResult — artifact_path / workspace_relative_path (same value),
format, width_px/height_px (TRUE size for PNG, None for vector), stale. With an inline
image, a ToolResult carrying the same fields plus the image block.
Example: export_object(doc_id, "logo", "svg")
Risk class: low (render/export to a sandbox-checked dir; no original overwrite).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes | ||
| format | No | png | |
| inline | No | ||
| out_dir | No | ||
| width_px | No | ||
| object_id | Yes | ||
| name_prefix | No | ||
| max_output_bytes | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| stale | No | |
| doc_id | Yes | |
| format | Yes | |
| width_px | Yes | |
| all_blank | No | |
| height_px | Yes | |
| is_vector | No | |
| opaque_px | No | |
| artifact_path | Yes | |
| fonts_outlined | No | |
| workspace_relative_path | Yes |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate safe read-only operation. Description adds extensive behavioral details: validation of object_id charset, sandbox checking for out_dir, inline PNG behavior gated by max_output_bytes, and return shape including stale flag.
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?
Well-organized with front-loaded purpose, clear paragraphs, and an example. Slightly verbose in explaining inline behavior but still efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all 8 parameters, explains return shape (ExportResult), mentions risk class, and gives usage context with sibling differentiation. Output schema exists, but description adds value for inline image handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates fully. It explains the role and constraints of object_id, format, out_dir, name_prefix, inline, and max_output_bytes, adding meaning beyond 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?
The description clearly states 'Export a single object (by id) to PNG, PDF, or SVG.' It distinguishes from siblings by naming 'export_document' and 'export_batch' as alternatives for different use cases.
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?
Explicitly states 'When to use: exporting one object, clipped to its own bbox' and provides when-not scenarios with specific sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
export_print_profileExport print profileARead-only
Export a print-oriented PDF (vector, page area) of the whole document.
When to use: producing a press-safe PDF. For web assets use export_web_profile; for a plain
(non-print) PDF/PNG/SVG use export_document.
Key params: applies real print-specific Inkscape settings (PDF version pinned to 1.4 + text
outlined to paths) so output is press-safe and ALWAYS differs from a plain PDF export — even for
text-free docs, since the plain export defaults to PDF 1.5 while this pins 1.4 (header
%PDF-1.4, a deterministic byte difference). out_dir writes into a
caller-chosen dir — a relative out_dir anchors to the workspace ROOT and is sandbox-checked
(out-of-workspace rejected "path rejected: outside workspace"); name_prefix tags the file.
Return shape: ProfileExportResult — profile, the auditable applied_settings, and
one PDF in artifacts with a workspace_relative_path plus content-truth is_vector /
fonts_outlined (true vector when both hold).
Example: export_print_profile(doc_id, out_dir="dist/print")
Risk class: low (export to a sandbox-checked dir; no original overwrite).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes | ||
| out_dir | No | ||
| name_prefix | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| profile | Yes | |
| artifacts | Yes | |
| applied_settings | Yes |
TDQS
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and destructiveHint. The description adds valuable behavioral context: output always differs from plain PDF due to PDF version pinning, exports to sandbox-checked dir, no original overwrite.
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?
The description is well-structured with sections (When to use, Key params, Return shape, Example, Risk class) and front-loaded with the main purpose. Slightly long but every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description explains the return shape and provides an example. It covers complexity well, ensuring an agent can use the tool correctly.
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?
The schema has 0% description coverage, but the description explains out_dir (anchors to workspace root, sandbox-checked) and name_prefix (tags file). doc_id is not explicitly described but is implied. This compensates for the schema gap.
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?
The description clearly states the tool exports a print-oriented PDF with specific properties. It distinguishes from sibling tools like export_web_profile and export_document by stating when each should be used.
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?
The description explicitly provides usage guidelines: use for press-safe PDF, not for web assets (use export_web_profile) or plain export (use export_document).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
export_setExport setARead-only
Batch-export a SET of documents in one call: per-doc results + aggregate + verdict.
When to use: exporting a whole multi-document system (e.g. a 12-icon set) at the same sizes /
formats in one call, with the set's total byte footprint and a cross-doc consistency check. For
a SINGLE document use export_batch; for an icon set from one doc use create_icon_set.
Key params: doc_ids is a non-empty, duplicate-free set; specs is the SAME typed ExportSpec
list export_batch takes (applied to EVERY document). dry_run / byte_budget / out_dir /
name_prefix behave exactly as on export_batch (composed, not reimplemented), per document; a
name_prefix is recommended with out_dir so the per-doc files do not collide. The whole set
is rejected if ANY document's export_batch fails (no partial result).
Return shape: ExportSetResult — per_doc (each {doc_id, result} with the standard
BatchResult), total_items and total_bytes aggregated across the set (projected on a dry
run, actual on a real run), and consistency — the structured cross-doc verdict over the set's
viewBox / stroke-width / id-naming conventions (per property: agree/disagree + the differing
values + which doc_ids differ).
Example: export_set(["d1","d2","d3"], [{"format": "png", "width_px": 64}], dry_run=False, out_dir="dist", name_prefix="icon")
Risk class: low (artifact-only export to a sandbox-checked dir; composes the per-doc engine).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| specs | Yes | ||
| doc_ids | Yes | ||
| dry_run | No | ||
| out_dir | No | ||
| byte_budget | No | ||
| name_prefix | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| dry_run | Yes | |
| per_doc | Yes | |
| consistency | Yes | Structured cross-document consistency audit over a set. One :class:`ConsistencyProperty` per audited property (``viewBox``, ``stroke_width``, ``id_naming``). ``consistent`` is True iff EVERY audited property agrees across the set. Not prose: an agent reads ``properties`` to see precisely which property disagrees and which ``doc_ids`` carry which value. |
| total_bytes | Yes | |
| total_items | Yes |
TDQS
A4.6/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds that the whole set is rejected on any single failure (no partial results) and labels risk as low, composing the per-doc engine. This adds useful behavioral context beyond 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?
The description is well-structured with clear sections (purpose, when to use, key params, return shape, example, risk class) and is front-loaded with the main action. It is concise for the complexity but could potentially be shortened slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters, output schema, and complex behavior, the description covers all necessary aspects: purpose, usage, parameter semantics, return shape (per_doc, total_items, total_bytes, consistency with detailed cross-doc verdict), and a concrete example. It feels complete and self-contained.
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?
With 0% schema description coverage, the description compensates by explaining key params: doc_ids must be non-empty and duplicate-free, specs is identical to export_batch's list, and dry_run/byte_budget/out_dir/name_prefix behave exactly as in export_batch. It also notes name_prefix is recommended to avoid collisions. Not all six params are fully detailed, but the critical ones are well-covered.
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?
The description explicitly states 'Batch-export a SET of documents in one call' with specific outputs (per-doc results + aggregate + verdict). It distinguishes from siblings like export_batch and create_icon_set, providing clear differentiation.
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?
The 'When to use' section gives explicit context for multi-document exports and names alternatives (export_batch for single documents, create_icon_set for icon sets). This provides clear guidance on when to choose this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
export_web_profileExport web profileARead-only
Export a web-oriented asset set: a responsive PNG set plus one plain SVG.
When to use: producing a web-ready asset bundle. For a print PDF use export_print_profile; for
a square icon set use create_icon_set; for a single export use export_document.
Key params: PNG widths resolve as — explicit widths (each a PNG); else density scales
applied to width_px (e.g. [1,2,3] -> 1x/2x/3x); else width_px. Every PNG is pixel-capped
before Inkscape runs and distinct on disk; responsive entries report their scale. out_dir
writes the set into a caller-chosen dir so a dist/ tree assembles with no
Bash cp — a relative out_dir anchors to the workspace ROOT and is sandbox-checked
(out-of-workspace rejected "path rejected: outside workspace"); name_prefix tags each file.
Return shape: ProfileExportResult — profile, applied_settings, and ordered artifacts
(ascending width, then one plain SVG last); each carries a workspace_relative_path plus
content-truth fields (PNG: opaque_px/all_blank).
Example: export_web_profile(doc_id, scales=[1, 2, 3], out_dir="dist/web")
Risk class: low (export to a sandbox-checked dir; no original overwrite).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes | ||
| scales | No | ||
| widths | No | ||
| out_dir | No | ||
| width_px | No | ||
| name_prefix | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| profile | Yes | |
| artifacts | Yes | |
| applied_settings | Yes |
TDQS
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true and destructiveHint=false. Description adds risk class (low), no original overwrite, sandbox checking, and pixel-capping behavior. No contradiction with 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?
Well-structured with sections (purpose, usage, key params, return shape, example, risk). Slightly verbose but each sentence adds value. Front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 parameters, 0% schema coverage, and an output schema, the description covers parameter interactions, return shape, typical usage, and risk. Output schema is mentioned but not detailed, which is acceptable since it exists.
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 0%, but description explains key parameters: widths, scales, width_px interaction, out_dir semantics (relative to workspace root, sandbox-checked), and name_prefix. Doc_id is not explained, but the description provides significant value beyond 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?
The description clearly states it exports a web-oriented asset set (responsive PNGs plus SVG). It distinguishes from siblings like export_print_profile, create_icon_set, and export_document.
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?
Explicit 'When to use' section and alternative tools provided. Clearly specifies when this tool is appropriate and when to use siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
find_objectsFind objectsARead-only
Find addressable object ids in a tracked document by tag / paint / text / id-prefix / bbox.
When to use: before an id-taking edit (set_fill, move_object, replace_text,
rotate_object, …) on a document the agent did not author, or to enumerate "every blue rect",
"every text mentioning 'Total'", etc. For the full structural picture (tree / layers / styles /
fonts / assets) plus the same list use inspect_document; to map a goal to a tool, how_do_i.
Key params (all filters optional; supplied filters AND together; none → every addressable
object): tag exact local name ("rect"/"text"/"path"); fill/stroke a paint matched
casing- and hex-shorthand-insensitive ("#FFF" matches "#ffffff") — matching resolves the
FULL CSS cascade so an object painted via a <style> rule / class / id selector or INHERITED
from an ancestor <g> is matched too (the reported fill/stroke stay the per-element
authored token); text a case-insensitive substring of text content; id_prefix an id
prefix; bbox an {x, y, width, height} box kept on INTERSECTION. By default bbox uses the
attribute-derived box and objects with no derivable box (path/text/group/transformed) are
EXCLUDED; set accurate_bbox=true to compute geometry-accurate, transform-/outline-aware boxes
via one batched Inkscape --query-all call (so those objects can match) — it degrades to the
attribute box when the Inkscape engine is unavailable.
Return shape: FindResult — {doc_id, count, objects: [{object_id, tag, bbox?, fill?, stroke?, text?}]}. Objects without an id are never returned (they cannot be targeted). With
accurate_bbox=true, bbox carries the engine box where one was reported.
Example: find_objects("d_ab12", tag="rect", fill="#3366cc")
Risk class: low for the default direct-DOM path (read-only, ADR-005; no snapshot / Operation
Record); accurate_bbox=true adds a read-only Inkscape --query-all invocation (medium, still
no mutation).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | ||
| bbox | No | ||
| fill | No | ||
| text | No | ||
| doc_id | Yes | ||
| stroke | No | ||
| id_prefix | No | ||
| accurate_bbox | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| doc_id | Yes | |
| objects | Yes |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true; description adds details on matching (CSS cascade), return shape, risk class, accurate_bbox behavior, and limitations (objects without id never returned). No contradiction.
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 clear purpose, then usage, param details, return shape, example, risk. Every sentence adds value; well-organized and appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a complex tool with 8 parameters and output schema. Covers all key aspects: when to use, parameter semantics, return format, edge cases (no-id objects, accurate_bbox fallback), and risk level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates by explaining each parameter in detail (tag, fill/stroke, text, id_prefix, bbox, accurate_bbox) with matching rules and default filters.
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?
The description clearly states 'Find addressable object ids in a tracked document by tag / paint / text / id-prefix / bbox', which is specific and distinguishes it from siblings like inspect_document and how_do_i.
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?
Explicitly says 'When to use: before an id-taking edit...' and mentions alternatives (inspect_document, how_do_i), providing clear guidance on when to use this tool versus others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
fit_to_contentFit canvas to contentA
Fit the document's root viewBox to its CONTENT bounding box.
When to use: cropping the page so it frames the drawing exactly. To set an explicit page size
use resize_canvas, to merely repair the viewBox use normalize_viewbox.
Key params: none beyond doc_id. The content bbox is computed by the Inkscape engine
(--query-all, ADR-005 — real geometry, not naive XML) in the document's intrinsic
user-coordinate space (probed against a px-identity copy so the value is STABLE across calls);
only the root viewBox changes. IDEMPOTENT: a second call on an already-fitted document reports
changed=False. Fails with a stable error if the engine is unavailable, the document has no
drawable content, or the bbox is degenerate.
Return shape: EditResult — operation_id, snapshot_id, changed (real before/after content
diff), before/after preview; the edit lands on the working copy only (reversible).
Example: fit_to_content(doc_id)
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A3.9/5.0
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description claims idempotency ('IDEMPOTENT: a second call ... reports changed=False'), but the annotation sets idempotentHint=false, creating a direct contradiction. This is a critical failure and override any positive behavioral disclosures.
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?
The description is well-structured with sections (purpose, when to use, key params, behavior, return shape, example, warning) and front-loads the core purpose. It is slightly verbose when repeating return shape details, but overall efficient for the tool's complexity.
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?
Despite the idempotency contradiction, the description covers usage, behavior, error cases, and a warning. With an output schema existing, it provides ample context for a one-parameter tool. The contradiction slightly undermines completeness, but the description is otherwise thorough.
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?
The input schema has 0% description coverage, so the description must compensate. It clearly states 'Key params: none beyond doc_id', identifying the sole parameter and implying no others. While it doesn't detail doc_id's format, the context of a single required parameter makes it adequate. Baseline for 0 params is 4, and this fits.
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?
The description clearly states the tool's action: 'Fit the document's root viewBox to its CONTENT bounding box.' It uses a specific verb and resource, and distinguishes from siblings like resize_canvas and normalize_viewbox by explicitly contrasting use cases.
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?
The description provides explicit guidance on when to use this tool (cropping the page to frame the drawing) and when to use alternatives (resize_canvas for explicit page size, normalize_viewbox for repairing viewBox). This leaves no ambiguity for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
group_objectsGroup objectsA
Wrap existing objects (object_ids, ≥ 1, all must exist) in a NEW <g>.
When to use: collecting several existing objects under one group. For an EMPTY group use
create_group; to move a single object into an existing group use reparent_object.
Key params: object_ids ≥ 1, all must exist; object_id to pin the new group id. The objects
keep their own transforms / styles; only their parent changes.
Return shape: CreateResult — object_id is the new group id (inserted at the position of the
first target), bbox=None, plus the pipeline fields.
Example: group_objects(doc_id, ["icon", "label"])
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium (reversible write-new on the working copy; original untouched).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes | ||
| object_id | No | ||
| object_ids | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| bbox | No | |
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| object_id | Yes | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, destructiveHint=false), the description reveals that objects keep their transforms/styles, only parent changes, and specifies the return shape (CreateResult). It also states risk class 'medium (reversible write-new)'. No contradiction.
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?
The description is well-structured with sections like 'When to use', 'Key params', 'Return shape', 'Example', and 'Risk class'. It is efficient and front-loaded, but could be slightly more concise by combining some sentences. However, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description explains return shape and pipeline fields. It covers usage guidelines, parameter details, behavioral notes, an example, and a safety note about rendering and restoring. It is fully complete for a tool of this complexity.
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 0%, so the description must compensate. It explains object_ids (≥1, all must exist) and object_id (to pin new group id). The doc_id parameter is mentioned but not detailed, which is acceptable as it's a common parameter. Overall adds significant meaning beyond 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?
The description clearly states the tool wraps existing objects into a new group, using the verb 'Wrap' and the resource 'objects'. It distinguishes from sibling tools create_group and reparent_object by specifying their different use cases.
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?
The description provides explicit when-to-use guidance: 'collecting several existing objects under one group.' It also includes when-not-to-use by directing to alternatives for empty groups (create_group) and single object moves (reparent_object).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
how_do_iHow do IARead-only
Map a natural-language goal to the concrete inkscape-mcp tool(s) that achieve it.
When to use: when you know what you want in words but not which typed tool does it. To browse
the whole map at once read the intents section of list_capabilities; to then resolve an
object id for an id-taking edit use find_objects. Guidance only — not a portmanteau or raw
tool (ADR-002/003); it executes nothing.
Key params: goal is a natural-language description, e.g. "draw a rectangle", "make my svg
smaller for web", "find the red shapes", "export a png".
Return shape: HowDoIResult — exactly one of: an in-scope hit (out_of_scope=False, matches
best-first, each {goal_pattern, tools, how_to, group}); an out-of-scope goal (edit a
JPEG/photo's pixels, run an arbitrary Action/extension/script, fetch from a URL, execute code) →
out_of_scope=True, empty matches, note naming WHY (vector-only / ADR-003 / no-network /
no-exec); or no match → out_of_scope=False, empty matches, note suggesting
list_capabilities / inspect_document.
Example: how_do_i("make my svg smaller for web")
Risk class: low (read-only guidance; no snapshot / Operation Record).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| goal | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| goal | Yes | The goal string that was matched (echoed back). |
| note | No | Reason (out-of-scope) or suggestion (no match); empty on a confident match. |
| matches | No | Best-matching guidance entries (tool name(s) + one-line how-to + group). |
| out_of_scope | No | True when the goal is a known out-of-scope category (see `note` for why). |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. Description adds risk class (low, read-only guidance), explains it executes nothing, and details return shape (three possible outcomes). No contradictions with 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?
Well-structured with sections: purpose, usage, params, return shape, example, risk class. Every sentence adds value; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple parameter and output schema, the description covers all needed context: return cases, exclusions, and references to design documents. Complements sibling tools well.
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?
With 0% schema coverage, the description compensates by explaining the 'goal' parameter as a natural-language description with examples. Provides clear semantic meaning beyond 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?
The description clearly states the tool maps natural-language goals to inkscape-mcp tools, distinguishing it from siblings like list_capabilities and find_objects. Uses specific verb 'map' and resource 'natural-language goal to tools'.
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?
Explicitly states when to use ('when you know what you want in words but not which typed tool does it'), when not to use, and alternatives (list_capabilities, find_objects). Also references ADR-002/003 for design constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
insert_svg_fragmentInsert SVG fragmentA
Insert an agent-composed SVG fragment under a parent (parent_id) or the document root.
When to use: grafting one composed subtree into an existing document (no file round-trip). To
REPLACE the whole document use set_document_svg; for a single typed shape use the create_*
tools.
Key params: svg is ONE element subtree (wrap several siblings in a <g>). parent_id (must
exist) sets where it lands, else the document root. unwrap (default True) controls a <svg>
root: when True the wrapper <svg> is unwrapped and its children grafted (an empty wrapper is
rejected); pass unwrap=False to KEEP an explicit nested <svg> container, inserted as-is
(still allowlist-scrubbed; an empty nested <svg> is then allowed). unwrap has no effect on a
non-<svg> root, which is always inserted intact. Same hardening as set_document_svg
(safe-parse + strict allowlist; <script>, on* handlers, javascript: hrefs, external refs
rejected; only same-document #id allowed). A real run REQUIRES a non-empty approval_token.
The original/source file is never touched.
Return shape: ComposeResult — an EditResult (operation + pre-mutation snapshot links,
reversible via restore_snapshot) extended with the post-adopt validate_document findings
(validation).
Example: insert_svg_fragment(doc_id, "<g>...</g>", parent_id="layer1", approval_token="ok");
to keep a nested container: insert_svg_fragment(doc_id, "<svg>...</svg>", unwrap=False, approval_token="ok").
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: HIGH — requires a non-empty approval_token; without it the op is refused and
nothing is written.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| svg | Yes | ||
| doc_id | Yes | ||
| unwrap | No | ||
| parent_id | No | ||
| approval_token | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| validation | Yes | Structured, machine-readable validation result for one document. `ok` is True iff there are no `error`-severity findings. `error_count` / `warning_count` are convenience tallies over `findings`. |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: hardening (safe-parse, strict allowlist), approval_token requirement, reversibility via restore_snapshot, original file untouched, return shape with validation. No annotation contradiction.
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?
Well-structured with sections for usage, parameters, return, example, and risk. Comprehensive but slightly lengthy; every sentence adds value so still highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all aspects: purpose, usage, parameters, behavior, return value, examples, safety precautions. With output schema present, return shape is summarized appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant meaning beyond schema: explains svg should be one element subtree, unwrap behavior with examples, parent_id requirement, approval_token necessity. Schema coverage is 0% so description fully compensates.
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?
Clearly states 'Insert an agent-composed SVG fragment under a parent or document root.' Distinguishes from siblings by mentioning set_document_svg for replacement and create_* tools for single shapes.
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?
Explicitly provides when to use (grafting composed subtree), when not (use set_document_svg for replace, create_* for single shapes), and suggests using render_preview before trusting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
inspect_documentInspect documentARead-only
Inspect a loaded document: tree, layers, styles, fonts, external assets.
When to use: the go-to overview to understand a document's structure AND discover targetable
object ids before editing. To search for SPECIFIC objects by filter use find_objects; for
quality metrics use quality_report; for well-formedness use validate_document.
Key params: doc_id only (read-only).
Return shape: InspectDocumentResult — summary, tree, layers, styles, fonts,
assets, and objects (flat list of every id-bearing object with tag / bbox / paint / text,
the same ObjectRef shape find_objects returns).
Example: inspect_document(doc_id)
Risk class: low (read-only, direct DOM per ADR-005).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| tree | Yes | |
| fonts | Yes | |
| assets | Yes | |
| layers | Yes | |
| styles | Yes | |
| objects | Yes | |
| summary | Yes |
TDQS
A4.4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds risk class 'low (read-only)' and references ADR-005, providing extra context without contradiction.
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?
Extremely concise and well-structured with bullet points, bold for emphasis, and an example. Every sentence adds value; no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Provides sufficient detail on return shape (InspectDocumentResult with fields), includes an example, and covers risk. Output schema exists, so detailed return specs are not needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. Only states 'Key params: doc_id only (read-only)' but does not explain what doc_id represents or how to obtain it, leaving ambiguity.
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?
Clear verb 'inspect' and resource 'loaded document' with specific aspects listed (tree, layers, styles, etc.). Explicitly distinguishes from siblings like find_objects, quality_report, validate_document.
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?
Explicitly states when to use ('go-to overview') and when not, with specific alternative tools for filtering (find_objects), quality (quality_report), and validation (validate_document).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_capabilitiesList capabilitiesARead-only
Return the cached runtime capability matrix (probed once, then reused).
When to use: the cheap default for "what can this host/server do". To FORCE a re-probe use
diagnose_runtime; to map a single goal to a tool use how_do_i.
Key params: none.
Return shape: Capabilities — same shape as diagnose_runtime, served from cache. Includes an
intents section: the curated natural-language goal → tool(s) map (the same map how_do_i
matches against) so an agent can browse "which tool does X" without one call per goal. Also
carries the authoritative MCP tool surface: tool_count (the one true count of registered
@mcp.tools) and tools (name + one-line purpose + risk class), sourced from the live
registry — so agents read one number instead of deriving it.
Example: list_capabilities()
Risk class: low (read-only).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| notes | No | Human-readable degradation messages (e.g. 'inkscape not found'). |
| tools | No | The authoritative MCP tool surface: each entry is {name, purpose, risk}, sourced from the live FastMCP registry. Counts only `@mcp.tool`s (not resources or prompts). Populated by the tools/system layer before serving; empty on a raw probe. |
| actions | No | Action ids from `inkscape --action-list` (enumeration only; not executable). |
| intents | No | Curated natural-language goal → tool(s) map: each entry is {goal_pattern, tools, how_to, group}. The same data the read-only `how_do_i` tool matches against; surfaced here so an agent can browse the whole map. Guidance only — executes nothing, no raw-action hatch (ADR-003). Host-independent (not probed). |
| probed_at | Yes | UTC ISO-8601 timestamp of when this probe ran. |
| font_count | No | Font faces reported by `fc-list` (0 ⇒ fontconfig broken/absent). |
| inkex_path | No | Path to bundled `inkex/__init__.py`, or null if not found. |
| tool_count | No | Authoritative number of registered `@mcp.tool`s. Equals `len(tools)` and the live `mcp.list_tools()` count — one unambiguous number so agents stop deriving it. Populated from the live FastMCP registry, not probed from Inkscape. |
| export_types | No | Export-type tokens parsed from the `--export-type=` list in inkscape --help. |
| inkex_version | No | `__version__` read from inkex sources (NOT imported), or null if unknown. |
| meets_minimum | No | Whether the detected version is >= MINIMUM_VERSION (1, 3, 0). |
| user_data_dir | No | Inkscape user data directory (`--user-data-directory`). |
| python_version | Yes | Interpreter version running this server. |
| inkscape_binary | No | Absolute path to the Inkscape binary, or null if absent. |
| system_data_dir | No | Inkscape system data directory (`--system-data-directory`). |
| dbus_session_bus | No | Whether DBUS_SESSION_BUS_ADDRESS is set (session bus present). |
| has_path_actions | No | Whether any `path-*` action is present. |
| inkscape_version | No | Raw version string reported by `inkscape --version`. |
| has_export_actions | No | Whether any `export-*` action is present. |
| has_object_actions | No | Whether any `object-*` action is present. |
| has_select_actions | No | Whether any `select*` action is present. |
| inkscape_available | Yes | Whether an Inkscape binary was found and ran. |
| shell_mode_available | No | Whether `inkscape --shell` (the headless shell engine/ADR-007) can run here. True when an Inkscape binary is present (shell mode ships on all supported 1.x). Whether the warm engine is USED is the separate INKSCAPE_MCP_ENGINE_MODE gate. |
| dbus_inkscape_present | No | Whether an `org.inkscape.Inkscape*` name is on the session bus right now. |
| inkscape_version_tuple | No | Parsed (major, minor, patch) version, or null if unparsable. |
| live_extension_socket_available | No | Whether the live helper extension is installed under a data dir (unshipped). |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the result is cached and probed once, which is beyond the annotations (readOnlyHint, destructiveHint). It explains return shape includes intents and tools sections, and states risk class as low. No contradiction with annotations; adds valuable context about caching.
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?
The description is highly concise with front-loaded purpose, then sections for usage, parameters, return shape, example, and risk class. Every sentence provides essential information without redundancy. Structure is clear and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and an output schema, the description covers all necessary aspects: what it returns (including details on intents and tools sections), an example call, risk class, and usage guidance. It is complete for the tool's low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100%. The description explicitly says 'Key params: none' and explains why (cached call with no inputs). This adds meaning beyond the schema by confirming the parameterless nature.
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?
The description clearly states the tool returns the cached runtime capability matrix, and distinguishes it from siblings by specifying when to use diagnose_runtime and how_do_i. The verb 'Return' with the specific resource 'cached runtime capability matrix' makes the purpose unambiguous.
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?
Explicitly provides when-to-use ('cheap default for what can this host/server do'), when-not-to-use ('To FORCE a re-probe use diagnose_runtime; to map a single goal use how_do_i'), and notes there are no key parameters. This gives clear guidance for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_framesList framesARead-only
List the frames of a capture_frame series, ordered by index.
When to use: gathering a whole run's PNGs at the end without re-deriving paths. To produce
frames use capture_frame.
Key params: series is sanitized identically to capture_frame (defaults to run).
Return shape: FrameListResult — doc_id, series, and frames (each a FrameInfo with
frame_index + a resolvable workspace_relative_path), ordered by index; empty when the series
has no frames yet.
Example: list_frames(doc_id, series="cleanup")
Risk class: low (read-only listing of the managed artifacts dir).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes | ||
| series | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| frames | Yes | |
| series | Yes |
TDQS
A4.7/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds return shape details, risk class 'low (read-only listing)', and clarifies the series parameter behavior, providing context beyond 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?
Well-structured with clear sections (summary, when to use, key params, return shape, example, risk class). Every sentence adds value; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive given low complexity: covers purpose, usage, parameters, return shape, and risk. Output schema exists, so detailed return description is not needed. Includes an example for clarity.
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?
Despite 0% schema coverage, description explains the key `series` parameter: sanitized identically to `capture_frame`, defaults to `run`. This adds meaningful context that is not in 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?
Description clearly states it lists frames of a `capture_frame` series, ordered by index. It distinguishes from sibling `capture_frame` by specifying when to use this tool vs producing frames.
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?
Explicit usage guidance: 'When to use: gathering a whole run's PNGs at the end without re-deriving paths.' Also directly contrasts with `capture_frame` for producing frames.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_snapshotsList snapshotsARead-only
List a document's snapshots in order, with metadata.
When to use: choosing which checkpoint to roll back to. To make one use create_snapshot; to
roll back use restore_snapshot.
Key params: none beyond doc_id.
Return shape: SnapshotList — doc_id plus snapshots (each a SnapshotInfo with its id +
metadata), in order.
Example: list_snapshots(doc_id)
Risk class: low (read-only manifest).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| snapshots | No |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's labeling as 'read-only manifest' is consistent and adds context. It also describes the return shape and provides an example, going beyond 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?
Description is efficiently structured with headings, uses only 5 sentences, and every sentence adds value—no fluff. Front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and an output schema, the description covers usage, return shape, example, and risk. Sibling tools are numerous but the description clearly differentiates. No 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 0%, so description must compensate. It identifies the sole parameter `doc_id` and says 'none beyond doc_id,' which is accurate but does not elaborate on its type or constraints. However, given the single parameter and clear naming, this is sufficient for an agent.
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?
Description clearly states the verb+resource: 'List a document's snapshots in order, with metadata.' It also specifies the use case 'choosing which checkpoint to roll back to,' which distinguishes it from siblings like create_snapshot and restore_snapshot.
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?
Explicitly tells when to use ('choosing which checkpoint to roll back to'), when not (use create_snapshot to make one, restore_snapshot to roll back), and includes a risk class note ('low (read-only manifest)').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
live_apply_to_selectionLive: apply to selectionA
Apply a validated style and/or simple transform to the current live selection.
When to use: editing the GUI selection's style/transform live. To insert markup use
live_insert_svg; to edit text use live_set_selected_text; for headless edits use set_fill
/ move_object / etc.
Key params: reuses the headless safe-edit semantics — fill/stroke colour-validated,
stroke_width a CSS length, opacity in [0, 1], transform composed from dx/dy (both
required together), scale (positive), rotate (degrees); at least one input required.
Semantic-only — no arbitrary code, no raw Action (ADR-003). Mutating a running user session is
HIGH risk: REQUIRES an explicit approval_token (refused without one).
Return shape: LiveEditResult — a Live Operation Record with before/after canvas renders,
syncable to a snapshot via live_sync_to_workspace.
Example: live_apply_to_selection(approval_token="ok", fill="#3366cc")
Risk class: high (approval-gated).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dx | No | ||
| dy | No | ||
| fill | No | ||
| scale | No | ||
| rotate | No | ||
| stroke | No | ||
| opacity | No | ||
| stroke_width | No | ||
| approval_token | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| count | No | |
| summary | No | |
| transport | No | |
| affected_ids | No | |
| operation_id | Yes | |
| preview_after | No | |
| undo_friendly | No | |
| preview_before | No |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description goes beyond annotations by stating the high risk of mutating a user session, the requirement for an explicit approval_token, and that it's semantic-only with no arbitrary code. This adds critical context beyond the readOnlyHint=false annotation.
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?
The description is well-structured with a clear first sentence stating purpose, followed by usage guidance, parameter details, return shape, an example, and risk classification. Every sentence adds value without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 params, high risk, mutation), the description covers all essential aspects: when to use, parameter constraints, return value (LiveEditResult with before/after renders), and risk class. The presence of an output schema is supplemented by description of the return shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates fully by explaining each parameter's semantics: color validation, CSS length for stroke_width, opacity range, transform constraints (dx/dy required together, positive scale, degrees for rotate), and the at-least-one-input requirement.
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?
The description clearly states the tool applies a validated style/transform to the current live selection. It distinguishes from siblings by naming alternatives like live_insert_svg and live_set_selected_text.
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?
Explicit 'When to use' section guides the agent to use this for live style/transform editing and lists sibling tools for different tasks (insert, text, headless edits).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
live_arm_socketLive: arm socketA
Auto-arm the extension-socket helper so a programmatic launch gets the FULL live surface.
When to use: bringing up the FULL perceive/compose live command set without a human
Extensions-menu click — a programmatic launch otherwise yields only DBus's reduced
action set. After this returns armed, call live_connect (the socket bridge is then the best
transport). To install the helper files first use live_install_helper; to probe readiness use
check_live_support.
Key params: none. Installs the helper if absent, then LAUNCHES a headful Inkscape with the
helper effect auto-invoked so it binds its loopback socket and advertises a rendezvous — no menu
click. The socket bridge is the cross-platform primary (NOT bound to one OS). Requires the
master live gate. GUI-ONLY: the headful launch needs a display; on a HEADLESS host (CI / box,
no DISPLAY/WAYLAND_DISPLAY) it fails with a clear, stable message (this leg is documented as
deferred there) rather than spawning a doomed process. An already-armed session is reused.
Return shape: SocketArmResult — armed, launched (whether THIS call started Inkscape),
helper_installed, transport, and notes. No host path is carried (sec.12).
Example: live_arm_socket() then live_connect()
Risk class: restricted (launches a headful Inkscape process and writes a server-bundled helper).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| armed | Yes | |
| notes | No | |
| launched | Yes | |
| transport | No | |
| helper_installed | Yes |
TDQS
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses launching headful Inkscape, installing helper, display requirement, clear failure on headless, session reuse, and risk class. No contradiction with annotations; adds value beyond readOnlyHint, destructiveHint etc.
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?
Description is detailed but efficient; each sentence adds value. Slightly long but appropriate for complexity. Front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, behavior, return shape (SocketArmResult), example, risk. Output schema exists; description completes context for tool with side effects and prerequisites.
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?
No parameters in schema; description confirms 'Key params: none'. Baseline 4 applies as no param info needed and description acknowledges absence.
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?
Clearly states verb 'Auto-arm' and resource 'extension-socket helper' with effect of getting 'FULL live surface'. Distinguished from siblings like live_connect, live_install_helper, check_live_support.
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?
Explicitly describes when to use: bringing up full command set without human click, programmatic launch otherwise limited. Mentions post-action call to live_connect, alternative tools for installation and readiness check, and reuse of existing session.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
live_connectLive: connectA
Connect to a running Inkscape over the best-ranked available transport (enables live).
When to use: starting a live session before any other live_* tool. To probe first use
check_live_support; to tear down use live_disconnect.
Key params: prefer selects the profile. read (default) is the best READ-capable transport
(extension-socket primary; full selection/inspect surface) but is MODAL on the socket bridge —
the GUI freezes for the session. no_freeze drives the GUI WITHOUT freezing (Linux DBus path): the export-based active-doc read, live_render_view, live_set_viewport, and
live_apply_to_selection are no-freeze; selection-id reads (live_get_selection /
live_inspect_selection) and live_insert_svg / live_set_selected_text are NOT available
over DBus and stay modal. Requires the master gate (INKSCAPE_MCP_LIVE_ENABLED). With no
transport available it fails cleanly without affecting headless tools.
Return shape: LiveSession — the chosen transport, active document, and connection state.
Example: live_connect(prefer="no_freeze")
Risk class: medium (establishes a transport; read-only thereafter).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| prefer | No | read |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| notes | No | Clean human-readable status notes. |
| enabled | Yes | Whether live mode is permitted (master gate, X1). |
| connected | Yes | Whether a live transport is currently attached. |
| transport | No | Active transport name, if connected. |
| connected_at | No | UTC ISO-8601 connect timestamp. |
| active_document | No | Identity of the live document at connect time. |
| available_transports | No | Transports reported available on this host right now. |
TDQS
A4.6/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint=false, but the description adds significant behavioral details: modal socket bridge (GUI freezes), no_freeze mode via DBus, which operations are available in each mode, and clean failure when no transport is available. This far exceeds what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and informative but slightly lengthy. It uses well-placed line breaks and headings, but some sentences could be tightened. Every sentence adds value, but overall conciseness could be improved.
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?
Given the tool's complexity (starting a live session with transport selection), the description covers purpose, usage, parameters, behavior, return shape (LiveSession), and risk class. It does not explain the output schema in detail, but that is acceptable since an output schema exists.
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 0%, so description fully compensates. It explains the 'prefer' parameter with two options: 'read' (default, modal, full surface) and 'no_freeze' (limited but non-blocking). It details the trade-offs and available operations for each, providing clear semantics.
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?
The description clearly states 'Connect to a running Inkscape over the best-ranked available transport (enables live).' It specifies the action (connect) and the resource (running Inkscape), and distinguishes from sibling tools like live_disconnect and check_live_support.
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?
Explicitly provides usage context: 'When to use: starting a live session before any other live_* tool. To probe first use check_live_support; to tear down use live_disconnect.' This clearly guides when to use this tool and what alternatives exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
live_diff_viewLive: diff viewARead-only
Produce a FOCUSED, annotated before/after visual diff of a live operation.
When to use: visualizing what one live mutation changed. To produce a mutation to diff use
live_apply_to_selection / live_insert_svg / live_set_selected_text (or
live_session_step, which calls this internally).
Key params: operation_id names the Live Operation Record. The tool REUSES the before/after
frames the mutation already captured (run_live_mutation persists preview_before /
preview_after), pixel-diffs them to a CHANGED-REGION bbox, and emits ONE annotated overlay
highlighting it plus the current selection outline (best-effort when a session is connected).
Frames are resolved VIA the operation_id (never a raw client path) and sandbox-validated under
the live artifacts dir before any bytes are read. Identical-dimension frames required; a size
mismatch is a stable error. ARTIFACT-ONLY — no mutation, no Operation Record routing, no
approval, no network.
Return shape: LiveDiffResult — a workspace-relative overlay PNG path, the operation_id, the
pixel-space changed_bbox (null when the frames are identical), and highlighted_ids; the diff
path is linked back onto the record's diff_artifacts.
Example: live_diff_view(operation_id)
Risk class: low (artifact-only; reads + annotates two existing frames, no mutation, no record).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| operation_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| width | Yes | Frame width in pixels. |
| height | Yes | Frame height in pixels. |
| changed_bbox | No | Changed-region bbox in PIXELS (null when frames are identical). |
| operation_id | Yes | Live Operation Record id this diff was computed for. |
| artifact_path | Yes | Workspace-relative annotated overlay PNG path. |
| highlighted_ids | No | Selection ids whose outline was drawn on the overlay. |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true and destructiveHint=false. The description adds beyond annotations: 'ARTIFACT-ONLY — no mutation, no Operation Record routing, no approval, no network' and 'Risk class: low'. It explains frame resolution via operation_id, sandbox validation, and size mismatch error, providing full behavioral context.
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?
The description is well-structured with sections: main purpose, when to use, key params, and details. It is front-loaded and each sentence adds value. Slightly long but appropriate for the complexity; minimal redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (though not shown), the description covers return shape: LiveDiffResult with overlay path, operation_id, changed_bbox, and highlighted_ids. Also explains link to diff_artifacts. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter, operation_id, with 0% schema description coverage. The description adds meaning: 'Key params: `operation_id` names the Live Operation Record' and clarifies frames are resolved via operation_id, never a raw client path. This compensates for lack of schema description.
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?
The description clearly states the tool produces a focused, annotated before/after visual diff of a live operation. It specifies the resource (live operation diff) and action (visual diff), and distinguishes from siblings by noting when to use alternatives like live_apply_to_selection.
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?
Explicitly states 'When to use: visualizing what one live mutation changed.' It also provides alternative tools for producing mutations and mentions that live_session_step calls this internally, giving clear guidance on context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
live_disconnectLive: disconnectARead-onlyIdempotent
Disconnect the current live session (the X1 disable switch). Idempotent.
When to use: ending a live session (or as a hard kill switch). To start one use live_connect;
to check state use live_status.
Key params: none. Idempotent — safe to call with no session.
Return shape: LiveSession — the now-disconnected session state.
Example: live_disconnect()
Risk class: low (tears down the transport; no document mutation).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| notes | No | Clean human-readable status notes. |
| enabled | Yes | Whether live mode is permitted (master gate, X1). |
| connected | Yes | Whether a live transport is currently attached. |
| transport | No | Active transport name, if connected. |
| connected_at | No | UTC ISO-8601 connect timestamp. |
| active_document | No | Identity of the live document at connect time. |
| available_transports | No | Transports reported available on this host right now. |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context beyond annotations: idempotent, safe with no session, return shape, risk class. No contradiction with annotations (readOnlyHint, destructiveHint are consistent with 'no document mutation').
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?
Very concise, well-structured with sections (description, when to use, key params, return shape, example, risk class). Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a simple tool with no parameters and supportive annotations. Covers purpose, usage, behavior, example, and risk class. Output schema likely provides return details.
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?
No parameters; baseline 4 applies. Description correctly notes 'Key params: none,' but adds no extra meaning beyond 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?
Clearly states 'Disconnect the current live session (the X1 disable switch). Idempotent.' Identifies the specific resource and action, and distinguishes from siblings like live_connect and live_status.
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?
Explicitly provides when-to-use ('ending a live session (or as a hard kill switch)') and alternatives: 'To start one use live_connect; to check state use live_status.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
live_export_selectionLive: export selectionARead-only
Export just the current live selection to a PNG under the live artifacts dir.
When to use: a PNG of only the GUI selection. For the whole canvas use live_render_view; for
pixels plus structure use live_get_scene.
Key params: none. Read-only feedback (no mutation, no approval, no Operation Record), mirroring
live_render_view. Requires an established session.
Return shape: LiveExportResult — a workspace-relative PNG path under the live artifacts dir.
Example: live_export_selection()
Risk class: low (render to artifact dir).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| format | Yes | |
| object_ids | No | |
| size_bytes | Yes | |
| artifact_path | Yes |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, destructiveHint), description adds 'read-only feedback (no mutation, no approval, no Operation Record),' 'Risk class: low,' and return shape. No contradictions with 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?
Description is concise (5 sentences) with front-loaded action, structured sections (When to use, Key params, Return shape, Example, Risk class). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter tool, the description covers all necessary context: when to use, prerequisites, output shape, example, risk class, and differentiation from siblings. Complete.
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?
Input schema has zero parameters, and schema coverage is 100%. Description confirms 'Key params: none,' which meets the baseline of 4 for 0-parameter tools.
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?
The description states a specific verb+resource: 'Export just the current live selection to a PNG under the live artifacts dir.' It distinguishes from sibling tools `live_render_view` (whole canvas) and `live_get_scene` (pixels+structure), making purpose clear.
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?
Explicitly says 'When to use: a PNG of only the GUI selection' and provides alternatives for different needs. Also mentions prerequisite 'Requires an established session,' giving clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
live_get_active_documentLive: get active documentARead-only
Identify the document open in the connected live instance (read-only).
When to use: confirming WHICH document the live GUI has open. For its full scene use
live_get_scene; for the current selection use live_get_selection.
Key params: none. Requires an established session (live_connect).
Return shape: LiveDocumentRef — the active live document's identity.
Example: live_get_active_document()
Risk class: low (read-only over an established live session).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| name | No | Document title / base filename. |
| path | No | On-disk path as reported by Inkscape. |
| object_count | No | Object node count, if reported. |
TDQS
A4.7/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. Description adds context: requires established session, return shape (LiveDocumentRef), example, and risk classification. No contradictions.
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?
Five well-structured sentences covering purpose, usage, parameters, return, example, and risk. Every sentence adds value, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, when to use, prerequisites, return object, example, and risk class. With an output schema present, no further details needed.
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?
No parameters, schema coverage 100% (empty schema). Description notes 'Key params: none', which is sufficient. Baseline 4 for zero parameters.
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?
The description states the specific verb 'identify' and resource 'document' in a connected live instance, and explicitly distinguishes this tool from siblings like live_get_scene and live_get_selection.
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?
Explicit 'When to use' section states the exact use case: confirming which document is open. Also provides alternatives (live_get_scene, live_get_selection) and prerequisite (requires live_connect session).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
live_get_sceneLive: get sceneARead-only
Capture one live frame as a PNG PLUS a structured, machine-readable LiveScene.
When to use: the core perception step — the agent reasons over STRUCTURE, not pixels. For
pixels-only use live_render_view; for one loop iteration use live_session_step.
Key params: region/scale/fast work exactly as live_render_view (all four region parts at once,
user units, w/h > 0; optional scale > 0; fast=True for the downscaled loop preview, explicit
scale wins). Frame rendered through the transport, never an OS screenshot
(deterministic, cross-platform — ADR-006); served from the per-session cache keyed on
(doc_revision, viewport, scale). Scene pulled over the fixed get_scene command — no
code or raw Action path (ADR-003). Requires an established session. READ-ONLY (no Operation
Record, no approval).
Return shape: LiveSceneFrame — render (the PNG) plus scene: a LiveScene carrying the
active-document identity, selection (ids + bboxes), viewport (zoom/center/visible region), the
canvas size, and a visible-object summary.
Example: live_get_scene(fast=True)
Risk class: low (read-only perception; no document mutation, no Operation Record).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fast | No | ||
| scale | No | ||
| region_x | No | ||
| region_y | No | ||
| region_width | No | ||
| region_height | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| scene | Yes | Structured scene paired with this frame (read-only). |
| render | Yes | Rendered frame (workspace-relative PNG path). |
TDQS
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description provides extensive behavioral details beyond annotations: deterministic rendering via transport (not OS screenshot), caching mechanism, data source (get_scene command), requirement for established session, and read-only nature. The risk class is also stated. No contradiction with annotations; readOnlyHint is consistent.
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?
The description is well-structured with clear sections: purpose, when to use, parameter details, behavioral notes, return shape, example, and risk class. While thorough, it is not excessively verbose; every sentence contributes meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, output schema exists, annotations present), the description covers all critical aspects: purpose, parameters, behavior, return shape (LiveSceneFrame with render and scene), an example, and risk classification. The presence of an output schema means detailed return fields are documented elsewhere, so the summary is sufficient.
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?
With 0% schema coverage, the description adds significant value by explaining how region/scale/fast work, including constraints (w/h > 0, scale > 0) and behavior (fast=True for preview, explicit scale wins). This compensates well for the schema's lack of descriptions.
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?
The description clearly states the tool captures a live frame as both a PNG and a structured LiveScene. It distinguishes from sibling tools live_render_view (pixels only) and live_session_step (one loop iteration), making the purpose unmistakable.
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?
Explicitly states when to use ('core perception step') and when not to use, including direct mentions of alternative tools (live_render_view, live_session_step). This provides clear guidance for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
live_get_selectionLive: get selectionARead-only
Read the current selection in the live instance as object ids (read-only).
When to use: getting the ids the user selected in the GUI. For their semantic detail use
live_inspect_selection; for the whole scene use live_get_scene. Not available over DBus
(no_freeze) — stays on the modal socket transport.
Key params: none. Requires an established session (live_connect).
Return shape: LiveSelection — count plus the selected object ids.
Example: live_get_selection()
Risk class: low (read-only).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| count | No | Number of selected objects. |
| object_ids | No | Selected object ids. |
TDQS
A4.7/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and destructiveHint=false. Description adds value by disclosing 'Not available over DBus (`no_freeze`) — stays on the modal socket transport' and 'Requires an established session (`live_connect`)', which are beyond 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?
Well-structured with distinct sections: purpose, when-to-use, limitations, prerequisites, return shape, example, risk. Every sentence adds unique value; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage guidelines, transport constraint, session requirement, return shape (mentioning `LiveSelection` with count and ids), and an example. Output schema exists, so return details are complete. No gaps for a simple zero-parameter read-only tool.
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?
No parameters in schema; description mentions 'Key params: none' and gives an example call. Baseline for zero-parameter tools is 4, and description adds no further semantics but is adequate.
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 'Read the current selection in the live instance as object ids (read-only)' with a specific verb and resource. Clearly distinguishes from siblings by referencing `live_inspect_selection` for semantic detail and `live_get_scene` for the whole scene.
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?
Explicitly states when to use: 'getting the ids the user selected in the GUI.' Provides clear alternatives ('For their semantic detail use `live_inspect_selection`; for the whole scene use `live_get_scene`') and notes transport limitation and session requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
live_insert_svgLive: insert SVGA
Insert an SVG fragment into the running document.
When to use: grafting composed markup into the live document. To style the selection use
live_apply_to_selection; for the headless equivalent use insert_svg_fragment.
Key params: svg_fragment is parsed through the normative safe parser (no entities, no external
DTD, no network) and size-bounded before it crosses the transport — only well-formed, safe
markup is inserted; no code path (ADR-003). Inserting into a running user session is HIGH risk:
REQUIRES an explicit approval_token (refused without one).
Return shape: LiveEditResult — a Live Operation Record with before/after canvas renders,
syncable to a snapshot.
Example: live_insert_svg("<rect .../>", approval_token="ok")
Risk class: high (approval-gated).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| svg_fragment | Yes | ||
| approval_token | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| count | No | |
| summary | No | |
| transport | No | |
| affected_ids | No | |
| operation_id | Yes | |
| preview_after | No | |
| undo_friendly | No | |
| preview_before | No |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses behavior beyond annotations: svg_fragment is safely parsed (no entities, no external DTD, no network) and size-bounded. Clearly states 'high risk' and requirement for approval_token. No contradiction with annotations (readOnlyHint=false consistent with write operation).
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?
Concise and well-structured: brief action statement, usage guidance, key params, risk info, return shape, and example. Every sentence adds value, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (live insertion, high risk), the description covers purpose, usage, parameters, risk, return output (LiveEditResult with before/after renders), and an example. The output schema is referenced, providing complete context for invocation.
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 0%, so description compensates partially. It mentions key params (svg_fragment and approval_token) and adds safety context for svg_fragment. However, it does not fully describe each parameter's type or constraints beyond what schema provides. With only 2 params, the context is adequate but could be more precise.
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?
The description clearly states 'Insert an SVG fragment into the running document.' It uses a specific verb and resource, and distinguishes from siblings by noting alternatives for styling (live_apply_to_selection) and headless equivalent (insert_svg_fragment).
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?
Explicitly says 'When to use: grafting composed markup into the live document.' Provides alternative tools for different use cases. Also states prerequisites: 'REQUIRES an explicit approval_token' and notes high risk, guiding appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
live_inspect_selectionLive: inspect selectionARead-only
Inspect the selected objects in the live instance (semantic, by id; read-only).
When to use: getting structured detail (not just ids) of the GUI selection. For ids only use
live_get_selection; for the whole scene use live_get_scene. Not available over DBus
(no_freeze) — stays on the modal socket transport.
Key params: none. Requires an established session (live_connect).
Return shape: LiveSelectionInspection — count plus per-object inspection (the headless
object-inspection shape).
Example: live_inspect_selection()
Risk class: low (read-only).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| count | No | |
| objects | No |
TDQS
A4.7/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds context beyond annotations: read-only, transport restriction (no DBus), session prerequisite, and return shape. Annotations already cover safety, but the description enriches understanding.
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?
Description is efficient and well-structured with clear sections (When to use, Key params, Return shape, Example, Risk class). Every sentence adds value, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool with an output schema, the description covers prerequisites, constraints, return shape, and example. It is fully complete for the tool's complexity.
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?
No parameters exist, and schema coverage is 100%. Description correctly states 'Key params: none.' No further detail needed; baseline is met and slightly exceeded by explicitly noting lack of params.
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?
Description clearly states verb 'Inspect', resource 'selected objects', and context 'live instance, read-only'. It distinguishes from siblings by specifying the alternative tools for ids and whole scene.
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?
Explicitly states when to use (structured detail of GUI selection) and when not (not over DBus). Names alternatives `live_get_selection` and `live_get_scene`. Also mentions requirement of established session.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
live_install_helperLive: install helperA
Install the shipped extension-socket helper into the Inkscape user extensions dir.
When to use: one-time setup so a running Inkscape can expose the socket bridge. After install,
probe with check_live_support then live_connect.
Key params: none. Copies the fixed-purpose helper (inkscape_mcp_live.py + .inx). Requires
the master gate (live is opt-in). Touches no workspace document.
Return shape: HelperInstallResult — installed_files and extensions_dir (presented
~-relative, never an absolute host path/L5).
Example: live_install_helper()
Risk class: restricted (writes a server-bundled file under the Inkscape extensions dir).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| extensions_dir | Yes | Install dir, `~`-relative (never an absolute host path). |
| installed_files | Yes |
TDQS
A4.8/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the tool writes files (copies helper), requires opt-in, and does not touch the workspace document. Annotations already provide non-read-only status, but description adds useful context. No contradiction.
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?
Well-structured with clear sections: action, usage, params, return shape, example, risk class. Every sentence is informative and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and presence of output schema, the description covers prerequisites, return shape, file operations, and risk class. No gaps for an agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, schema coverage is 100%. The description adds value by naming the specific files copied (inkscape_mcp_live.py + .inx) and linking to output 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?
The description clearly states the tool installs the extension-socket helper into Inkscape's user extensions directory. It is distinct from sibling tools like live_connect or check_live_support.
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?
Explicitly indicates 'When to use: one-time setup' and suggests subsequent steps: 'probe with check_live_support then live_connect'. Also mentions requirement for the master gate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
live_render_viewLive: render viewARead-only
Rasterize the live canvas to a PNG in the live artifacts dir (visual feedback).
When to use: a pixels-only view of the live canvas. For pixels PLUS structured scene use
live_get_scene; for just the selection use live_export_selection.
Key params: with no region the whole canvas renders. Supply ALL four of
region_x/region_y/region_width/region_height (user units; w/h > 0) for a targeted bbox,
and optional scale (>0) to up/downscale. fast=True gives a cheap downscaled loop-preview; an
explicit scale always wins. Every numeric is finite-checked and bounded server-side before it
crosses the transport; the frame comes from the transport renderer, never an OS screenshot
(deterministic, cross-platform — ADR-006). Served from a per-session cache keyed on
(doc_revision, viewport, scale) so a stale frame is never returned after a change.
Return shape: LiveRenderResult — a workspace-relative PNG path plus render metadata.
Example: live_render_view(fast=True)
Risk class: low (render to artifact dir; view-only, no Operation Record).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fast | No | ||
| scale | No | ||
| region_x | No | ||
| region_y | No | ||
| region_width | No | ||
| region_height | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| scale | No | |
| format | Yes | |
| region | No | |
| size_bytes | Yes | |
| artifact_path | Yes |
TDQS
A4.8/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and destructiveHint. Description adds details on deterministic rendering, caching, and risk class, enhancing beyond 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?
Concise yet comprehensive: covers usage, parameters, example, return shape, and risk. Well-structured with clear sections.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Fully covers all aspects: parameters, output schema, caching, rendering source, and risk. No missing information given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but description explains all parameters: region constraints, scale, fast, and ordering rules. Provides context on validation and caching behavior.
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?
Clearly states 'Rasterize the live canvas to a PNG' with a specific verb and resource. Distinguishes from siblings like 'live_get_scene' and 'live_export_selection'.
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?
Explicitly states when to use (pixels-only view) and when not to (pixels+scene or selection), with alternative tool names and an example.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
live_session_stepLive: session stepADestructive
Run ONE perceive→decide→act→observe iteration of the live-view loop.
When to use: the flagship loop step — call it repeatedly to drive a live edit loop (use
live_wait_for_change between steps to react to the user's edits). It COMPOSES the existing
live tools (ADR-006); for a single standalone edit call live_apply_to_selection /
live_insert_svg / live_set_selected_text directly. Each call is one bounded iteration — no
server-side autonomous run.
Key params: action is the AGENT's decision (this tool embeds no LLM), one of the FIXED set
apply | insert_svg | set_text (no raw-Action/code path — ADR-002/003; an out-of-enum
action is rejected). OMIT action for a PERCEIVE-ONLY step (mutates nothing, no Operation
Record). When acting: apply takes fill/stroke/stroke_width/opacity and/or
dx/dy/scale/rotate; insert_svg takes a safe-parsed svg_fragment; set_text takes a
control-char-checked text. The act runs through run_live_mutation (the SAME path as the
standalone tools); mutating a running session is HIGH risk and REQUIRES an explicit
approval_token. Requires a session.
Return shape: LiveSessionStepResult — always the PERCEIVE scene + frame; after an act also the
operation_id, a focused live_diff_view artifact, and the after scene/frame.
Example: live_session_step(action="apply", approval_token="ok", fill="#3366cc")
Risk class: high when it acts (routes through run_live_mutation — HIGH + approval); low when
perceive-only (read-only; no mutation, no Operation Record).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dx | No | ||
| dy | No | ||
| fill | No | ||
| text | No | ||
| scale | No | ||
| action | No | ||
| rotate | No | ||
| stroke | No | ||
| opacity | No | ||
| stroke_width | No | ||
| svg_fragment | No | ||
| approval_token | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| diff | No | Focused before/after diff linked to the record (act steps only). |
| edit | No | The mutation outcome (null when perceive-only). |
| acted | Yes | Whether a semantic act was performed this step. |
| action | No | The semantic act performed, or null on a perceive-only step. |
| after_frame | No | Canvas frame captured after the act (null when perceive-only). |
| after_scene | No | Structured scene captured AFTER the act (null when perceive-only). |
| before_frame | Yes | Canvas frame captured before acting. |
| before_scene | Yes | Structured scene captured BEFORE deciding/acting. |
| operation_id | No | Live Operation Record id of the act (null when perceive-only). |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses risk: 'high when it acts (routes through `run_live_mutation` — HIGH + approval); low when perceive-only (read-only).' It also explains the approval token requirement. Annotations already indicate destructiveHint=true, but the description adds valuable context beyond 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?
Well-structured with sections: purpose, usage, key params, return shape, example, risk class. Front-loaded with main purpose. Every sentence adds value, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary aspects: purpose, usage, parameters, return type (references output schema), example, risk, and design decisions (ADR references). Complete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description thoroughly explains key parameters: `action` enum, parameter dependencies per action, and the role of `approval_token`. It adds significant meaning beyond the bare 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?
The description clearly states the tool's purpose: 'Run ONE perceive→decide→act→observe iteration of the live-view loop.' It distinguishes from sibling tools by referencing standalone tools like `live_apply_to_selection`, `live_insert_svg`, and `live_set_selected_text`, and explains when to use each.
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?
Explicit 'When to use' section explains the tool is for repeated loop steps, with `live_wait_for_change` between steps. It also notes when to use standalone tools instead. Clear and actionable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
live_set_selected_textLive: set selected textADestructive
Replace the selected text object's content in the running document.
When to use: changing the selected text object's words live. To restyle the selection use
live_apply_to_selection; for the headless equivalent use replace_text.
Key params: text is length-bounded and control-character-rejected (the same guard as the
headless replace_text); it is stored as a text node, so no markup injection is possible.
Editing a running user session is HIGH risk: REQUIRES an explicit approval_token (refused
without one).
Return shape: LiveEditResult — a Live Operation Record with before/after canvas renders,
syncable to a snapshot.
Example: live_set_selected_text("Hello", approval_token="ok")
Risk class: high (approval-gated).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | ||
| approval_token | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| count | No | |
| summary | No | |
| transport | No | |
| affected_ids | No | |
| operation_id | Yes | |
| preview_after | No | |
| undo_friendly | No | |
| preview_before | No |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context beyond annotations: length-bounded text, control-character rejection, no markup injection, high risk requiring approval token, and return shape as LiveEditResult with canvas renders. No contradiction with 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?
Concise, well-structured with sections for purpose, usage, key params, return shape, example, and risk class. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all aspects: purpose, usage, parameters, risk, return (with output schema mentioned), and example. Complete for a mutation tool with high risk.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema description coverage is 0%, the description fully compensates by explaining `text` constraints (length-bounded, no markup injection) and the `approval_token` requirement.
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?
Clearly states 'Replace the selected text object's content in the running document,' using a specific verb and resource. Differentiates from siblings like `live_apply_to_selection` and `replace_text`.
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?
Explicitly states when to use ('changing the selected text object's words live'), provides alternatives for restyling and headless case, and notes high-risk nature requiring approval token.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
live_set_viewportLive: set viewportARead-onlyIdempotent
Control the live canvas viewport: zoom / pan / fit-to-selection / fit-to-page.
When to use: framing the canvas before a render/capture. To then render use live_render_view;
to edit (not just view) use live_apply_to_selection.
Key params: mode is one of the fixed verbs zoom | pan | fit_selection | fit_page (no
raw Action or code path — ADR-003). zoom takes a positive zoom and optional
center_x/center_y to recentre; pan takes both dx and dy (a delta in user units);
fit_selection/fit_page take no numerics. Every numeric is finite-checked and bounded
server-side before it crosses the transport (sec.12). Requires a session. VIEW-ONLY (no
Operation Record, no approval).
Return shape: LiveViewportResult — the applied viewport state.
Example: live_set_viewport("zoom", zoom=2.0)
Risk class: low (view-only; no document mutation, no Operation Record).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dx | No | ||
| dy | No | ||
| mode | Yes | ||
| zoom | No | ||
| center_x | No | ||
| center_y | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| mode | Yes | Viewport mode applied (zoom/pan/fit_selection/fit_page). |
| detail | No | Short human-readable summary. |
| applied | No | Whether the backend applied the viewport op. |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Reinforces annotations by declaring VIEW-ONLY, no Operation Record, no approval, and mentions server-side bounds checking. No contradiction with 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?
Well-structured with clear sections, no filler, each sentence adds value. Efficiently covers purpose, usage, params, example, risk.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 0% schema coverage, description compensates fully. Includes return shape mention (LiveViewportResult). Usage and safety covered. Complete for this view-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, description fully explains each mode's parameter requirements (zoom needs zoom/center, pan needs dx/dy, fit modes take no numerics), adding critical meaning beyond 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?
Description clearly states verb 'control' and resource 'live canvas viewport', and explicitly distinguishes from siblings like live_render_view and live_apply_to_selection.
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?
Provides explicit 'When to use' guidance and names alternatives for rendering and editing, making it clear when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
live_statusLive: statusARead-only
Report live-session state: enabled, connected, active transport, available transports.
When to use: checking whether a session is live before issuing live tools. For per-host
transport detail use check_live_support.
Key params: none. Never raises — reports "not connected" / "none available" cleanly.
Return shape: LiveSession — enabled, connected, active transport, available transports.
Example: live_status()
Risk class: low (read-only).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| notes | No | Clean human-readable status notes. |
| enabled | Yes | Whether live mode is permitted (master gate, X1). |
| connected | Yes | Whether a live transport is currently attached. |
| transport | No | Active transport name, if connected. |
| connected_at | No | UTC ISO-8601 connect timestamp. |
| active_document | No | Identity of the live document at connect time. |
| available_transports | No | Transports reported available on this host right now. |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true and destructiveHint=false. Description adds that it never raises exceptions and cleanly returns 'not connected' or 'none available', which is beyond annotation info.
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?
Extremely efficient: first sentence states purpose, then usage guidelines, parameter note, return shape, example, and risk class. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema exists, the description adequately covers the return shape and usage context. It is complete for a simple read-only status tool.
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?
No parameters, schema coverage 100%. Description correctly notes 'Key params: none'. Baseline 4 is appropriate as no further parameter details needed.
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?
Description clearly states the tool reports live-session state with specific fields. It distinguishes from sibling 'check_live_support' by specifying that this tool covers overall state, not per-host details.
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?
Explicitly states 'when to use: checking whether a session is live before issuing live tools' and provides a direct alternative ('For per-host transport detail use check_live_support').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
live_sync_to_workspaceLive: sync to workspaceA
Save the live document's current state into the workspace as a NEW tracked document.
When to use: capturing live work into the headless workspace so the typed tools can act on it.
For pixels-only feedback use live_render_view; to save a HEADLESS doc to disk use
save_document_as.
Key params: dest_path is the new workspace file; RELATIVE anchors to the first workspace root
(NOT the server CWD) and a not-yet-existing SUBFOLDER is created in-sandbox first (matching
save_document_as; a ..-escaping / out-of-sandbox dest creates nothing and is rejected with
path rejected: outside workspace). Reads the live SVG and writes it through the policy layer
(sandbox + symlink guard), registers it (working copy), and records an Operation Record +
snapshot (ADR-004). An existing destination is REFUSED — sync never overwrites, so a live fault
cannot damage a workspace file. Requires an established session.
Return shape: LiveSyncResult — the new doc_id, operation_id, and snapshot links.
Example: live_sync_to_workspace("from-live.svg")
Risk class: medium (writes a new workspace document, reversible + recorded).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dest_path | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| saved_path | Yes | |
| size_bytes | Yes | |
| snapshot_id | Yes | |
| operation_id | Yes |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant behavioral context beyond annotations: path validation, no overwrite, session requirement, subfolder creation, recording of operation and snapshot, risk class.
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?
Well-structured with purpose first, usage, params, behavior, return shape, example, risk. Slightly long but all information is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all aspects: prerequisites, constraints, behavior, return shape, risk class. Output schema mentioned so no need to detail return fields further.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Highly detailed description of dest_path parameter including relative path behavior, sandbox constraints, and rejection conditions, compensating for zero schema description coverage.
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?
Clear verb 'save ... as a NEW tracked document', distinct from sibling tools live_render_view and save_document_as.
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?
Explicitly states when to use and provides alternatives with specific differences.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
live_wait_for_changeLive: wait for changeARead-only
Block until the live state changes, or the bounded timeout elapses (read-only).
When to use: between live_session_step iterations so the loop reacts to the user's own GUI
edits instead of busy-rendering. To then re-perceive use live_get_scene.
Key params: timeout_s is clamped to at most 60s and poll_interval_s is floored, so the wait
never spins tightly nor blocks forever (it sleeps between cheap polls). Each poll pulls a CHEAP
state token (small revision marker + selection ids + coarse viewport — never the full doc or a
PNG; protocol v5), hashed + diffed against the last token. Requires a session; no
code/raw-Action path (ADR-003). NOTE: the socket helper runs on a snapshot, so within one call
it cannot observe later GUI edits; the token mechanism is transport-agnostic and detects user
edits on any transport that recomputes per poll.
Return shape: LiveChange — changed, timed_out, and the delta flags selection_changed /
document_changed / viewport_changed (more than one may fire).
Example: live_wait_for_change(timeout_s=10)
Risk class: low (read-only polling; no document mutation, no Operation Record).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| timeout_s | No | ||
| poll_interval_s | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| token | No | The newest observed state token. |
| changed | No | Whether any tracked component changed. |
| timed_out | No | True when a bounded wait elapsed with no change. |
| selection_ids | No | Current selection object ids at observation time. |
| document_changed | No | Document revision marker changed. |
| viewport_changed | No | Viewport (zoom/center) changed. |
| selection_changed | No | Selection ids changed. |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses internal polling mechanism, parameter bounds (timeout_s clamped, poll_interval_s floored), cheap token nature, transport-agnostic property, socket limitation, and return shape details. Goes far beyond 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?
Well-structured: starts with purpose, then usage, then parameter behavior, then return shape, then example. Every sentence is informative and efficient; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all relevant aspects: purpose, when-to-use, parameter constraints, internal behavior, return shape, example, risk class, and session requirement. Complete for a moderate-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds semantic meaning to both parameters: explains timeout_s is bounded to 60s, poll_interval_s is floored, and describes impact on polling behavior. With 0% schema coverage, this fully compensates.
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?
Clearly states the tool blocks until live state changes or timeout, read-only. Distinguishes itself by context between live_session_step and live_get_scene, and explicitly notes it is for reacting to user GUI edits.
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?
Explicitly states when to use (between live_session_step iterations) and what to use after (live_get_scene). Also notes session requirement and exclusion of code/raw-Action path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
move_objectMove objectA
Translate an object/group by (dx, dy) in its parent coordinate space.
When to use: repositioning one object; get its id from find_objects. To resize use
scale_object, to spin use rotate_object, to lay out copies use tile.
Key params: dx/dy are a delta in the parent coordinate space; a translate(dx,dy) is
prepended to the target's transform (child geometry untouched).
Return shape: EditResult — operation_id, snapshot_id, changed (real before/after content
diff), before/after preview; the edit lands on the working copy only (reversible).
Example: move_object(doc_id, "logo", 10, 0)
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dx | Yes | ||
| dy | Yes | ||
| doc_id | Yes | ||
| object_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, destructiveHint=false), the description adds context: 'the edit lands on the working copy only (reversible),' 'a translate(dx,dy) is prepended to the target's transform (child geometry untouched),' and a risk warning. It also advises to render and look before trusting.
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?
The description is well-structured with a clear purpose, usage guidelines, key parameters, return shape, example, and safety note. Every sentence is informative and no redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema and annotations, the description thoroughly covers the tool's behavior: return shape (EditResult details), reversibility, and the need for preview. It is complete for a move operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description explains the key parameters: 'dx/dy are a delta in the parent coordinate space,' and includes an example call. It adds meaning to all four required parameters beyond the schema types.
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?
The description clearly states the tool's action: 'Translate an object/group by (dx, dy) in its parent coordinate space.' It uses a specific verb ('translate') and resource ('object/group'), and distinguishes itself from sibling tools like scale_object, rotate_object, and tile.
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?
The description provides explicit guidance on when to use: 'repositioning one object; get its id from find_objects.' It also lists alternatives: 'To resize use scale_object, to spin use rotate_object, to lay out copies use tile.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
normalize_viewboxNormalize viewBoxA
Normalize or repair the document's root viewBox.
When to use: tidying/repairing a missing or malformed root viewBox. To frame the page to the
art use fit_to_content, to set the page size use resize_canvas.
Key params: none beyond doc_id. A valid 4-number viewBox is left unchanged (idempotent →
changed=False); an absent one is synthesized from numeric width/height; a malformed one is
repaired from width/height when possible.
Return shape: EditResult — operation_id, snapshot_id, changed (real before/after content
diff), before/after preview; the edit lands on the working copy only (reversible).
Example: normalize_viewbox(doc_id)
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A4.7/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide minimal info (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds rich behavior: idempotency for valid viewBox, synthesis/recovery for absent/malformed, reversibility on working copy, return shape with diff, and risk warning. No contradiction with 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?
Description is well-structured with clear sections: purpose, usage, key params, return shape, example, risk warning. Every sentence adds value and the most important information (what it does) is front-loaded. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, output schema exists), the description covers all needed aspects: purpose, when to use, behavior, return, risk, and references to siblings. It is fully complete for an agent to select and invoke correctly.
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 has 1 param (doc_id) with 0% description coverage. Description mentions 'Key params: none beyond doc_id', acknowledging the parameter but adding no further details about its type or usage. For a single simple parameter, this is adequate but minimal added value.
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?
The description clearly states the tool normalizes/repairs the root viewBox. It specifies the action and resource, and distinguishes from siblings fit_to_content and resize_canvas by naming them as alternatives for different purposes.
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?
Explicitly states 'When to use: tidying/repairing a missing or malformed root viewBox.' and provides when-not-to-use guidance with alternative tool names, offering clear context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
open_documentOpen documentARead-only
Open an SVG into a tracked workspace document and return its id + summary.
When to use: the entry point for working on an EXISTING file — you need the doc_id before any
other tool. To start from nothing use create_document; to adopt agent-composed SVG use
set_document_svg / insert_svg_fragment; to resync external edits use reload_document.
Key params: path may be workspace-RELATIVE (anchored to the first workspace root, NOT the
server CWD — matching save_document_as / live_sync_to_workspace) or absolute; either is
sandbox-validated and a ../-escape, an absolute path outside the workspace, or a symlink whose
target leaves the sandbox is rejected with path rejected: outside workspace.
WORKING-COPY MODEL: opening copies your source SVG byte-for-byte into a per-document workspace
as an immutable original.svg and seeds a single live WORKING COPY. The returned doc_id
addresses that copy; EVERY subsequent tool operates on it, and your ORIGINAL is NEVER mutated.
Edits are reversible (pre-edit snapshot + Operation Record); restore_snapshot rolls back.
Return shape: OpenDocumentResult — doc_id (opaque, pass to every other tool) and summary
(size, viewBox, units, counts).
Example: open_document("logo.svg")
Risk class: low (opens via working copy; original never mutated).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| summary | Yes | Top-level document summary (viewBox / page / size / counts). |
TDQS
A4.8/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes working-copy model, that original is never mutated, edits are reversible, and risk class. Annotations already indicate readOnly and non-destructive, but description adds valuable behavioral context beyond 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?
Well-structured with clear sections (When to use, Key params, WORKING-COPY MODEL, Return shape, Example, Risk class). Every sentence adds value, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter and an output schema, the description covers all necessary context: working copy model, return shape details, example, and risk assessment. Complete for an entry-point tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has no description for the path parameter, but the description provides extensive semantics: relative vs absolute paths, sandbox validation, rejection conditions, and alignment with sibling tools.
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?
Clearly states the tool opens an SVG into a tracked workspace document, returns id and summary. Distinguishes from siblings like create_document, set_document_svg, reload_document.
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?
Explicitly states when to use (entry point for existing file) and when not to (alternatives provided). Lists sibling tools for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
optimize_setOptimize setA
Web-optimize a SET of documents in one call: per-doc results + aggregate + verdict.
When to use: losslessly shrinking a whole multi-document system (e.g. a 12-icon set) in one
call, reading the set's total byte saving and a cross-doc consistency check. For a SINGLE
document use svg_web_optimize; to inspect the opportunities use quality_report_set.
Key params: doc_ids is a non-empty, duplicate-free set; precision / keep_ids are the SAME
arguments svg_web_optimize takes (applied to EVERY document). Each document is optimized
through the reversible pipeline, so a CHANGED document gets ONE pre-mutation snapshot +
Operation Record (ADR-004) and a no-op writes none. The whole set is rejected if ANY document
fails (no partial apply on the remainder is suppressed — earlier successful docs stay optimized
and reversible via their snapshots).
Return shape: OptimizeSetResult — per_doc (each {doc_id, result} with the standard
WebOptimizeResult), total_bytes_before / total_bytes_after / total_bytes_saved
aggregated across the set, changed_count, and consistency — the structured cross-doc verdict
computed on the PRE-optimize state (per property: agree/disagree + the differing values + which
doc_ids differ).
Example: optimize_set(["d1","d2","d3"], precision=2)
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium (each document optimized reversibly; one snapshot per changed doc).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_ids | Yes | ||
| keep_ids | No | ||
| precision | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| per_doc | Yes | |
| consistency | Yes | Structured cross-document consistency audit over a set. One :class:`ConsistencyProperty` per audited property (``viewBox``, ``stroke_width``, ``id_naming``). ``consistent`` is True iff EVERY audited property agrees across the set. Not prose: an agent reads ``properties`` to see precisely which property disagrees and which ``doc_ids`` carry which value. |
| changed_count | Yes | |
| total_bytes_after | Yes | |
| total_bytes_saved | Yes | |
| total_bytes_before | Yes |
TDQS
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses reversible pipeline, no-op behavior, whole-set rejection on failure, snapshot creation, and risk class 'medium', adding significant context beyond minimal 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?
Well-structured with sections, but somewhat lengthy. Every sentence contributes value; minor redundancy could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given tool complexity, output schema existence, and no sibling tool covers set optimization, the description provides all necessary input, behavior, output, and risk details for correct invocation.
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?
With 0% schema coverage, description compensates by explaining doc_ids constraints, and referencing precision/keep_ids from sibling tool. However, keep_ids purpose is not fully detailed, relying on agent's knowledge of svg_web_optimize.
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?
The description clearly states the verb 'Web-optimize' and the resource 'SET of documents', and contrasts with single-document and inspection tools, making it distinguishable from siblings.
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?
Explicitly states when to use (losslessly shrinking a multi-document system), and when to use alternatives (svg_web_optimize for single docs, quality_report_set for inspection). Also recommends post-use preview.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
place_documentPlace documentA
Place an existing document or object INTO another document at (x, y) with scale.
When to use: re-composing existing geometry cross-document without re-authoring or extracting
SVG by hand — the single-asset companion of compose_grid. To lay out MANY assets in a grid use
compose_grid; to graft agent-COMPOSED markup use insert_svg_fragment; to instance a
same-document object use create_use.
Key params: supply EXACTLY ONE source — source_doc_id (place that whole document's root) OR
object_id together with source_doc_id (place that one object from the source document). The
source subtree is deep-copied (every id re-minted, intra-clone refs rewritten, no id clashes —
the source is NEVER mutated) and wrapped in a <g> translated to (x, y) and uniformly scaled
by scale (> 0) about that origin. The whole place lands under ONE snapshot + Operation Record.
Return shape: PlaceResult — an EditResult (reversible via restore_snapshot) plus
target_doc_id, placed_id (the new wrapper-group id), and source (a short label).
Example: place_document("sheet", 100, 0, source_doc_id="logo") drops the whole logo document
into sheet at (100, 0); place_document("sheet", 0, 0, source_doc_id="kit", object_id="star")
places just the star object from kit.
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium (write-new on the target working copy, reversible; sources never mutated).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | ||
| y | Yes | ||
| scale | No | ||
| object_id | No | ||
| source_doc_id | No | ||
| target_doc_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| source | Yes | |
| changed | Yes | |
| summary | No | |
| placed_id | Yes | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| target_doc_id | Yes | |
| preview_before | No |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses deep-copy behavior, id re-minting, non-mutation of source, translation/scaling, snapshot/operation record creation, and risk class 'medium'. Annotations only provide basic hints; description adds critical behavioral context.
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?
Well-structured with clear sections (purpose, when-to-use, key params, return shape, example, risk). Slightly verbose but every sentence adds value. Front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters, 0% schema coverage, and existence of output schema, the description covers all essential aspects: operation details, parameter constraints, return shape, example, risk, and verification guidance. Complete enough for an agent to use confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description fully compensates. Explains the required mutual exclusivity of `source_doc_id` and `object_id`, the effect of `scale` and `(x, y)`, and provides annotated examples. Adds meaning far beyond the bare 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?
Clearly states 'Place an existing document or object INTO another document at (x, y) with scale.' Distinguishes from siblings by naming `compose_grid`, `insert_svg_fragment`, `create_use`, and explaining when each is appropriate.
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?
Explicitly states when to use: 're-composing existing geometry cross-document without re-authoring or extracting SVG by hand.' Provides clear alternatives for other use cases, such as `compose_grid` for many assets and `insert_svg_fragment` for grafted markup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
prune_snapshotsPrune snapshotsARead-only
Apply the snapshot + live-frame retention policy, pruning superseded server state.
When to use: reclaiming disk from old snapshots/frames. To roll back instead use
restore_snapshot; to list checkpoints use list_snapshots. No mutating tool triggers this
implicitly — it is an explicit maintenance sweep.
Key params: none beyond doc_id. Retains the last N snapshots and all within the keep-days
window (configurable), bounded by absolute hard caps on count and bytes; deletes the rest plus
orphaned Operation Records. In the SAME pass it prunes the doc root's loop/live render frames
by age + byte budget, never deleting a frame still referenced by a Live Operation
Record. The current working copy and original are never touched, so the restore chain stays
intact.
Return shape: PruneResult — pruned_snapshot_ids, pruned_operation_ids, and live_frames
(the frame pruning stats).
Example: prune_snapshots(doc_id)
Risk class: low (deletes only disposable, superseded server state under a deterministic policy; authoritative current state is never affected).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| freed_bytes | Yes | |
| live_frames | No | |
| retained_count | Yes | |
| pruned_snapshot_ids | No | |
| pruned_operation_ids | No |
TDQS
A3.9/5.0
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description claims destructive behavior (deletes snapshots/frames), but the annotation has readOnlyHint: true, which contradicts. Per rules, score 1 for contradiction. The description is otherwise detailed but the contradiction invalidates trust.
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?
Well-structured with clear sections: purpose, when to use, key params, return shape, example, risk class. Every sentence adds value, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers retention policy details, what is kept, what is deleted, output shape (PruneResult), and risk class. Output schema exists so explaining return values is unnecessary. Complete for agent decision-making.
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?
Only one parameter doc_id with no schema description. Description mentions it's the only key param and gives an example, but does not elaborate on its format or constraints. Schema coverage 0% means description should compensate more, but it's adequate for a simple param.
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?
The description clearly states it applies a retention policy to prune superseded snapshots and live-frames, using specific verbs like 'pruning' and 'reclaiming disk'. It distinguishes from siblings like `restore_snapshot` and `list_snapshots`.
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?
Explicitly says when to use (reclaim disk), when not (roll back use restore_snapshot, list use list_snapshots), and notes it's an explicit maintenance sweep, not triggered implicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
quality_reportQuality reportARead-only
Build a machine-readable quality report for a document: validation findings plus metrics.
When to use: assessing a document's health and what optimizing would save. For pass/fail
correctness only use validate_document; to actually strip the opportunities use
svg_web_optimize.
Key params: none beyond doc_id.
Return shape: QualityReport — ok, the validate_document findings (missing fonts, external
assets, large rasters, id problems, viewBox sanity), quantitative metrics (object/node/layer
counts, embedded-raster weight in bytes, font coverage, viewBox health), and opportunities
(keyed identically to svg_web_optimize.removed: editor metadata, unused defs, unreferenced
ids, empty groups, reducible coordinate precision). Every field is structured (not prose).
Example: quality_report(doc_id)
Risk class: low (read-only; document unchanged).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| score | Yes | |
| doc_id | Yes | |
| metrics | Yes | Quantitative document metrics (all read-only). |
| findings | Yes | |
| error_count | Yes | |
| opportunities | Yes | |
| warning_count | Yes |
TDQS
A4.6/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, destructiveHint=false. Description adds 'Risk class: low (read-only; document unchanged)' and details return shape including fields and structure. Adds significant context beyond 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?
Well-structured with clear sections (purpose, usage, params, return shape, example, risk). Each sentence adds value, though slightly verbose. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema existence, description comprehensively covers validation findings, metrics, opportunities structure. Single param is simple. No gaps for tool complexity.
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 coverage is 0%, but tool has only one parameter doc_id. Description mentions 'Key params: none beyond doc_id' and includes it in example, but does not explain its purpose or format. Adequate for a simple single-param tool but not exceptional.
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?
Clearly states verb 'build' and resource 'machine-readable quality report for a document'. Distinguishes from siblings validate_document and svg_web_optimize by scope and use case.
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?
Explicitly states when to use (assessing document health) and when not (pass/fail correctness -> validate_document, stripping opportunities -> svg_web_optimize). Provides clear alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
quality_report_setQuality report (set)ARead-only
Quality-report a SET of documents in one call: per-doc reports + aggregate + verdict.
When to use: auditing a whole multi-document system (e.g. a 12-icon set) for health AND
cross-doc consistency in one read-only call. For a SINGLE document use quality_report; to
actually strip the opportunities across the set use optimize_set.
Key params: doc_ids is a non-empty, duplicate-free set. Read-only — composes the single-doc
quality_report engine over the set, so NO snapshot / Operation Record is written for any
document. The whole set is rejected if ANY id is unknown or unparseable (no partial result).
Return shape: QualityReportSetResult — per_doc (the standard QualityReport per document),
all_ok, worst_score / mean_score and total_opportunities aggregated across the set, and
consistency — the structured cross-doc verdict over the set's viewBox / stroke-width /
id-naming conventions (the cross-doc audit a 12-icon system used to need a Bash/lxml loop for).
Example: quality_report_set(["d1","d2","d3"])
Risk class: low (read-only; no document mutated, no Operation Record / snapshot).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_ids | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| all_ok | Yes | |
| per_doc | Yes | |
| mean_score | Yes | |
| consistency | Yes | Structured cross-document consistency audit over a set. One :class:`ConsistencyProperty` per audited property (``viewBox``, ``stroke_width``, ``id_naming``). ``consistent`` is True iff EVERY audited property agrees across the set. Not prose: an agent reads ``properties`` to see precisely which property disagrees and which ``doc_ids`` carry which value. |
| worst_score | Yes | |
| total_opportunities | Yes |
TDQS
A4.8/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds valuable context: no snapshot/Operation Record written, all-or-nothing rejection, and cross-doc consistency check. Does not contradict 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?
Well-structured with labeled sections (intro, when to use, key params, return shape, example, risk class). Every sentence serves a purpose, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, parameter constraints, return shape description, and risk class. Despite having an output schema, the description adds necessary context for the agent to understand the tool's behavior fully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage. Description adds critical semantics: `doc_ids` must be non-empty and duplicate-free, and the entire set is rejected if any ID is invalid (no partial results).
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?
Description clearly states it quality-reports a SET of documents with per-doc reports, aggregate, and verdict. It distinguishes from siblings `quality_report` (single doc) and `optimize_set` (action vs audit).
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?
Explicit 'When to use' section advises for auditing multi-doc systems and directly names alternatives: `quality_report` for single doc and `optimize_set` for stripping opportunities.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
reload_documentReload documentARead-onlyDestructive
Refresh a working copy FROM ITS SOURCE under the SAME doc_id, discarding working edits.
When to use: external edits changed the source file and you want to resync in place (keep the
same doc_id). To undo a single edit instead use restore_snapshot; to open a different file
use open_document.
Key params: doc_id must be open. Flow (reversible): take a PRE-reload snapshot of the current
working copy (undo via restore_snapshot), re-resolve the source through the sandbox and
re-validate it is STILL inside the workspace (a moved/vanished source is rejected with a stable
"path rejected" message), then re-copy the source over the working copy. A create_document
document has no external source, so its reload restores from its blank seed.
Return shape: ReloadDocumentResult — refreshed summary plus pre_reload_snapshot_id (the
pre-reload checkpoint).
Example: reload_document(doc_id)
Risk class: low (only the working copy is rewritten, reversibly; the original is never written).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| summary | Yes | Top-level document summary (viewBox / page / size / counts). |
| pre_reload_snapshot_id | Yes |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Provides detailed behavioural flow: pre-reload snapshot, re-resolving source, validation, rejection message. Discloses that create_document reloads from blank seed, and risk class (low, reversible, only working copy rewritten). Adds context beyond 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?
Well-organized with clear front-loaded purpose, usage, behavioral details, return shape, example, and risk. No superfluous sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, behavior, parameter, return shape (output schema exists), example, and risk. Complete for the tool's complexity and single parameter.
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?
With schema coverage at 0%, description compensates by explaining doc_id must be open and is the only parameter. Could elaborate more on doc_id format or constraints, but sufficient.
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?
Clearly states the tool refreshes a working copy from its source under the same doc_id, discarding edits. Distinguishes from siblings restore_snapshot and open_document by specifying different use cases.
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?
Explicitly states when to use (external edits changed source, want to resync in place), when not to use (for undo or opening different file), and names alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
rename_objectRename objectAIdempotent
Change an object's id and/or its inkscape:label.
When to use: giving an object a stable/human id or label. To copy it use duplicate_object; to
keep an id surviving svg_web_optimize add it to that tool's keep_ids.
Key params: provide new_id and/or label (at least one required). Changing the id validates
the new id (safe charset, not already used) and rewrites all in-document references to the old
id so nothing dangles. label is set on inkscape:label.
Return shape: EditResult — operation_id, snapshot_id, changed, before/after preview; the
edit lands on the working copy only (reversible).
Example: rename_object(doc_id, "rect12", new_id="header", label="Header bar")
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium (reversible edit on the working copy; original untouched).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| label | No | ||
| doc_id | Yes | ||
| new_id | No | ||
| object_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (idempotentHint=true, destructiveHint=false), the description explains id validation, reference rewrites, working copy modification (reversible), and risk class. No contradictions; adds substantial behavioral context.
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?
The description is efficiently structured: one-line summary, bulleted usage, key params, return shape, example, and risk note. Every sentence adds value; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, no schema descriptions, but has output schema), the description covers purpose, parameters, return, examples, safety notes, and usage guidance. It is fully complete for an AI agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by naming `new_id` and `label`, stating at least one required, detailing validation for `new_id` and meaning of `label`. This adds crucial meaning missing from 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?
The description clearly states the tool changes an object's `id` and/or `inkscape:label`. It distinguishes itself from `duplicate_object` and `svg_web_optimize`, making the purpose specific and differentiated from siblings.
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?
Provides explicit when-to-use guidance (stable/human id or label), contrasts with alternatives (`duplicate_object` for copying, `keep_ids` in `svg_web_optimize`), and advises to render a preview before trusting. This fully satisfies the dimension.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
render_previewRender previewARead-only
Render a PNG preview of the whole document into the artifacts dir.
When to use: a quick visual check of the whole document. For a final file use `export_document`;
for one object use `export_object`; for an ordered run series use `capture_frame`.
Key params: `width_px` scales the raster (height follows the document aspect ratio); omit for
intrinsic size. Oversized requests are rejected before Inkscape runs. `name` tags the file
(successive calls do NOT clobber, — each render gets a unique frame name). INLINE RASTER
: by default the PNG is also returned as an MCP image block so the agent SEES it without
a second Read; gated by max_output_bytes (~5 MiB default) and skipped for an oversized
render; inline=False returns only the structured result.
Return shape: `PreviewResult` — `artifact_path` / `workspace_relative_path` (same root-relative
value), `format`, `width_px`/`height_px` (TRUE on-disk size), `stale`. With an inline
image, a `ToolResult` carrying the same structured fields plus the image block.
Example: `render_preview(doc_id, width_px=512)`
Risk class: low (render/export to artifact dir; no original overwrite).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| doc_id | Yes | ||
| inline | No | ||
| width_px | No | ||
| max_output_bytes | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| stale | No | |
| doc_id | Yes | |
| format | Yes | |
| width_px | Yes | |
| all_blank | No | |
| height_px | Yes | |
| opaque_px | No | |
| artifact_path | Yes | |
| workspace_relative_path | Yes |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true (safe read) and destructiveHint=false. The description adds valuable context: risk class 'low' with rationale (render/export to artifact dir, no original overwrite), behavior on oversized requests (rejected before Inkscape runs), and that successive calls do not clobber (unique frame names). It also explains the inline image gating by max_output_bytes. Everything adds beyond 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?
The description is well-structured with clear sections (purpose, when to use, key params, return shape, example, risk class). It front-loads the core purpose, then adds detail in a logical order. However, it is somewhat lengthy (8 sentences), and might be slightly more concise by merging the return shape description into the param section. Still, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, output schema exists), the description covers everything needed: purpose, usage boundaries, parameter details, return shape (referencing output schema), an example call, and risk assessment. The output schema is mentioned but not redundantly detailed, which is appropriate since the schema itself provides structure. No gaps are apparent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description bears full responsibility for parameter meaning. It covers all 5 parameters: width_px (scaling, omit for intrinsic), name (file tag, uniqueness), inline (boolean, default true, inline image behavior), max_output_bytes (gating threshold), and doc_id (implied required). Each parameter's effect and defaults are explained, providing complete semantics.
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?
The description clearly states the tool renders a PNG preview of the whole document to the artifacts directory. It distinguishes from sibling tools by explicitly naming alternatives (export_document, export_object, capture_frame), making the specific resource and action obvious.
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?
The description includes a dedicated 'When to use' section that specifies the scenario (quick visual check) and provides explicit guidance on when to use alternative tools for final files, single objects, or ordered runs. This leaves no ambiguity about appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
reparent_objectReparent objectA
Move an object (object_id) under a new parent (new_parent_id); both must exist.
When to use: re-nesting one existing object into another group. To wrap SEVERAL objects in a new
group use group_objects; to reposition without re-nesting use move_object.
Key params: object_id and new_parent_id both must exist; rejected if the new parent is the
object itself or one of its descendants. NOTE: re-parenting changes the inherited coordinate
space — the object's visual position can shift if old/new parents carry different transforms.
Return shape: CreateResult — object_id echoes the moved object, bbox=None, plus the
pipeline fields (operation_id, snapshot_id, changed, preview).
Example: reparent_object(doc_id, "star", "layer2")
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium (reversible edit on the working copy; original untouched).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes | ||
| object_id | Yes | ||
| new_parent_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| bbox | No | |
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| object_id | Yes | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (which mark readOnlyHint false and destructiveHint false), the description discloses important behavioral traits: rejection if new parent is self/descendant, change in inherited coordinate space affecting visual position, and the recommendation to render a preview before trusting. These details add significant transparency.
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?
The description is well-structured and front-loaded with the core action. It uses separate paragraphs for usage, key params, return shape, and example. Every sentence adds value, though a slight tightening could be possible.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema ('CreateResult'), the description appropriately covers return shape, key constraints, and risk. It also provides a concrete example and a safety warning. The tool is moderately complex, and the description fully equips an agent to use it correctly.
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?
With 0% schema description coverage, the description carries the full burden. It explains the meaning of `object_id` and `new_parent_id` ('both must exist') and gives an example, but does not explicitly describe `doc_id`. However, `doc_id` is a common document identifier and the context likely implies it. The description adds meaningful semantic value beyond the raw 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?
The description starts with a clear verb+resource: 'Move an object under a new parent'. It explicitly distinguishes from sibling tools 'group_objects' (wrapping several) and 'move_object' (repositioning without re-nesting), ensuring the agent selects the correct tool.
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?
The description includes a 'When to use' section that sets precise context and names alternatives. It provides an example and a risk class ('medium'), giving the agent clear guidance on when this tool is appropriate and what to expect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
replace_colorReplace colorADestructive
Replace one colour with another across the document (or within scope_ids subtrees).
When to use: swapping every occurrence of one colour for another. For a multi-colour theme swap
use apply_palette; to recolour specific objects only use set_fill / set_stroke.
Key params: both colours are validated; matching is case- and hex-shorthand-insensitive and
covers inline-style colour properties (fill, stroke, stop-color, ...) and the same-named
presentation attributes. scope_ids, if given, confines the replacement to those elements'
subtrees (each id must exist).
Return shape: EditResult — operation_id, snapshot_id, changed (false if the colour was
not found anywhere in scope), before/after preview; lands on the working copy only (reversible).
Example: replace_color(doc_id, "#ff0000", "#3366cc")
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes | ||
| to_color | Yes | ||
| scope_ids | No | ||
| from_color | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=true), description adds color matching behavior (case- and hex-shorthand-insensitive, covers inline and presentation attributes), scope_ids validation, return shape EditResult, reversible nature, and preview recommendation. No contradiction with 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?
Well-structured: one-sentence purpose, usage guidance, key params with details, return shape, example, safety note. Every sentence adds value, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a mutation tool with 4 params: explains parameters, behavior, return shape, side effects, and risk mitigation. No gaps given annotations and output schema (EditResult described).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, description explains scope_ids (confines to subtrees, ids must exist), from_color/to_color validation and matching semantics, and provides an example. Compensates fully for missing schema descriptions.
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?
Description clearly states 'Replace one colour with another' with explicit scope (document or scope_ids subtrees). Differentiates from siblings like apply_palette and set_fill/set_stroke.
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?
Explicit 'When to use' section with clear guidance on when to use this tool vs alternatives (apply_palette for multi-colour, set_fill/set_stroke for specific objects).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
replace_textReplace textADestructive
Replace the text content of a text element (<text> / <tspan> / flow text).
When to use: changing what a text object says (get its id from find_objects). To change the
font/size use set_font; to rename the element's id use rename_object.
Key params: object_id must be a text-bearing element; text is length-bounded and may not
contain control characters other than tab / newline / carriage return. If the <text> has
<tspan> children they are dropped and the content collapses to a single run.
Return shape: EditResult — operation_id, snapshot_id, changed, before/after preview; the
edit lands on the working copy only (reversible).
Example: replace_text(doc_id, "title", "Hello")
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium (reversible text edit on the working copy; original untouched).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | ||
| doc_id | Yes | ||
| object_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses critical behavioral details: `<tspan>` children are dropped, content collapses to single run, edit is on working copy only and reversible. Annotations already indicate `destructiveHint: true` and `readOnlyHint: false`, but description adds nuance about reversibility and risk level. No contradiction.
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?
Well-structured with sections for purpose, usage, params, return shape, example, and risk. However, some sentences are slightly verbose (e.g., 'Render and look before you trust this edit'). Still efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all aspects: purpose, usage, params, behavior (child handling), return shape, example, and risk. Output schema exists but description still explains `EditResult` fields. Complete for a medium-risk text editing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description fully compensates by explaining `object_id` must be a text-bearing element and `text` has length and character restrictions. Also provides concrete example mapping parameters.
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?
Description clearly states it replaces text content of text-bearing elements like `<text>` and `<tspan>`, with specific examples. Distinguishes itself from siblings like `set_font` and `rename_object`.
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?
Explicitly states when to use (changing what text says) and when not to (for font/size use `set_font`; for renaming use `rename_object`). Provides example and links to `find_objects` for obtaining IDs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
resize_canvasResize canvasAIdempotent
Set the document canvas width / height to validated CSS lengths.
When to use: changing the PAGE size. To crop the page to the art use fit_to_content, to repair
the viewBox use normalize_viewbox, to resize one OBJECT use scale_object.
Key params: width/height are validated CSS lengths; child geometry is not altered. By
default an existing viewBox is preserved (synthesized only when absent). adjust_viewbox=True
RETARGETS the viewBox to "0 0 W H" so it tracks the new canvas (opt-in; changes the
coordinate system). BLEED (opt-in): bleed > 0 ALSO grows the viewBox outward by that
many user units on every side and paints the new border strip with bleed_color (validated
colour, default white) via one background <rect> behind all content — a print-bleed resize in
ONE call instead of a second scale_object/background step. bleed needs a valid existing or
derivable viewBox and is mutually exclusive with adjust_viewbox.
Return shape: EditResult — operation_id, snapshot_id, changed (real before/after content
diff), before/after preview; the edit lands on the working copy only (reversible).
Example: resize_canvas(doc_id, "800", "600"); with bleed:
resize_canvas(doc_id, "800", "600", bleed=8, bleed_color="#fff")
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| bleed | No | ||
| width | Yes | ||
| doc_id | Yes | ||
| height | Yes | ||
| bleed_color | No | #ffffff | |
| adjust_viewbox | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description covers all behavioral traits: child geometry unchanged, viewBox preservation vs adjustment, bleed behavior with viewBox growth and background rect, mutual exclusivity of bleed and adjust_viewbox, and return shape with EditResult. Annotations provide readOnlyHint, destructiveHint, idempotentHint; description adds risk class and working copy edit details.
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?
Well-structured with clear sections, each sentence adds value. No filler. Includes purpose, usage, key params, return shape, example, and caution.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete coverage for a 6-parameter tool with 3 required, no nested objects, and output schema. Describes all parameters, edge cases, return value, and provides example. Agent has sufficient info to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description fully compensates. It explains each parameter in detail: width/height as validated CSS lengths, bleed opt-in with viewBox growth and color, adjust_viewbox default false, mutual exclusivity, and example usage.
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?
Description explicitly states 'Set the document canvas width/height to validated CSS lengths' and distinguishes from sibling tools like fit_to_content, normalize_viewbox, and scale_object.
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?
Provides clear 'When to use' directive for changing PAGE size and explicitly lists when not to use with alternative tools. Also includes caution to render preview before trusting and notes reversibility.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
restore_snapshotRestore snapshotADestructive
Revert a document's working copy to a chosen snapshot.
When to use: undoing/rolling back to an earlier checkpoint. To find a snapshot_id use
list_snapshots; to make a new checkpoint use create_snapshot.
Key params: snapshot_id names the target checkpoint (must exist for this document).
Return shape: RestoreResult — the reversibility-chain links plus restored_sha256 (SHA-256
hex digest) and restored_size_bytes of the restored working copy, so a caller can assert
recovery succeeded without reading the document off disk.
Example: restore_snapshot(doc_id, snapshot_id)
Risk class: medium (reverts working copy via Operation Record; never touches the original).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes | ||
| snapshot_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| operation_id | Yes | |
| restored_from | Yes | |
| restored_sha256 | Yes | |
| restored_size_bytes | Yes | |
| pre_restore_snapshot_id | Yes |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses risk class ('medium') and mechanism ('reverts working copy via Operation Record; never touches the original'), adding context beyond annotations. Return shape details help caller verify recovery, compensating for the lack of output schema in the input.
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?
Well-structured with clear sections: purpose, usage, key params, return shape, example, risk class. Every sentence adds value with no redundancy. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 required params) and the presence of annotations (destructiveHint) and mention of output schema, the description fully covers what an agent needs: purpose, when to use, params, return shape, and risk. No 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 0%, so description carries burden. It explains snapshot_id ('names the target checkpoint, must exist') and provides a full example. However, doc_id is not explicitly described, though it's clear from context. Still, the description adds significant value beyond 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?
Description opens with 'Revert a document's working copy to a chosen snapshot', clearly stating the verb (revert) and resource (working copy). This differentiates it from siblings like create_snapshot and list_snapshots.
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?
Explicitly says 'When to use: undoing/rolling back to an earlier checkpoint' and provides sibling references for related actions (list_snapshots, create_snapshot), giving clear guidance on when to use this tool vs alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
rotate_objectRotate objectA
Rotate an object/group by degrees about a point.
When to use: spinning one object; get its id from find_objects. To move use move_object, to
resize use scale_object.
Key params: degrees is the rotation angle; it rotates about (cx, cy) when BOTH are given,
otherwise about the parent coordinate-space origin.
Return shape: EditResult — operation_id, snapshot_id, changed (real before/after content
diff), before/after preview; the edit lands on the working copy only (reversible).
Example: rotate_object(doc_id, "arrow", 90, cx=50, cy=50)
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cx | No | ||
| cy | No | ||
| doc_id | Yes | ||
| degrees | Yes | ||
| object_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes return shape (EditResult with operation_id, snapshot_id, changed, before/after preview), states the edit is reversible on the working copy, and includes risk class. Annotations are minimal (false flags), but description adds substantial behavioral context without contradiction.
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?
Well-structured with a clear opening sentence, then sections for usage, key params, return shape, example, and caution. Every sentence adds value; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, output schema present, and the tool's medium complexity, the description covers purpose, parameters, usage alternatives, return details, risk, and post-edit verification steps. It is fully informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully explains degrees, cx/cy rotation behavior ('when BOTH given otherwise about origin'), and provides an example. It also links object_id to find_objects. All parameters are meaningfully described.
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?
The description clearly states 'Rotate an object/group by degrees about a point', using a specific verb and resource. It also distinguishes from siblings by explicitly mentioning when to use move_object or scale_object instead.
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?
Provides explicit when-to-use context: 'When to use: spinning one object; get its id from find_objects.' It also gives alternatives and notes that rotation center behavior depends on cx/cy presence. Additionally advises to render and check before trusting, with revert option.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
save_document_asSave document asADestructive
Save a document's current working-copy state to a NEW file in the workspace.
When to use: persisting the working copy to disk. To export a raster/PDF instead use
export_document; to snapshot in-server state (not a file) use create_snapshot. The original
and source files are never touched.
Key params: dest_path may be RELATIVE or absolute — relative anchors to the FIRST configured
workspace root (NOT the server CWD); absolute must resolve inside a configured root. A dest into
a not-yet-existing SUBFOLDER (e.g. "output/final.svg") is supported: missing parents are
created only after proving they resolve INSIDE the workspace (a ..-escaping / out-of-sandbox
dest creates nothing and is rejected with path rejected: outside workspace). The dest is
sandbox- and symlink-checked (incl. a pre-existing symlink at the final name) and the copy never
follows a symlinked dest (sec.12). Overwriting an existing file requires overwrite=True PLUS a
non-empty approval_token.
Return shape: SaveResult — saved_path (workspace-relative POSIX), operation_id,
overwritten, and pre_validation / post_validation (the validate_document reports from
before and after the write).
Example: save_document_as(doc_id, "output/final.svg")
Risk class: medium for a new-file save; high (approval-gated) when overwriting an existing file.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes | ||
| dest_path | Yes | ||
| overwrite | No | ||
| approval_token | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| saved_path | Yes | |
| overwritten | Yes | |
| operation_id | Yes | |
| pre_validation | Yes | Structured, machine-readable validation result for one document. `ok` is True iff there are no `error`-severity findings. `error_count` / `warning_count` are convenience tallies over `findings`. |
| post_validation | Yes | Structured, machine-readable validation result for one document. `ok` is True iff there are no `error`-severity findings. `error_count` / `warning_count` are convenience tallies over `findings`. |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses behavioral traits beyond annotations, such as path resolution rules, sandbox checks, symlink handling, and overwrite requirements. It adds valuable context not captured in 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?
The description is well-structured with clear sections and every sentence adds value, but it is somewhat lengthy. Could be slightly more concise without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, output schema present), the description is complete. It covers all key behaviors, edge cases (path escaping, symlinks), return shape, and risk class. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema description coverage is 0%, the description fully compensates by explaining dest_path semantics (relative/absolute, subfolder creation, sandbox checks), overwrite requirement, and approval_token. This is crucial for correct usage.
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?
The description clearly states the tool's purpose: 'Save a document's current working-copy state to a NEW file in the workspace.' It uses specific verbs and resources, and distinguishes itself from siblings like export_document and create_snapshot.
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?
Explicitly describes when to use the tool ('persisting the working copy to disk') and when not to (use export_document for raster/PDF, create_snapshot for in-server state). Also notes that original and source files are never touched, providing clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
scale_objectScale objectA
Scale an object/group by factor sx (and sy, defaulting to sx for uniform).
When to use: resizing one object; get its id from find_objects. To reposition use
move_object, to rotate use rotate_object, to resize the whole page use resize_canvas.
Key params: sx (and optional sy, defaulting to sx for uniform) scale about the parent
coordinate-space ORIGIN; non-finite or non-positive factors are rejected.
Return shape: EditResult — operation_id, snapshot_id, changed (real before/after content
diff), before/after preview; the edit lands on the working copy only (reversible).
Example: scale_object(doc_id, "logo", 2)
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sx | Yes | ||
| sy | No | ||
| doc_id | Yes | ||
| object_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant context beyond annotations: scaling about parent origin, non-finite/non-positive factors rejected, edit lands on working copy (reversible), returns EditResult with details, risk class medium, and recommends rendering before trusting. Annotations only provide readOnlyHint=false, destructiveHint=false.
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?
The description is concise (~150 words), well-organized into sections: action, when to use, key params, return, example, risk. Every sentence adds value and it is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters with 0% schema coverage, output schema exists, and annotations provided, the description is complete. It covers usage, parameters, return shape, risk, and an example. No 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 0%, so description compensates. Explains sx as scale factor, sy defaults to sx for uniform, and constraints about origin and valid values. doc_id and object_id are mentioned but not elaborated, though they are standard identifiers.
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?
The description clearly states the tool scales an object/group by factor sx, with optional sy defaulting to sx for uniform scaling. It specifies the verb 'scale' and the resource 'object/group', and distinguishes from siblings like move_object, rotate_object, and resize_canvas.
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?
Explicitly states when to use: resizing one object, and that object_id comes from find_objects. Provides clear alternatives for repositioning (move_object), rotating (rotate_object), and resizing the whole page (resize_canvas).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
set_document_svgSet document SVGADestructiveIdempotent
REPLACE the whole working copy with an agent-composed SVG string (root must be <svg>).
When to use: adopting a full SVG composed in memory, replacing the working copy wholesale (no
file round-trip). To ADD to (not replace) a document use insert_svg_fragment; for a blank
start use create_document.
Key params: svg root must be <svg>; it is byte-size-checked, safe-parsed, and
allowlist-scrubbed — <script>, any on* handler, javascript: hrefs, and external refs
(http(s):// / // / file: / data:) are REJECTED; only a same-document #id reference is
allowed. A real run REQUIRES a non-empty approval_token. The original/source file is never
touched.
Return shape: ComposeResult — an EditResult (operation + pre-mutation snapshot links,
reversible via restore_snapshot) extended with the post-adopt validate_document findings
(validation).
Example: set_document_svg(doc_id, "<svg ...>...</svg>", approval_token="ok")
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: HIGH — requires a non-empty approval_token; without it the op is refused and
nothing is written.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| svg | Yes | ||
| doc_id | Yes | ||
| approval_token | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| validation | Yes | Structured, machine-readable validation result for one document. `ok` is True iff there are no `error`-severity findings. `error_count` / `warning_count` are convenience tallies over `findings`. |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (idempotentHint=true, destructiveHint=true), description adds critical details: security scrubbing (rejects scripts, handlers, external refs), requirement for non-empty approval_token, that original file is untouched, return shape, and advice to preview and restore if wrong. No contradiction with 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?
Well-structured with clear sections: purpose, when to use, key params, return shape, example, risk class. Front-loaded with core action. Slightly lengthy but every sentence adds value. Could be trimmed marginally.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given tool complexity (destructive, idempotent, 3 params, output schema), description covers all needed context: purpose, alternatives, security constraints, required token, return shape, example, risk level, and preview advice. No gaps identified.
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 has 0% description coverage, so description must compensate. It explains svg must be <svg> root and lists security constraints, and clarifies approval_token must be non-empty for execution. Doc_id is not explained, but it's a common parameter. Overall adds significant meaning beyond schema for most parameters.
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?
The description clearly states the action as REPLACE the whole working copy with an agent-composed SVG string, distinguishing it from sibling tools insert_svg_fragment (add) and create_document (blank start).
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?
Explicit when-to-use: adopting a full SVG composed in memory, replacing wholesale. Explicit alternatives: insert_svg_fragment for addition, create_document for blank start. Provides clear context and guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
set_fillSet fillAIdempotent
Set the fill colour (and optional fill opacity) of one or more objects.
When to use: recolouring specific objects' fill (get the ids from find_objects). To change
every instance of a colour document-wide use replace_color; for a whole theme use
apply_palette; for the outline use set_stroke.
Key params: color accepts hex, rgb()/rgba()/hsl()/hsla(), a named colour, or a url(#id)
paint-server reference — a gradient/pattern in <defs>, e.g. an id from add_linear_gradient /
add_radial_gradient (optionally with a fallback colour: url(#id) red). External urls,
javascript:, and CSS-injection punctuation are rejected. opacity, if given, in [0, 1].
Return shape: EditResult — operation_id, snapshot_id, changed (false if the colour was
already present), before/after preview; the edit lands on the working copy only (reversible).
Example: set_fill(doc_id, ["logo"], "#3366cc")
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| color | Yes | ||
| doc_id | Yes | ||
| opacity | No | ||
| object_ids | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (idempotent, non-destructive), the description reveals the edit lands on a reversible working copy, advises rendering before trusting, and assigns a risk class, offering full behavioral context.
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?
The description is well-structured with front-loaded purpose, followed by usage, key parameters, return shape, example, and caution. Every sentence adds value without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 params, output schema exists), the description covers usage, parameter details, return shape (EditResult fields), example, and risk advisory, leaving no gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description compensates thoroughly: it explains color format (hex, rgb, named, url references), rejection of unsafe inputs, opacity range [0,1], and provides an example clarifying object_ids usage.
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?
The description clearly states the tool sets the fill colour and optional opacity for one or more objects, distinguishing it from siblings like replace_color, apply_palette, and set_stroke by specifying scope.
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?
Explicitly states when to use (recolouring specific objects' fill) and when not (document-wide colour change or outline), providing specific alternative tools: replace_color, apply_palette, set_stroke.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
set_fontSet fontAIdempotent
Set font-family / font-size / font-weight on one or more text objects.
When to use: restyling text typography. To change the words use replace_text; for non-font
fill/stroke use set_fill / set_stroke.
Key params: provide any of family, size, weight (at least one required); each is validated
and written to every target's inline style.
Return shape: SetFontResult — all EditResult fields (operation_id, snapshot_id,
changed, before/after preview; the edit lands on the working copy only, reversible) PLUS glyph
coverage: coverage_ok is False when a target now names a family that cannot render
its text, and font_coverage lists per object the uncovered_chars (read from the font's OWN
cmap, never fontconfig substitution) and a suggested_family that covers them — so a
non-covering font choice is checkable at apply time instead of silently shipping tofu.
Example: set_font(doc_id, ["title"], family="Inter", size="24px")
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium (reversible style edit on the working copy; original untouched).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | ||
| doc_id | Yes | ||
| family | No | ||
| weight | No | ||
| object_ids | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| coverage_ok | No | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| font_coverage | No | |
| preview_after | No | |
| preview_before | No |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description goes beyond annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) by explaining the edit is reversible, lands on the working copy, and includes risk class and detailed return shape with glyph coverage handling. No contradiction with 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?
Well-structured with sections: core purpose, use guidelines, key params, return shape, example, caution note, and risk class. Front-loaded with primary action; every sentence adds value; no extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 params, output schema), the description covers all essential aspects: purpose, usage, parameters, return values (including edge cases like uncovered characters), example, and risk. Nothing is missing for an agent to correctly invoke and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description fully compensates by explaining key parameters: family, size, weight (at least one required), validation, and effect. It provides an example and clarifies the required fields (doc_id, object_ids) implicitly.
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?
The description clearly states it sets font-family/font-size/font-weight on text objects, distinguishing from sibling tools like replace_text (for words) and set_fill/set_stroke (for non-font styling). The verb+resource combination is specific and unambiguous.
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?
The description explicitly says 'When to use: restyling text typography' and contrasts with alternatives: 'To change the words use replace_text; for non-font fill/stroke use set_fill / set_stroke.' This provides clear context and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
set_opacitySet opacityAIdempotent
Set the element-level opacity of one or more objects.
When to use: making whole objects more/less transparent. For fill-only or stroke-only opacity
use set_fill / set_stroke with their opacity argument instead.
Key params: opacity must be in [0, 1] (this is the element opacity, affecting fill AND
stroke together).
Return shape: EditResult — operation_id, snapshot_id, changed, before/after preview; the
edit lands on the working copy only (reversible).
Example: set_opacity(doc_id, ["overlay"], 0.5)
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes | ||
| opacity | Yes | ||
| object_ids | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), description explains the edit is reversible, lands on working copy, and risk class is medium. No contradiction with annotations; adds useful behavioral details.
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?
Well-structured with sections (When to use, Key params, Return shape, Example, etc.), front-loaded with purpose. Slightly lengthy but every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive coverage: input, behavior, output (EditResult described), safety guidelines, and risk. Given output schema exists, description is complete and leaves no gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, description compensates by explaining opacity range [0,1], its effect on fill+stroke, and provides an example. Adds meaning beyond raw 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?
The description clearly states the tool sets element-level opacity of objects, distinguishing it from fill/stroke opacity. It uses specific verb+resource and differentiates from siblings set_fill and set_stroke, making the purpose unambiguous.
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?
Explicitly states when to use (making whole objects transparent) and when to use alternatives (set_fill/set_stroke for fill/stroke-only opacity). Also advises to render and check before trusting, providing clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
set_strokeSet strokeAIdempotent
Set the stroke colour, width, and/or opacity of one or more objects.
When to use: styling an object's outline/border. For the interior use set_fill; to turn a
stroke into a filled outline path use stroke_to_path.
Key params: at least one of color, width, opacity must be supplied. color accepts a
colour OR a url(#id) paint-server reference (gradient/pattern in <defs>, optionally with a
fallback colour); width is a CSS length (number + optional unit); opacity must be in [0, 1].
External urls, javascript:, and CSS-injection punctuation are rejected.
Return shape: EditResult — operation_id, snapshot_id, changed, before/after preview; the
edit lands on the working copy only (reversible).
Example: set_stroke(doc_id, ["border"], color="#000", width="2")
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| color | No | ||
| width | No | ||
| doc_id | Yes | ||
| opacity | No | ||
| object_ids | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false. Description adds critical behavioral details: edit lands on working copy only (reversible), security constraints (rejection of external urls, javascript:, CSS-injection), and a 'Risk class: medium' tag. No contradictions.
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?
Well-structured with clear sections: main action, when to use, key params, return shape, example, rendering advice, risk. Every sentence is informative and earns its place. Front-loaded with the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given presence of output schema (EditResult), description focuses on usage and behavior. Covers parameter constraints, security, reversibility, and post-edit validation. Complete for a styling tool with moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must carry full burden. It explains key params: 'at least one of color, width, opacity must be supplied', describes color as a colour or url(#id) reference, width as CSS length, opacity in [0,1], and security filtering. This adds substantial meaning beyond the schema types.
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?
The description explicitly states 'Set the stroke colour, width, and/or opacity of one or more objects' with a specific verb and resource. It distinguishes from siblings by mentioning 'set_fill' for interior and 'stroke_to_path' for converting to outline.
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?
Includes a 'When to use' section (styling outline/border) and clear alternatives: 'For the interior use set_fill; to turn a stroke into a filled outline path use stroke_to_path'. Also advises to render and inspect before trusting, and to use restore_snapshot for reversion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
stat_artifactStat artifactARead-only
Return the on-disk byte size + sha256 digest of one sandboxed artifact.
When to use: to VERIFY what you wrote (an export, a render, a saved SVG) — its exact byte size
and content digest — without a wc -c / sha256sum Bash fallback. For a whole SET (and an
aggregate byte total) use stat_artifacts; for image pixel dimensions read the producing
tool's result fields instead.
Key params: path may be workspace-RELATIVE (anchored to the first workspace root, matching
open_document / save_document_as) or absolute; either is sandbox-validated and a
../-escape, an absolute path outside the workspace, or a symlink whose target leaves the
sandbox is rejected with path rejected: outside workspace. The file must exist and be within
the configured size limit; the sha256 is computed streaming so a large file is bounded in
memory.
Return shape: ArtifactStat — {path, bytes, sha256} where path is the WORKSPACE-RELATIVE
POSIX path (never a host path) and sha256 is the lowercase hex digest.
Example: stat_artifact("dist/logo.png")
Risk class: low (read-only stat; nothing is mutated, no Operation Record / snapshot).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| path | Yes | |
| bytes | Yes | |
| sha256 | Yes |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint=true and destructiveHint=false. The description adds significant context beyond annotations: path validation rules (workspace-relative/absolute, sandbox validation, rejection of escapes, symlinks), file existence/size limits, streaming sha256 computation, and low risk class. No contradictions.
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?
The description is well-structured with sections: main purpose, when to use, key params, return shape, example, risk class. Every sentence adds value, though it is slightly verbose for a simple read-only tool. Could be tightened slightly, but still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one param, read-only, one output), the description covers all relevant aspects: purpose, usage guidelines, parameter details, return shape, and risk assessment. No missing information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has one parameter 'path' with no description (0% coverage). The description compensates fully by explaining path semantics: workspace-relative (anchored to first root), absolute allowed, validation rules, and rejection conditions. Also provides an example. This is thorough for a single parameter.
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?
The description clearly states the tool returns 'on-disk byte size + sha256 digest of one sandboxed artifact', specifying the verb 'return', the resource 'sandboxed artifact', and the outputs. It distinguishes from sibling 'stat_artifacts' which handles a set, and mentions alternatives for image dimensions.
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?
Explicitly says 'When to use: to VERIFY what you wrote' and provides scenarios like verifying exports, renders, saved SVGs. Also states when not to use: for a whole set use 'stat_artifacts', for image pixel dimensions use other tool's result fields.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
stat_artifactsStat artifactsARead-only
Stat a SET of sandboxed artifacts: per-file size + sha256 plus an aggregate byte total.
When to use: to verify a whole produced collection (an icon set, a dist/ tree) and read its
TOTAL byte budget in one call — the readback half of a batch export, without a du -cb. For a
single file use stat_artifact.
Key params: paths is a non-empty list; each entry is resolved EXACTLY as stat_artifact
resolves its path (workspace-relative or absolute, sandbox + symlink validated, size-capped).
The first entry that escapes the sandbox or exceeds the size limit fails the whole call with a
stable message — nothing partial is returned.
Return shape: ArtifactStatSet — {artifacts: [{path, bytes, sha256}], total_bytes, count}
where total_bytes is the sum of the per-file sizes and every path is workspace-relative
(never a host path).
Example: stat_artifacts(["dist/16.png", "dist/32.png", "dist/64.png"])
Risk class: low (read-only stat; nothing is mutated, no Operation Record / snapshot).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| paths | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| artifacts | Yes | |
| total_bytes | Yes |
TDQS
A4.8/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds detail beyond annotations: explains failure behavior (first failing entry causes whole call to fail with stable message) and risk class (read-only, no mutation). Annotations already indicate read-only, so description enriches.
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?
Well-structured: purpose statement, usage section, key params, return shape, example, risk class. Every sentence adds value; no redundancy. Front-loaded with essential info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a stat tool: covers purpose, usage, parameter, return shape (output schema exists), and risk. No gaps given the tool complexity and existing structured fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only parameter 'paths' is thoroughly described: non-empty list, resolution logic (same as stat_artifact), sandbox/symlink validation, size-cap, and failure behavior. Schema has 0% description coverage, so description compensates fully.
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?
Description clearly states the tool stats a SET of artifacts, listing per-file size, sha256, and aggregate byte total. It distinguishes from the sibling stat_artifact tool which handles a single file.
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?
Explicit 'When to use' section guides when to use this tool (verify a whole produced collection, readback of batch export) and when not (single file -> use stat_artifact). Clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
svg_web_optimizeOptimize SVG for webA
Web-optimize an SVG: strip editor metadata, drop dead structure, reduce coordinate precision.
When to use: losslessly shrinking an SVG for the web (direct-DOM, non-destructive). To inspect
what WOULD be stripped first use quality_report; for lossy node reduction use simplify_path.
Key params: three reversible cleanups — (1) remove Inkscape/sodipodi editor-only elements,
namespaced attributes, and XML comments; (2) drop unreferenced <defs>, every unreferenced
id, and empty groups (referenced ids preserved so no #frag / url(#frag) / href breaks);
(3) round geometry numbers (path d, transforms, x/y/width/…) to precision decimals
(0-8, default 2; root viewBox untouched). keep_ids is an allowlist of ids that must NEVER be
stripped as "unreferenced" — pass a deliberate human/a11y id (e.g. one from rename_object) to
keep "one clean file with a stable id"; unknown ids are ignored. Re-running on
optimized output removes/rounds nothing further.
Return shape: WebOptimizeResult — the reversible-edit fields (operation_id, snapshot_id,
before/after preview) plus machine-diffable deltas bytes_before, bytes_after, and removed
(a {code: count} map keyed IDENTICALLY to quality_report.opportunities), so an agent on a
byte budget can compute the saving without parsing prose or stat-ing the file.
Example: svg_web_optimize(doc_id, precision=2, keep_ids=["header"])
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes | ||
| keep_ids | No | ||
| precision | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| changed | Yes | |
| removed | Yes | |
| summary | No | |
| bytes_after | Yes | |
| snapshot_id | Yes | |
| bytes_before | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description details the exact transformations: removal of editor metadata, unreferenced defs/ids, and coordinate rounding. It notes that re-running does nothing further, implying idempotency, and states the risk class as 'medium.' It also mentions the result is reversible via snapshots, which the annotations do not cover. This provides rich behavioral context for safe invocation.
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?
The description is well-structured and front-loaded with a one-line summary. Each section serves a purpose: when to use, key parameters, return shape, example, and safety advice. Every sentence earns its place without redundancy. The length is appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description covers all necessary aspects: purpose, usage, parameters, behavior, idempotency, return shape, and risk. The output schema is referenced but not detailed, which is acceptable. The description is self-contained enough for an agent to select and invoke the tool correctly without external documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining each parameter: `precision` (rounding decimals 0-8, default 2), `keep_ids` (allowlist to preserve ids, unknown ids ignored), and `doc_id` (implied via example). It also clarifies the effect of re-running, which is crucial for idempotence. This adds significant meaning beyond the raw 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?
The description clearly states the tool's purpose: 'Web-optimize an SVG: strip editor metadata, drop dead structure, reduce coordinate precision.' It distinguishes from siblings by explicitly mentioning alternatives: 'To inspect what WOULD be stripped first use `quality_report`; for lossy node reduction use `simplify_path`.' The verb 'optimize' combined with specific actions makes the purpose unambiguous.
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?
The description explicitly states when to use this tool: 'losslessly shrinking an SVG for the web (direct-DOM, non-destructive).' It also provides clear alternatives and conditions: 'To inspect what WOULD be stripped first use `quality_report`; for lossy node reduction use `simplify_path`.' Additionally, it advises to 'render and look before you trust this edit' and mentions `restore_snapshot` for reversion, offering complete usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tileTile objectA
Lay out a rows x cols grid of an object in ONE reversible operation.
When to use: repeating one object into a grid in a single call. To move/scale/rotate one object
use move_object / scale_object / rotate_object; to copy once use duplicate_object.
Key params: the target stays as the (0,0) cell; rows*cols - 1 deep copies (each re-id'd
uniquely, intra-clone refs rewritten) are inserted, the copy at (r, c) translated by
(c*dx, r*dy). rows/cols must each be >= 1 and their product must not exceed the engine's
tile cap; dx/dy must be finite. A 4x4 grid is one call (not 30).
Return shape: EditResult — operation_id, snapshot_id, changed (a 1x1 tile reports
changed=False), before/after preview; the whole grid lands under one snapshot (reversible).
Example: tile(doc_id, "dot", 4, 4, 20, 20)
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: medium.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dx | Yes | ||
| dy | Yes | ||
| cols | Yes | ||
| rows | Yes | ||
| doc_id | Yes | ||
| object_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| doc_id | Yes | |
| changed | Yes | |
| summary | No | |
| snapshot_id | Yes | |
| operation_id | Yes | |
| preview_after | No | |
| preview_before | No |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description discloses key behaviors: reversible operation (one snapshot), deep copies with unique IDs, intra-clone reference rewriting, cell (0,0) stays as target, row/col and dx/dy constraints, risk class medium, and advice to preview first. No contradiction with 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?
Well-structured with sections: purpose, when to use, key params, return shape, example, risk note. Every sentence adds value, no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 required params with 0% schema coverage, the description covers usage, behavior, constraints, return shape, example, and risk. Adequate for an agent to use correctly.
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 0%, but description explains rows, cols, dx, dy (grid spacing, constraints) and provides example. doc_id and object_id are not explicitly described but are standard parameters understood from context. Adds significant meaning beyond 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?
The description clearly states the tool's purpose: 'Lay out a rows x cols grid of an object in ONE reversible operation.' It distinguishes from siblings like duplicate_object, move_object, scale_object, rotate_object.
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?
Explicit 'When to use' section with clear alternatives: to move/scale/rotate one object use respective tools, to copy once use duplicate_object. Includes example and constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
transform_objectsTransform objects (selector)ADestructive
Apply ONE typed op to EVERY object a selector matches — one atomic, reversible operation.
When to use: bulk editing keyed by a predicate rather than by hand-listing ids — "recolour every
blue rect", "nudge every text down 4px", "delete every object whose id starts with tmp-". It is
find_objects (the SELECTOR) wired to ONE typed op fanned across the matches, run through the
SAME atomic batch kernel as apply_edits. For a known id list call the dedicated tool
(set_fill, move_object, …) or apply_edits directly; this adds NO authority — only the
select-then-apply fan-out (ADR-002/003: no free text, no raw Action, no loops/expressions).
Key params: selector is the SAME predicate find_objects takes (tag / fill / stroke /
text / id_prefix / bbox, full CSS-cascade paint match); operation is exactly ONE op
tagged by an op field — the accepted set is set_fill / set_stroke / set_opacity /
set_font / move_object / scale_object / rotate_object / delete_object (high), each
with the SAME params as its dedicated tool MINUS the target ids (those from the selector), e.g.
{"op": "set_fill", "color": "#3366cc"}, {"op": "move_object", "dx": 0, "dy": 4}. Document-
wide ops (replace_color, apply_palette, resize_canvas, normalize_viewbox), element
CREATION ops, and identity-conflicting per-id ops (rename_object, replace_text,
duplicate_object) are NOT accepted — they are not meaningful applied identically per match.
dry_run=True (DEFAULT) resolves + validates and returns the matched ids + the projected plan,
writing NOTHING; dry_run=False performs it. max_matches (default 64) REJECTS an over-broad
selector before any mutation. A delete_object op makes the operation HIGH and requires a
non-empty approval_token.
Render and look before you trust it: a transform changes many objects at once — call
render_preview (or live_render_view in live mode) afterwards and inspect the result, and
restore_snapshot(doc_id, snapshot_id) reverts the WHOLE transform in one step.
Return shape: TransformObjectsResult — matched_ids + match_count, the effective
risk_class, the dry_run flag, the projected plan (per-edit op + target id(s)); on a real
run also applied / changed / summary and the single operation_id / snapshot_id (the
revert target).
Example: transform_objects(doc_id, {"tag": "rect", "fill": "#3366cc"}, {"op": "set_fill", "color": "#ff0000"}, dry_run=False)
Risk class: medium (the effective risk is the op's class; a delete_object op escalates the
operation to high and requires approval_token). Reversible via the pre-transform snapshot.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes | ||
| dry_run | No | ||
| selector | Yes | The target selector — the SAME predicate fields `find_objects` takes (no new logic). Every supplied filter is ANDed; an unset filter is ignored. With no filters at all the selector matches every addressable object (then bounded by `max_matches`). `tag` is an exact local element name; `fill` / `stroke` match the EFFECTIVE cascade-resolved paint (casing- / shorthand- insensitive); `text` is a case-insensitive substring; `id_prefix` an id prefix; `bbox` an intersection box. `accurate_bbox` opts into geometry-accurate boxes (one read-only Inkscape `--query-all`) so transformed / path / text objects can match a `bbox`. | |
| operation | Yes | ||
| max_matches | No | ||
| approval_token | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| plan | Yes | |
| doc_id | Yes | |
| applied | No | |
| changed | No | |
| dry_run | Yes | |
| summary | No | |
| risk_class | Yes | |
| match_count | Yes | |
| matched_ids | Yes | |
| snapshot_id | No | |
| operation_id | No |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds extensive behavioral context beyond annotations: reversible via snapshot, dry_run default, risk class, approval_token for delete, and the atomic batch kernel. No contradictions with 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?
Well-structured with front-loaded purpose, when-to-use, key params, caution, return shape, example, and risk. Every sentence adds value; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 params, nested objects, many siblings), the description covers all necessary aspects: purpose, usage, parameters, behavioral traits, return shape, example, risk, and reversibility. Output schema exists for return values, so further detail not needed.
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 description coverage is low (17%), but the description provides rich semantic detail for selector (same as find_objects) and operation (oneOf each op with same params minus ids), plus explains dry_run, max_matches, and approval_token. This compensates well for the schema's minimal descriptions.
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?
The description clearly states it applies one typed operation to every object a selector matches, using specific verbs and nouns. It distinguishes itself from sibling tools like find_objects and apply_edits by describing the select-then-apply fan-out pattern.
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?
Explicitly tells when to use (bulk editing by predicate) and when not to (known id lists use dedicated tools or apply_edits). Also lists operations that are NOT accepted, and provides safety guidelines like dry_run and max_matches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
validate_documentValidate documentARead-only
Validate a loaded document and return structured, machine-readable findings.
When to use: a pass/fail correctness check on a document. For quantitative metrics + optimize
opportunities use quality_report; to fix size opportunities use svg_web_optimize.
Key params: none beyond doc_id.
Return shape: ValidationReport — ok (True iff no error-severity findings), error_count,
warning_count, and findings (each a stable machine code, a severity
error|warning|info, a human-readable message, and an optional locator). Covers missing
fonts, glyph coverage (a missing_glyphs warning naming the characters a text element's
declared font cannot render — read from the font's own cmap, not fontconfig substitution — plus
a covering family to try), external asset refs, large embedded rasters, id problems (duplicate
ids / dangling #id refs), and viewBox presence/sanity.
Example: validate_document(doc_id)
Risk class: low (read-only validation; document unchanged).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| doc_id | Yes | |
| findings | Yes | |
| error_count | Yes | |
| warning_count | Yes |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds rich behavioral context: return shape details, what findings are covered (missing fonts, glyph coverage, etc.), and risk class. No contradictions.
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?
Well-structured: purpose, usage, params, return shape, example, risk class. Each sentence adds value, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema is mentioned (ValidationReport) and description covers the output fields and checks performed. Given the tool's complexity, the description is sufficiently complete for an agent to understand behavior and return value.
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 0% but only one param 'doc_id'. Description states 'Key params: none beyond doc_id' and provides example call, which clarifies usage. Could specify that doc_id refers to a loaded document ID.
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?
Description clearly states it validates a document and returns structured findings. It distinguishes from siblings 'quality_report' and 'svg_web_optimize' by specifying their different purposes.
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?
Explicitly says when to use: 'a pass/fail correctness check on a document.' Provides clear alternatives: 'quality_report' for metrics/optimize and 'svg_web_optimize' for size fixes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
87 tool updates
v0.1.0- First observed
add_linear_gradient - First observed
add_radial_gradient - First observed
apply_edits - First observed
apply_palette - First observed
capture_frame - First observed
check_live_support - First observed
compose_grid - First observed
create_circle - First observed
create_document - First observed
create_ellipse - First observed
create_group - First observed
create_icon_set - First observed
create_line - First observed
create_path - First observed
create_polygon - First observed
create_polyline - First observed
create_rect - First observed
create_snapshot - First observed
create_text - First observed
create_use - First observed
delete_object - First observed
diagnose_runtime - First observed
duplicate_object - First observed
export_batch - First observed
export_document - First observed
export_object - First observed
export_print_profile - First observed
export_set - First observed
export_web_profile - First observed
find_objects - First observed
fit_to_content - First observed
group_objects - First observed
how_do_i - First observed
insert_svg_fragment - First observed
inspect_document - First observed
list_capabilities - First observed
list_frames - First observed
list_snapshots - First observed
live_apply_to_selection - First observed
live_arm_socket - First observed
live_connect - First observed
live_diff_view - First observed
live_disconnect - First observed
live_export_selection - First observed
live_get_active_document - First observed
live_get_scene - First observed
live_get_selection - First observed
live_insert_svg - First observed
live_inspect_selection - First observed
live_install_helper - First observed
live_render_view - First observed
live_session_step - First observed
live_set_selected_text - First observed
live_set_viewport - First observed
live_status - First observed
live_sync_to_workspace - First observed
live_wait_for_change - First observed
move_object - First observed
normalize_viewbox - First observed
open_document - First observed
optimize_set - First observed
place_document - First observed
prune_snapshots - First observed
quality_report - First observed
quality_report_set - First observed
reload_document - First observed
rename_object - First observed
render_preview - First observed
reparent_object - First observed
replace_color - First observed
replace_text - First observed
resize_canvas - First observed
restore_snapshot - First observed
rotate_object - First observed
save_document_as - First observed
scale_object - First observed
set_document_svg - First observed
set_fill - First observed
set_font - First observed
set_opacity - First observed
set_stroke - First observed
stat_artifact - First observed
stat_artifacts - First observed
svg_web_optimize - First observed
tile - First observed
transform_objects - First observed
validate_document
TDQS
A4.2/5.0
Scored across 87 tools
Disambiguation5/5
Every tool has a clearly distinct purpose, reinforced by 'When to use' sections that explicitly differentiate it from related tools. Even similar operations like create_rect vs create_circle vs create_ellipse are well-distinguished.
Naming Consistency5/5
All tool names follow a consistent verb_noun snake_case pattern (e.g., create_rect, set_fill, export_document). No mixing of conventions or ambiguous verbs.
Tool Count1/5
With 87 tools, the count far exceeds the calibration's 'extreme mismatch' threshold for a single server. While each tool may have its place, the sheer volume risks overwhelming an agent and suggests insufficient consolidation.
Completeness4/5
The tool surface covers nearly all core SVG editing operations—creation, styling, transforms, grouping, export, live editing, validation, and optimization. Minor gaps exist (e.g., boolean operations, filters), but agents can accomplish most tasks without dead ends.
Maintenance
ActivityStale
ResponsivenessNo issues
Related MCP Connectors
Generate vector art, vectorize images, and return SVG, PNG, and logo kits to AI agents.
Create and edit architecture diagrams from your AI agent; get an SVG and a live editable canvas.
13 micro-tools for agents: read pages, verify email, convert, validate, diff, extract. AI-operated.
Generate and vectorize clean, editable SVG graphics from text, images, or both.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to control Inkscape for vector graphics editing via MCP tools.58MIT
- AlicenseAqualityDmaintenanceEnables AI agents to vectorize raster images and import vector files (PDF/AI/EPS), then inspect, edit, render, and optimize SVGs locally.6MIT
Rayzia MCPofficial
AlicenseNot gradedqualityCmaintenanceEnables AI agents to drive a live SVG/vector editor, allowing a full observe-and-act loop on a canvas with real tools, state reading, and PNG rendering.MIT