Kiln

Overview Schema Source Related Servers Discussions Admin

save_print_checkpoint

Save print checkpoints during an active 3D print to capture known-good Z height, layer, and temperatures for accurate failure detection and resume planning.

Instructions

Save a checkpoint during an active print for accurate resume.

The checkpoint is keyed by ``(printer_name, job_id)`` and read
automatically by :func:`detect_print_failure` so that the resulting
:class:`FailureReport` carries known-good Z / layer / temps.  The
resume planner uses this for accurate ``resume_z_mm`` instead of
estimating from ``z_per_layer * resume_layer`` — meaningfully more
accurate when the print uses variable-layer-height slicing.

Args:
    printer_name: Name of the printer running the job.
    job_id: Unique job identifier.
    z_height: Current Z height in mm.
    layer_number: Current layer number (0-based).
    hotend_temp: Hotend temperature at checkpoint time (Celsius).
    bed_temp: Bed temperature at checkpoint time (Celsius).
    filament_used_mm: Filament consumed so far in mm.
    fan_speed_pct: Part-cooling fan speed (0-100); omitted, 0.
    flow_rate_pct: Flow-rate multiplier in percent; omitted, 100.

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": {
      "printer_name": "<printer_name>",
      "job_id": "<job_id>"
    },
    "name": "save_print_checkpoint"
  }
}

Input Schema

Name	Required	Description
`job_id`	Yes	Unique job identifier.
`bed_temp`	No	Bed temperature at checkpoint time (Celsius).
`z_height`	No	Current Z height in mm.
`hotend_temp`	No	Hotend temperature at checkpoint time (Celsius).
`layer_number`	No	Current layer number (0-based).
`printer_name`	Yes	Name of the printer running the job.
`fan_speed_pct`	No	Part-cooling fan speed (0-100); omitted, 0.
`flow_rate_pct`	No	Flow-rate multiplier in percent; omitted, 100.
`filament_used_mm`	No	Filament consumed so far in mm.

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedv1.5.1Nov 5, 2026
- addedInput schema / properties / bed_temp / description
```
Added value: +"Bed temperature at checkpoint time (Celsius)."
```
- addedInput schema / properties / fan_speed_pct / description
```
Added value: +"Part-cooling fan speed (0-100); omitted, 0."
```
- addedInput schema / properties / filament_used_mm / description
```
Added value: +"Filament consumed so far in mm."
```
- addedInput schema / properties / flow_rate_pct / description
```
Added value: +"Flow-rate multiplier in percent; omitted, 100."
```
- addedInput schema / properties / hotend_temp / description
```
Added value: +"Hotend temperature at checkpoint time (Celsius)."
```
- addedInput schema / properties / job_id / description
```
Added value: +"Unique job identifier."
```
- addedInput schema / properties / layer_number / description
```
Added value: +"Current layer number (0-based)."
```
- addedInput schema / properties / printer_name / description
```
Added value: +"Name of the printer running the job."
```
- addedInput schema / properties / z_height / description
```
Added value: +"Current Z height in mm."
```
Changed7 schema fields changedv1.5.0Oct 23, 2026
- removedInput schema / properties / bed_temp / default
```
Removed value: -null
```
- removedInput schema / properties / fan_speed_pct / default
```
Removed value: -null
```
- removedInput schema / properties / filament_used_mm / default
```
Removed value: -null
```
- removedInput schema / properties / flow_rate_pct / default
```
Removed value: -null
```
- removedInput schema / properties / hotend_temp / default
```
Removed value: -null
```
- removedInput schema / properties / layer_number / default
```
Removed value: -null
```
- removedInput schema / properties / z_height / default
```
Removed value: -null
```
First observedv0.1.0Jul 4, 2026

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, so the mutation/safety profile is covered. Beyond that, the description adds real value: the checkpoint is keyed by (printer_name, job_id), it is consumed automatically by detect_print_failure and the resume planner, and it matters most for variable-layer-height prints. It does not state overwrite semantics or retention, which keeps it from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and the keying rationale are front-loaded and earn their place, but the Args block duplicates nine parameter descriptions already present at 100% coverage in the schema. That is roughly half the text spent on zero marginal information, though nothing is confusingly ordered.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter mutation with no output schema, the description covers purpose, keying, and downstream consumers well, and annotations carry the safety profile. It still leaves gaps an agent would want: what the call returns, whether an existing checkpoint is replaced, and how often it should be saved during a job.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all nine parameters, and the Args block essentially restates those same one-line descriptions plus the defaults (fan 0, flow 100). No additional semantics such as valid ranges or units beyond the schema are introduced, so the baseline 3 applies.

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 ("Save a checkpoint") plus the exact timing constraint ("during an active print") and the benefit ("for accurate resume"). It also names the key tuple (printer_name, job_id), which pins down what makes a checkpoint unique, so it is clearly distinguishable from nearby tools like record_recovery_check or monitor_print.

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

Usage Guidelines3/5

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

The phrase "during an active print" implies the correct window to call it, and the mention that detect_print_failure reads the checkpoint adds useful downstream context. However, it never says what to do if no checkpoint exists, whether repeated calls overwrite, or which sibling (e.g., record_recovery_check, record_recovery_outcome) should be preferred in adjacent scenarios.

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

Deploy Server