Source: https://spooly.eu/en/docs/ai/tools

# Tool reference

All 23 tools of the MCP server, sorted by topic. They return the same data as the REST API.

## For all tools

- Tools that change something need the permission to change. They also take an optional `request_id`: with the same ID, a retry runs only once.
- Lists return `total`, and the AI pages through with `limit` and `offset`.
- Weights are in grams, costs in the currency from `get_account`.
- Spool names, notes and printer names are data. Spooly tells the AI not to follow instructions inside them.

## Account

| Tool | What it does | Parameters |
| --- | --- | --- |
| `get_account` | Account type (Pro or Trial), calls today, daily limit, key name and currency | None |
| `get_attention` | What is due today: maintenance due, number of prints waiting for review, and low spools | None |

## Spools

| Tool | What it does | Parameters |
| --- | --- | --- |
| `list_spools` | Spools by number, with remaining weight, size and warning level | `limit` 1 to 500, default 100; `offset`; `archived` default false |
| `get_spool` | One spool | `spool_id`: the `id` from `list_spools`, not the spool number |
| `create_spool` changes | Creates a spool. Without a remaining weight it is full. | Required in `spool`: `color_hex` as #RRGGBB, `material` (with its variant, such as PLA Basic), `spool_size_grams`. Optional: `name`, `color_name`, `manufacturer`, `finish`, `remaining_grams`, `empty_spool_grams`, `price`, `notes`, `location_id` and with it `place`. The names are the same as in `list_spools`. |
| `update_spool` changes | Changes the fields sent for a spool. Weight goes through `set_spool_weight` and `refill_spool`. | `spool_id`, `changes`: the same fields as when creating, without remaining weight, so `color_hex`, `material`, `spool_size_grams`, `name`, `color_name`, `manufacturer`, `finish`, `empty_spool_grams`, `price`, `notes`, `location_id`, `place` |
| `set_spool_weight` changes | Sets the remaining weight. 0 g archives the spool, as in the app. | `spool_id` and exactly one of: `grams` 0 to 20,000 or `gross_grams` 0 to 40,000 |
| `refill_spool` changes | Adds grams. The result must not exceed the spool size. | `spool_id`, `grams` above 0 up to 20,000 |
| `archive_spool` changes | Archives a spool, its print history stays. Not possible during a running print. | `spool_id` |
| `restore_spool` changes | Brings an archived spool back. | `spool_id` |
| `move_spool` changes | Puts a spool into a storage location. | `spool_id`, `location_id`; null takes it out of the location; optional `place` for a place |

## Slots

| Tool | What it does | Parameters |
| --- | --- | --- |
| `get_slots` | Which spool sits in which slot, for example in the AMS or the ACE | None |
| `assign_slot` changes | Puts a spool into a slot. Only with the slot autopilot active. If the printer reports a different color, the call fails with `andere_farbe`. | `slot_id`, `spool_id`, `confirm_color` |
| `clear_slot` changes | Empties a slot. The spool stays in Spooly. | `slot_id` |

## Storage locations

| Tool | What it does | Parameters |
| --- | --- | --- |
| `list_locations` | Storage locations with ID, path and number of places, for `move_spool` | None |

## Prints

| Tool | What it does | Parameters |
| --- | --- | --- |
| `list_prints` | Prints, newest first, with duration, grams per spool and material cost | `limit` 1 to 200, default 100; `offset` |

## Printers

| Tool | What it does | Parameters |
| --- | --- | --- |
| `list_printers` | All printers. Online and offline only with a reliable signal, otherwise `unknown`. Progress and remaining time only for Bambu Lab. | None |
| `set_printer_hours` changes | Sets the total hours to the number on the device. Due dates do not jump. Less than the hours Spooly has recorded is not possible. | `printer_id`, `total_hours` 0 to 1,000,000 |

## Maintenance

| Tool | What it does | Parameters |
| --- | --- | --- |
| `get_maintenance` | Maintenance book: printers with hours, tasks with status, remaining amount and an estimate in days. Device errors and AMS humidity only concern Bambu Lab. | None |
| `list_maintenance_log` | Maintenance history, newest first | `task_id`, `printer_id`, `limit` 1 to 200, default 50; `offset` |
| `complete_maintenance` changes | Marks a maintenance as done, only when you said so. The counter starts over and parts are deducted from stock. This does not create a new nozzle or plate. | `task_id`, `action` (`replace`, `clean`, `check`), `notes` up to 1,000 characters |
| `snooze_maintenance` changes | Reminds you about a maintenance later. | `task_id`, `days` 7, 14 or 30, `reason` up to 200 characters |

## Statistics

| Tool | What it does | Parameters |
| --- | --- | --- |
| `get_statistics` | Prints, failed prints, grams, hours, filament cost, the equally long period before, materials, printers, most used spools and stock value. Months follow the time zone of the account. | `year` 2000 to 2100, `month` 1 to 12. Without them, everything. |