Kiln

Overview Schema Source Related Servers Discussions Admin

add_spool

Destructive

Add a filament spool to Kiln inventory or correct the remaining grams on a recorded spool so print usage counts match what is actually left.

Instructions

Add a filament spool to inventory, or correct how much is left on one.

To ADD a spool, give its ``material``.  ``remaining_grams`` is what is
left on a spool that is not new; left out, the spool is full.

To CORRECT a spool already on record, pass its ``spool_id`` (from
``list_spools``) with ``remaining_grams``: the person says they have
more left than Kiln shows, or less.  Only the amount changes.  Kiln
counts a spool down as the prints it starts use it, and a count drifts,
so the person's word wins.  ``remaining_grams=0`` records the spool as
used up and keeps it on the list; ``remove_spool`` takes it off.

Args:
    material: Material type (PLA, PETG, ABS, etc.).  Required to add.
    color: Filament color.
    brand: Manufacturer brand.
    weight_grams: Total spool weight in grams (default 1000).
    cost_usd: Cost of the spool in USD.
    remaining_grams: Grams left on the spool.
    spool_id: A spool already on record whose remaining amount to set.

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": "add_spool"
  }
}

Input Schema

Name	Required	Description
`brand`	No	Manufacturer brand.
`color`	No	Filament color.
`cost_usd`	No	Cost of the spool in USD.
`material`	No	Material type (PLA, PETG, ABS, etc.). Required to add.
`spool_id`	No	A spool already on record whose remaining amount to set.
`weight_grams`	No	Total spool weight in grams (default 1000). Default: 1000.0.
`remaining_grams`	No	Grams left on the spool.

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedv1.5.1Nov 5, 2026
- addedInput schema / properties / brand / description
```
Added value: +"Manufacturer brand."
```
- addedInput schema / properties / color / description
```
Added value: +"Filament color."
```
- addedInput schema / properties / cost_usd / description
```
Added value: +"Cost of the spool in USD."
```
- addedInput schema / properties / material / description
```
Added value: +"Material type (PLA, PETG, ABS, etc.).  Required to add."
```
- addedInput schema / properties / remaining_grams / description
```
Added value: +"Grams left on the spool."
```
- addedInput schema / properties / spool_id / description
```
Added value: +"A spool already on record whose remaining amount to set."
```
- changedInput schema / properties / weight_grams / description
```
Previous value: -"Default: 1000.0."New value: +"Total spool weight in grams (default 1000). Default: 1000.0."
```

Changed10 schema fields changedv1.5.0Oct 23, 2026

removedInput schema / properties / brand / default
```
Removed value: -null
```
removedInput schema / properties / color / default
```
Removed value: -null
```
removedInput schema / properties / cost_usd / default
```
Removed value: -null
```

addedInput schema / properties / material / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedInput schema / properties / material / type
```
Removed value: -"string"
```

addedInput schema / properties / remaining_grams

Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "title": "Remaining Grams"
+}

addedInput schema / properties / spool_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "title": "Spool Id"
+}

removedInput schema / properties / weight_grams / default
```
Removed value: -1000
```
addedInput schema / properties / weight_grams / description
```
Added value: +"Default: 1000.0."
```
removedInput schema / required
```
Removed value: -[
-  "material"
-]
```

First observedv0.1.0Jul 4, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already flag destructiveHint=true and readOnlyHint=false; the description earns credit by disclosing what is actually overwritten (only the amount changes on a correction), what zero means (used up but retained), and the drift rationale. It does not say what happens if both material and spool_id are supplied, nor whether any permission or validation gates apply, which is why it falls short of a 5 for a mutation tool.

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 two-mode summary, then per-mode paragraphs, with the Args block last. The Args block largely duplicates the schema descriptions verbatim at 100% coverage, which is redundant, but the surrounding prose is dense and every earlier sentence carries new information.

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?

For a 7-parameter, zero-required mutation tool with no output schema, the description covers both invocation paths, defaults, the zero-value edge case, and the sibling alternative. What it leaves out is conflict handling between modes and whether the call returns the created or updated spool.

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%, so the baseline is 3, but the description adds conditional semantics the schema cannot express: material is required only in add mode, spool_id is required only in correct mode, and an omitted remaining_grams means a full spool. The remaining gap is the unaddressed interaction of the optional descriptive fields (brand, color, cost_usd) when correcting an existing spool.

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 both operations precisely — adding a spool to inventory and correcting the remaining amount on an existing one — and each mode is then restated with the parameters that select it. It also names the sibling tools that frame the boundary (list_spools for the id, remove_spool for taking a spool off the list), so an agent can distinguish it from neighbors without reading schemas.

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 when-to-use for both branches: give material to add, give spool_id plus remaining_grams to correct. It states the exclusion case (remove_spool takes it off the list, this does not) and even explains the decision rule — a drifted count loses to the person's stated amount.

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

Deploy Server