Kiln

Overview Schema Source Related Servers Discussions Admin

acquire_printer_lock

Reserve a printer for the current Kiln session to prevent other sessions from commanding it; renew before expiry or let the reservation end automatically.

Instructions

Reserve a printer for this Kiln session, so no other session commands it.

        Every AI app, terminal and bridge on this computer runs its own
        Kiln session.  While this session has the printer reserved, the
        others can still check its status and camera and send an
        emergency stop, but their other commands to it are refused, naming
        who reserved it.  The reservation ends when it is released, when
        ``hold_minutes`` run out, or when this session exits; call again to
        renew it.  It never lets anyone use a printer their plan would not
        (one printer at a time below Kiln Business).

        Args:
            printer_name: Printer to reserve.
            holder: A name for who reserved it (for example the app),
                shown to the sessions that are refused.
            hold_minutes: How long it lasts (1 to 1440, default 30).
            timeout_seconds: How long to wait if another session has it
                (default 0: answer at once with who has it; at most 120).

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_name": "<printer_name>"
    },
    "name": "acquire_printer_lock"
  }
}

Input Schema

Name	Required	Description
`holder`	No	A name for who reserved it (for example the app), shown to the sessions that are refused. Default: "".
`hold_minutes`	No	How long it lasts (1 to 1440, default 30). Default: 30.0.
`printer_name`	Yes	Printer to reserve.
`timeout_seconds`	No	How long to wait if another session has it (default 0: answer at once with who has it; at most 120). Default: 0.0.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv1.5.1Nov 5, 2026

addedInput schema / properties / hold_minutes

Added value: +{
+  "description": "How long it lasts (1 to 1440, default 30). Default: 30.0.",
+  "title": "Hold Minutes",
+  "type": "number"
+}

changedInput schema / properties / holder / description

Previous value: -"Default: \"agent\"."New value: +"A name for who reserved it (for example the app), shown to the sessions that are refused. Default: \"\"."

addedInput schema / properties / printer_name / description
```
Added value: +"Printer to reserve."
```

changedInput schema / properties / timeout_seconds / description

Previous value: -"Default: 30.0."New value: +"How long to wait if another session has it (default 0: answer at once with who has it; at most 120). Default: 0.0."

Changed4 schema fields changedv1.5.0Oct 23, 2026
- removedInput schema / properties / holder / default
```
Removed value: -"agent"
```
- addedInput schema / properties / holder / description
```
Added value: +"Default: \"agent\"."
```
- removedInput schema / properties / timeout_seconds / default
```
Removed value: -30
```
- addedInput schema / properties / timeout_seconds / description
```
Added value: +"Default: 30.0."
```
First observedv0.1.0Jul 4, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false) it discloses the effects that matter: the other sessions' commands are refused and the refusal names the reserver, status/camera/estop stay permitted, and the lock ends on release, expiry of hold_minutes, or session exit. It also discloses plan-based constraints (one printer at a time below Kiln Business) and the contention behavior governed by timeout_seconds.

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?

The headline sentence is front-loaded and immediately actionable, and the following prose is organized as scope, lifetime, limits, then Args. It is a bit verbose with wrapped, run-on lines, but no sentence is pure filler.

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 four-parameter mutating lock tool with no output schema, the description covers lifetime, contention, plan restrictions, and cross-session consequences, which is essentially everything an agent needs to call it correctly. Return-value details are unnecessary since success is implied by acquisition and failure surfaces who holds the lock.

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 each parameter is already documented, and the Args block largely restates the schema text for printer_name, holder, hold_minutes and timeout_seconds. The description adds little new syntax or edge-case detail (e.g. what happens on timeout expiry other than the default behaviour), so the baseline of 3 is right.

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 states a specific verb and resource ('Reserve a printer for this Kiln session') plus the scope of exclusivity ('so no other session commands it'). That phrasing distinguishes it cleanly from the sibling release_printer_lock and from status/camera tools, without needing to open any schema.

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 gives real when-to-use context: the reservation is per session, other sessions are denied other commands while it holds, and it must be re-acquired to renew. It also implies a when-not case by noting that status, camera and emergency stop remain available without the lock. It never names release_printer_lock or hand_back_printer as the way to end the reservation, leaving the counterpart tool implicit.

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

Deploy Server