Skip to main content
Glama
Sign In
Kiln

Kiln

by codeofaxel
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

record_nozzle_replacement

Destructive

Records a nozzle replacement event with printer ID, reason, and new material so you can track why each nozzle was swapped and keep wear history accurate.

Instructions

Pro+ — record a nozzle replacement event with the WHY.

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_id": "<printer_id>",
      "reason": "<reason>",
      "new_material": "<new_material>"
    },
    "name": "record_nozzle_replacement"
  }
}

Input Schema

NameRequiredDescriptionDefault
reasonYesOne of ``worn_out`` / ``damaged`` / ``upgraded`` / ``downgraded`` / ``diameter_change`` / ``preventive`` / ``experimental`` / ``other``. Missing / invalid → returns ``code=WHY_REQUIRED`` with the allowed list and one example sentence per reason.
printer_idYesStable printer identifier.
install_dateNoISO 8601 date string for the install event. Defaults to today.
new_materialYesMaterial of the nozzle going in: ``brass``, ``stainless_steel``, ``hardened_steel``, ``ruby_tip``, ``cht_brass``, ``cht_hardened``, ``tungsten_carbide`` or ``custom`` (case-insensitive), or ``unknown`` when nobody knows; anything else is refused.
printer_modelNoResolved printer model key (e.g. "bambu_a1") for cohort bucketing. Falls through to an empty string when the agent can't resolve from the user's printer registry. Default: "".
reason_detailNoOptional free-text "tell me more" that the agent should elicit alongside the reason. REQUIRED when ``reason == "other"``. Default: "".
client_event_idNoA stable id the caller assigns to this swap, used as the replacement event's id so a retried call names the same event. Empty, Kiln uses the lifecycle entry's own id, or mints one. Default: "".
failure_subtypeNoFor ``reason="worn_out"``: which part of the nozzle failed — ``tip`` (orifice wear, drift in dimensions), ``bore`` (melt-zone wear, uneven flow), ``both``, or ``other`` (a failure outside that split: diameter sag, body crack). Omitted, the event records no sub-type. Pass the ``replacement_recommendation`` an earlier ``nozzle_wear_status`` or ``check_nozzle_capacity_for_print`` answer gave when you have one.
new_diameter_mmNoDiameter in mm (optional, falls back to whatever the previous nozzle was).
printer_readingNoWhat the printer itself reports as its nozzle, filled in by the caller's own Kiln when it can reach the machine, so the answer can say whether the printer agrees with the new record. Used only where this process cannot read the printer; leave it unset by hand.
filament_materialNoThe filament that wore the nozzle out (e.g. ``"PETG-CF"``, ``"PLA"``). Given, the event also feeds the anonymous community wear baseline; omit it when unknown and the event is still recorded. Default: "".
previous_materialNoThe nozzle that came OUT, when the caller knows it. Wins over whatever the stored record holds — the caller is the only party that watched the swap. Pass it whenever the record may already have been updated, and always when this call follows a ``set_nozzle_state``. When it disagrees with the record, the stored wear counters belong to a different nozzle and are dropped rather than recorded against this one. Default: "".
previous_diameter_mmNoDiameter of the outgoing nozzle. Only meaningful alongside *previous_material*; defaults to whatever the record held.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.5.1

TDQS

C2.6/5.0
Behavior2/5

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

Annotations already flag destructiveHint=true and readOnlyHint=false, so the mutation profile is known; the description contributes only the Pro+ tier requirement. It says nothing about what gets overwritten, that disagreeing previous_material drops stored wear counters, or that missing/invalid reason returns WHY_REQUIRED — despite these being the traits an agent most needs at selection time.

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?

A single short clause, front-loaded with the tier marker and the verb. It wastes no words, though the terseness crosses into under-specification rather than tight writing.

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

Completeness2/5

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

For a 13-parameter destructive write with tier gating, no output schema, and critical interactions with nozzle state and wear counters, one clause is not enough to support correct selection. The rich schema descriptions partly compensate, but the description itself leaves behavior and sibling routing unexplained.

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 every parameter already carries its allowed values and defaults, which sets the baseline at 3. The description adds only the emphasis that the reason (WHY) is central, which the schema already enforces as required, so little meaning is added.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a concrete verb and resource ("record a nozzle replacement event") and adds the tier gate ("Pro+"), so the basic action is legible. It does not distinguish this from close siblings such as set_nozzle_state, record_cutter_replacement, or nozzle_wear_status, leaving the agent to infer boundaries.

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

Usage Guidelines2/5

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

There is no when-to-use or when-not-to-use guidance. "with the WHY" hints that a reason is mandatory but never says when an agent should record a swap rather than call set_nozzle_state, or how this relates to nozzle_wear_status recommendations. The Prerequisite/alternative routing an agent needs is absent.

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