Skip to content

Tool Reference

The MCP endpoint exposes three tools. All are stateless; each request stands alone. Input and output schemas are returned by the MCP list_tools call — this page covers behavior that isn't on the wire.

list_quills

Returns the Quills available on this deployment.

Use the returned values as $quill: <name>@<version> (or just <name> for "latest") when composing a document. Pinning a version protects against template changes; omitting it tracks the deployment's current default.

get_specs

Returns the spec for a chosen Quill: a markdown instruction describing block structure and conventions, plus a YAML blueprint listing every accepted field with its type, default, description, and (where applicable) enum values.

Call this before create_document. The blueprint marks required fields with a <must-fill> sentinel — leaving any in place will fail validation.

create_document

Creates a draft document, validates it, and returns a URL the user must open to claim and save it.

The first signed-in user who opens the URL claims the document. Unclaimed documents are swept after the claim window (around 5 minutes; see Overview).

Errors

Errors are returned with isError: true and a plain-text content payload. The MCP layer flattens engine diagnostics to text — there is no top-level structured error object, but each flattened diagnostic carries:

  • severity (always error for failures that block the call)
  • message
  • a stable error code (e.g., validation::must_fill_sentinel, validation::must_fill_absent)
  • a path into the offending field (e.g., memo_for, cards.indorsement[0].action)
  • an optional hint
  • an optional file:line:column location

Failure categories:

  • Parse failure — the content isn't valid Quillmark (missing fence, malformed YAML, $-prefixed key outside {$quill, $kind, $id, $ext}). The text reads "Document parse failed: …".
  • Validation errors — frontmatter is shaped wrong, a required field is missing, an enum value isn't allowed, or a <must-fill> blueprint sentinel was left in place.
  • Ephemeral creation failure — server-side issue persisting the row.

Resolve the offending line and call create_document again. The endpoint is stateless — no cleanup needed between attempts.