Kiln

Overview Schema Source Related Servers Discussions Admin

plan_failure_recovery

Read-only

Generate a recovery plan from a detected print failure ID, including preparation steps, parameter adjustments, and risk assessment.

Instructions

Generate a recovery plan for a previously detected failure.

        Uses the failure ID from a prior ``detect_print_failure`` call
        to look up the failure report and generate an appropriate recovery
        strategy with preparation steps, parameter adjustments, and risk
        assessment.

        **Which recovery tool to use:**

        - Have a printer_name + job_id from a failed print? → ``plan_print_recovery``
        - Have a failure_id from ``detect_print_failure``? → ``plan_failure_recovery`` (this tool)

        With kiln-pro installed the answer can also carry
        ``nozzle_wear_hypothesis`` (Kiln Pro), or below Pro
        ``nozzle_wear_hypothesis_gated``, as for
        ``analyze_print_failure_smart``.

        Picking the print back up where it stopped is offered only on a
        printer model a Kiln-built resume has been shown to work on, and
        only when the half-printed part is still on the plate; otherwise
        the plan is the next safe move and ``plan.not_offered`` says why
        and what to answer.

        Args:
            failure_id: The failure_id from a detect_print_failure result.
            printer_capabilities: Accepted for compatibility and ignored;
                the plan is built from the failure record and the
                printer's own recorded capabilities.
            safety_profile: Accepted for compatibility and ignored; the
                plan reads the printer's own safety profile.
            part_attached: Your word on whether the half-printed part is
                still stuck to the plate (true / false).  Left out, the
                plan asks once before it offers a resume.
            try_untested_resume: Opt this printer in to a resume Kiln has
                not yet seen work on its model; Kiln learns from how it goes.

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": {
      "failure_id": "<failure_id>"
    },
    "name": "plan_failure_recovery"
  }
}

Input Schema

Name	Required	Description
`failure_id`	Yes	The failure_id from a detect_print_failure result.
`part_attached`	No	Your word on whether the half-printed part is still stuck to the plate (true / false). Left out, the plan asks once before it offers a resume.
`safety_profile`	No	Accepted for compatibility and ignored; the plan reads the printer's own safety profile.
`try_untested_resume`	No	Opt this printer in to a resume Kiln has not yet seen work on its model; Kiln learns from how it goes. Default: false.
`printer_capabilities`	No	Accepted for compatibility and ignored; the plan is built from the failure record and the printer's own recorded capabilities.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv1.5.1Nov 5, 2026

addedInput schema / properties / failure_id / description

Added value: +"The failure_id from a detect_print_failure result."

addedInput schema / properties / part_attached

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Your word on whether the half-printed part is still stuck to the plate (true / false).  Left out, the plan asks once before it offers a resume.",
+  "title": "Part Attached"
+}

addedInput schema / properties / printer_capabilities / description

Added value: +"Accepted for compatibility and ignored; the plan is built from the failure record and the printer's own recorded capabilities."

addedInput schema / properties / safety_profile / description

Added value: +"Accepted for compatibility and ignored; the plan reads the printer's own safety profile."

addedInput schema / properties / try_untested_resume

Added value: +{
+  "description": "Opt this printer in to a resume Kiln has not yet seen work on its model; Kiln learns from how it goes. Default: false.",
+  "title": "Try Untested Resume",
+  "type": "boolean"
+}

Changed2 schema fields changedv1.5.0Oct 23, 2026
- removedInput schema / properties / printer_capabilities / default
```
Removed value: -null
```
- removedInput schema / properties / safety_profile / default
```
Removed value: -null
```
First observedv0.1.0Jul 4, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description goes well beyond them: it discloses that two parameters are accepted-and-ignored for compatibility, that resume is gated on printer-model provenance and physical part presence, that an unset part_attached triggers a single clarifying question, and that output may carry nozzle_wear_hypothesis or a gated variant. Since no output schema exists, naming these response fields is genuinely load-bearing information.

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?

Front-loading is good and the bulleted routing section is easy to scan, but the Args block duplicates the input schema nearly verbatim, and the kiln-pro nozzle_wear_hypothesis paragraph is dense and only tangentially relevant to invoking the tool. Roughly a third of the text does not earn its place relative to what the structured fields already provide.

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 five-parameter, non-destructive read tool with no output schema, the description covers selection between sibling planners, prerequisite inputs, ignored compatibility parameters, resume eligibility gating, and the shape of the returned plan including the not_offered explanation. Nothing an agent needs in order to call it correctly and interpret the result is missing.

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 five parameters, and the Args block largely restates those same descriptions. The only marginal addition is the compatibility note that safety_profile and printer_capabilities are ignored in favor of the printer's recorded values, which is already present in the schema text. Baseline 3 is appropriate when the schema does the heavy lifting.

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 description opens with a specific verb and resource ('Generate a recovery plan for a previously detected failure') and then states exactly which input it consumes ('failure ID from a prior detect_print_failure call') and what it produces ('recovery strategy with preparation steps, parameter adjustments, and risk assessment'). The explicit bullet contrast with plan_print_recovery lets an agent distinguish the two recovery planners without opening either 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?

It contains an explicit routing block: printer_name + job_id from a failed print routes to plan_print_recovery, while a failure_id from detect_print_failure routes here. It also states when the resume option will and will not be offered, and points to plan.not_offered as the fallback explanation, so the agent knows both the selection rule and the downstream branch.

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

Deploy Server