Tool Reference

The MCP endpoint exposes six tools. list_quills, get_template, and get_specs are read-only discovery. create_document, claim_document, and update_document create and revise a document, linked by a claim token the model carries between them: create_document issues it, claim_document binds the document to an account, and update_document reuses it to revise the draft. Each request stands alone — the server keeps no session. 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_template

Fetches a published template by its short code (e.g., HeLiBeKrXeFeCoNiZnAr) — the code a user copies from the template library's Copy for AI chat action. Returns the template's markdown plus the Quill format it targets (quill_ref).

Call it only when the user explicitly supplies a short code. Then run get_specs for the returned quill_ref and build the document from the template's content rather than a blank blueprint. (If the template has no quill_ref, use its content directly as the starting point.)

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, and again before every update_document. The blueprint marks required fields with a <must-fill> sentinel — leaving any in place will fail validation.

create_document

Creates and validates a draft, then returns a claim token and a claim link (a /claim/<code> URL). The draft starts unowned with a 5-minute deadline. Surface the link to the user — not the token, which is the model's secret — and ask for the six-digit device code the link shows. Keep the claim token: claim_document and later update_document both reuse it. See Account Pairing for the full flow.

claim_document

Binds a drafted document to the account that opened its claim link. Takes the claim token from create_document and the six-digit device code the user entered into the chat. On success the document is owned by that account, and the claim page they have open redirects them to it automatically.

The device code is single-use and rate-limited — repeated wrong guesses lock the claim. If the user mistypes, ask them to re-enter the code rather than retrying the same value. If the 5-minute window lapsed, start over with a fresh create_document. The code is consumed, but keep the claim token — update_document reuses it.

update_document

Revises an already-claimed draft in place, using the same claim token — no new link or device code. Takes the claim token plus the full replacement name and content. Call get_specs first, and build the new content by editing the document's current content, not a blank blueprint.

The claim token stays valid for the life of the draft — from the claim until the draft expires (24 hours after claiming). Save Copy copies the draft into the user's library but does not retire the token or delete the draft: update_document keeps editing the ephemeral draft (not the saved copy) until it expires. The call revises content only — it can't read the document back or change its owner.

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::field_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.