Skip to main content
Glama
Sign In
Kiln

Kiln

by codeofaxel
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

issue_preview_token

Issue a single-use preview-confirmation token after a user views a print via stage, URL, or PNG. Pass it to start_print or fulfillment_order to prevent sending unseen files to a physical printer.

Instructions

Issue a preview-confirmation token for a file about to be printed.

Call this AFTER the user has seen the print, and say WHICH door showed
it — ``door`` is required and is checked against what this server
itself recorded, never taken on your word:

1. ``door="stage"`` — the inline 3D stage (the MCP Apps panel that
   opens on a make, which the user can orbit).  This is the first and
   best option.  Accepted only when the panel actually fetched the
   geometry for this file (or for the design mesh it was sliced from).
2. ``door="url"`` — a hosted viewer link.  Use it when this host draws
   no panel.  Accepted only when ``show_on_stage(file_path)`` issued
   a ``viewer_url`` for this file that is still live (its result
   carries one on a host that draws no panel, while the machine is
   signed in).
3. ``door="png"`` — the stage's own still (``visualize_model`` with
   ``renderer`` ``stage`` or ``stage_paint``).  The total fallback.
   Accepted only when such a render is on record AND the stage is
   unavailable for a reason the server can name AND the link door
   refused for a reason it recorded.  A raw ``openscad`` render is
   inspection-only and is refused; a PNG claim on a host that draws
   the stage is refused and told to open the stage.

The user approves → you call this tool → you pass the returned token as
``preview_token`` to ``start_print`` (or any other tool that starts a
print) or ``fulfillment_order``.  Without a valid token those tools
refuse (unless ``KILN_SKIP_PREVIEW_GATE=1``).  This is the deepest
safety gate that prevents an agent from sending a print to the
physical printer without the user ever seeing what's about to be
printed.

Tokens are single-use and expire after ``ttl_seconds`` (default 600
seconds / 10 minutes).  Scoped to the specific file hash and
optionally to a specific printer_id so a token for one file can't
be reused to approve a different file.

Args:
    file_path: Path to the file to be printed (STL, 3MF, or .gcode).
        Hashed to bind the token to specific bytes.  If the file
        changes between issuing and using the token, the token is
        rejected.
    door: Required: ``"stage"``, ``"url"`` or ``"png"`` — which door the
        user saw the print through; checked against the server's own
        record, and refused when it does not match or is left empty.
    printer_id: Optional printer model ID to scope the token to a
        specific printer.  When set, using the token with a different
        printer will be rejected.
    ttl_seconds: Lifetime of the token (default 600).

Returns:
    Dict with ``token``, ``door``, ``evidence`` and ``expires_at``
    (unix timestamp); or a refusal whose message says which door to
    open and to call this tool again.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "file_path": "<file_path>"
    },
    "name": "issue_preview_token"
  }
}

Input Schema

NameRequiredDescriptionDefault
doorNoRequired: ``"stage"``, ``"url"`` or ``"png"`` — which door the user saw the print through; checked against the server's own record, and refused when it does not match or is left empty. Default: "".
file_pathYesPath to the file to be printed (STL, 3MF, or .gcode). Hashed to bind the token to specific bytes. If the file changes between issuing and using the token, the token is rejected.
printer_idNoOptional printer model ID to scope the token to a specific printer. When set, using the token with a different printer will be rejected.
ttl_secondsNoLifetime of the token (default 600). Default: 600.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv1.5.1
    • changedInput schema / properties / door / description
      Previous value: -"Default: \"\"."New value: +"Required: ``\"stage\"``, ``\"url\"`` or ``\"png\"`` — which door the user saw the print through; checked against the server's own record, and refused when it does not match or is left empty. Default: \"\"."
    • addedInput schema / properties / file_path / description
      Added value: +"Path to the file to be printed (STL, 3MF, or .gcode). Hashed to bind the token to specific bytes.  If the file changes between issuing and using the token, the token is rejected."
    • addedInput schema / properties / printer_id / description
      Added value: +"Optional printer model ID to scope the token to a specific printer.  When set, using the token with a different printer will be rejected."
    • changedInput schema / properties / ttl_seconds / description
      Previous value: -"Default: 600."New value: +"Lifetime of the token (default 600). Default: 600."
  2. Changed4 schema fields changedv1.5.0
    • addedInput schema / properties / door
      Added value: +{
+  "description": "Default: \"\".",
+  "title": "Door",
+  "type": "string"
+}
    • removedInput schema / properties / printer_id / default
      Removed value: -null
    • removedInput schema / properties / ttl_seconds / default
      Removed value: -600
    • addedInput schema / properties / ttl_seconds / description
      Added value: +"Default: 600."
  3. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare readOnlyHint=false / destructiveHint=false / openWorldHint=false; the description adds the real behavioral profile: single-use tokens, 600s default expiry, binding to the file hash and optionally printer_id, and server-side verification of the claimed door rather than trusting the caller. It also discloses what happens on refusal (a message naming which door to open). No contradiction with the annotations — a write to server state is consistent with readOnlyHint=false and non-destructive intent.

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?

Front-loaded with the one-sentence purpose, then the door ladder, then the token lifecycle. Everything is relevant, but the trailing 'Args:' and 'Returns:' blocks duplicate the schema verbatim and the heavy bolding/monospace makes it denser than needed — modest trimming would improve skimmability without losing meaning.

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 safety-gate tool with four parameters and no output schema, the definition covers trigger timing, per-door prerequisites, token scope and expiry, downstream consumption, and the refusal shape and its four returned keys. Nothing an agent needs to call it correctly or recover from a refusal 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% and the schema descriptions largely restate the prose, so the baseline would be 3. The description still adds value by explaining the *decision logic* behind `door` (acceptance conditions per value, why 'stage' is preferred, why a raw openscad PNG is refused) and the invalidation semantics of `file_path` hashing, which the schema only summarizes in one line.

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 specific verb and resource — 'Issue a preview-confirmation token for a file about to be printed' — and immediately establishes its position in the workflow relative to start_print and the stage/viewer tools. An agent can distinguish it from siblings like show_on_stage or may_i_print without opening a 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?

Explicit sequencing ('Call this AFTER the user has seen the print'), a ranked ladder of the three doors with precise acceptance conditions and refusal cases for each, and a named escape hatch (KILN_SKIP_PREVIEW_GATE=1). The description also says what to do with the result — pass the token to start_print or fulfillment_order — closing the loop.

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