Skip to main content
Glama
nuncaeslupus

drawspec

by nuncaeslupus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

Validate a drawspec document

validate_document
Read-onlyIdempotent

Check whether a drawspec document would render and exactly where it fails; returns all document or fit violations at once so you can fix them in one edit.

Instructions

Check whether render_document would refuse this document, and exactly where. It renders with the same theme and discards the drawing, so it passes only what draws; every violation comes back at once, so one pass is one edit. Call it while writing or editing; skip it when about to render anyway, since render_document refuses in the same shape. Local, deterministic, milliseconds. Refusals are error results with JSON text {"ok": false, "error": "DocumentError", "message": "...", "violations": [{"pointer": "/edges/0/to", "message": "..."}]}: error is e.g. DocumentError or FitError, pointer is RFC 6901 (empty for the whole document), and violations is never empty.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
themeNoA bundled theme name (accent, blueprint, compartment, default, wheel) or a path to a `.toml` theme file on the server's disk, e.g. `blueprint`. Omit for `default`.
documentYesA drawspec document as a JSON object (not a string or a path), e.g. `{"version": 1, "kind": "flow", "nodes": [...], "edges": [...]}`. `list_kinds` names the 36 values `kind` may take, `get_example` returns the smallest valid document of one, and `get_schema` returns its fields (the whole format is published at https://nuncaeslupus.github.io/drawspec/schema/drawspec-v1.schema.json).

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
okYes
kindYes
messageYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.3.4
    • changedInput schema / properties / document / description
      Previous value: -"A drawspec document, as JSON. `list_kinds` names the 36 values `kind` may take, `get_example` returns the smallest valid document of one, and `get_schema` returns its fields (the whole format is published at https://nuncaeslupus.github.io/drawspec/schema/drawspec-v1.schema.json)."New value: +"A drawspec document as a JSON object (not a string or a path), e.g. `{\"version\": 1, \"kind\": \"flow\", \"nodes\": [...], \"edges\": [...]}`. `list_kinds` names the 36 values `kind` may take, `get_example` returns the smallest valid document of one, and `get_schema` returns its fields (the whole format is published at https://nuncaeslupus.github.io/drawspec/schema/drawspec-v1.schema.json)."
    • changedInput schema / properties / theme / description
      Previous value: -"A bundled theme name or a path to a theme file. Omit for the default."New value: +"A bundled theme name (accent, blueprint, compartment, default, wheel) or a path to a `.toml` theme file on the server's disk, e.g. `blueprint`. Omit for `default`."
  2. Addedv0.3.3

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already establish read-only, idempotent, non-destructive, local behavior, and the description adds real substance on top: it renders with the same `theme` and discards the drawing, all violations return at once (one pass = one edit), and it is local, deterministic, and millisecond-scale. It even discloses the exact error payload shape and semantics of `error`, `pointer`, and `violations`.

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?

Information-dense and front-loaded, leading with purpose, then when/when-not, then cost, then error shape. A few clauses ('it passes only what draws', 'one pass is one edit') are terse enough to require a re-read, but nothing is filler.

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?

Even though an output schema exists, the description still explains the refusal shape and the meaning of each error field, and covers cost, determinism, and exact validation semantics. Nothing an agent needs to invoke it correctly or interpret a failure is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: `theme` is applied the same way `render_document` applies it, which tells the agent why the theme parameter exists here. No additional syntax for `document` is offered beyond what the schema already says.

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

Purpose5/5

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

States a precise verb and resource and goes further by defining the semantics: it checks whether `render_document` would refuse the document and pinpoints where. The distinction from the sibling `render_document` is explicit, so an agent can route between them without opening either schema.

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

Usage Guidelines5/5

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

Gives both directions: call it while writing or editing, and skip it when about to render anyway because `render_document` refuses in the same shape. The alternative and the condition that selects it are named outright.

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

Deploy Server

Other Tools