Skip to main content
Glama
Sign In
Kiln

Kiln

by codeofaxel
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

unload_filament

Destructive

Pull filament out of the hotend: returns it to the AMS on Bambu printers or heats and retracts on Klipper, readying the nozzle for the next material.

Instructions

Pull filament out of the hotend — back into the AMS on Bambu, a heated retract elsewhere.

Same temperature gate, verification, ``outcome`` vocabulary and wait
bound as ``load_filament``: on Bambu ``extrusion_verified`` is ``True``
once the AMS reports no tray feeding the nozzle (``tray_now`` 255); on
Klipper an ``UNLOAD_FILAMENT`` / ``M702`` macro is used when the config
has one; otherwise the hotend is heated and ``length_mm`` is retracted
(default 80).

Args:
    material: e.g. ``"PLA"`` -- picks a temperature when none is given
        and no spool report supplies one, as ``load_filament``.
    temperature: Hotend target in °C.  Omit to use the middle of the
        spool's or material's window.
    length_mm: Retract distance for the generic G-code path (default
        80).  Ignored where the firmware's own routine decides.
    wait_seconds: How long to watch for the AMS to confirm, bounded as
        in ``load_filament``.
    keep_hot: Leave the heater ON afterwards.  Off by default: unload
        never retracts at the end (the filament is already out) but
        still turns the heater off unless this asks otherwise.
    printer_name: Which printer.  Omit for the default one.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "unload_filament"
  }
}

Input Schema

NameRequiredDescriptionDefault
keep_hotNoLeave the heater ON afterwards. Off by default: unload never retracts at the end (the filament is already out) but still turns the heater off unless this asks otherwise. Default: false.
materialNoe.g. ``"PLA"`` -- picks a temperature when none is given and no spool report supplies one, as ``load_filament``.
length_mmNoRetract distance for the generic G-code path (default 80). Ignored where the firmware's own routine decides.
temperatureNoHotend target in °C. Omit to use the middle of the spool's or material's window.
printer_nameNoWhich printer. Omit for the default one.
wait_secondsNoHow long to watch for the AMS to confirm, bounded as in ``load_filament``.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv1.5.1
    • changedInput schema / properties / keep_hot / description
      Previous value: -"Default: false."New value: +"Leave the heater ON afterwards.  Off by default: unload never retracts at the end (the filament is already out) but still turns the heater off unless this asks otherwise. Default: false."
    • addedInput schema / properties / length_mm / description
      Added value: +"Retract distance for the generic G-code path (default 80).  Ignored where the firmware's own routine decides."
    • addedInput schema / properties / material / description
      Added value: +"e.g. ``\"PLA\"`` -- picks a temperature when none is given and no spool report supplies one, as ``load_filament``."
    • addedInput schema / properties / printer_name / description
      Added value: +"Which printer.  Omit for the default one."
    • addedInput schema / properties / temperature / description
      Added value: +"Hotend target in °C.  Omit to use the middle of the spool's or material's window."
    • addedInput schema / properties / wait_seconds / description
      Added value: +"How long to watch for the AMS to confirm, bounded as in ``load_filament``."
  2. Addedv1.5.0

TDQS

A4.1/5.0
Behavior4/5

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

Annotations declare destructiveHint=true and readOnlyHint=false; the description goes beyond them by disclosing the temperature gate, the AMS verification signal (extrusion_verified / tray_now 255), the macro alternate path, and that the heater shuts off afterward unless keep_hot is set. It omits failure behavior (e.g. no filament present, gate timeout), which keeps it short of 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.

Conciseness4/5

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

Front-loaded with the one-line purpose, then platform detail, then Args. The Args section duplicates the schema descriptions, which is mild waste but the overall length is proportionate to a six-parameter hardware tool.

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

Completeness4/5

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

No output schema and all six parameters optional, so the description carries the behavioral burden and does so well. The main gap is deferring the 'outcome' vocabulary and wait bound to load_filament rather than restating them, forcing a cross-tool lookup.

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% and the Args block largely restates the schema text, so little new meaning is added. The one useful addition is that length_mm is ignored when a firmware routine decides the retract, but that is also in the schema.

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?

The first sentence names a concrete verb and resource plus platform-specific behavior ('Pull filament out of the hotend — back into the AMS on Bambu, a heated retract elsewhere'), which distinguishes it immediately from load_filament and purge_filament in the sibling list.

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

Usage Guidelines4/5

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

It routes behavior by machine type (AMS tray_now path on Bambu, UNLOAD_FILAMENT/M702 on Klipper, generic G-code retract otherwise) and anchors itself to load_filament for shared semantics, but it never states explicit when-not conditions or contrasts with purge_filament.

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