Tool Reference

The MCP endpoint exposes five tools, plus a sixth on deployments that turn on device-code claiming. list_quills, get_template, and get_specs are read-only discovery. create_document and update_document create and revise a document, linked by a claim token the model carries between them. 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.

Results carry the workflow with them: each non-terminal one ends with a → Next: line naming the tool to call next, with the values the server already holds filled in.

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 gallery'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 carrying the card-yaml authoring rules and any deployment field policy, plus a blueprint — the Quill's fields as a ready-to-edit document, each annotated with its type, default, and description.

Call this before create_document, and again before every update_document. Build the document by editing the blueprint, not from scratch.

The blueprint marks each field awaiting your input with the YAML tag !must_fill: replace the value and drop the tag. A leftover !must_fill does not block the render — it comes back as a warning.

create_document

Creates and validates a draft, then returns a claim token and a claim link (a /claim/<code> URL). Takes the document name and content, and an optional author display name shown to readers. The draft starts unowned with a 5-minute deadline.

Surface the link to the user — not the token, which is the model's secret. Under the default claim mode, opening the link and signing in is the whole handshake. Under device-code claiming, also ask for the six-digit code the link shows. Keep the claim token either way: update_document reuses it. See Account Pairing for the full flow.

claim_document

Registered only on deployments that turn on device-code claiming; absent from list_tools otherwise.

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 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::field_absent, validation::coercion_failed)
• 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, $ext, $seed}). The text reads "Document parse failed: …".
• Validation errors — frontmatter is shaped wrong, a required field is missing, a value won't coerce to its declared type, or an enum value isn't allowed.
• Policy rejection — a field value the deployment disallows, such as a classification above its ceiling. get_specs declares the policy up front in its instruction.
• 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.