Skip to main content
Glama
Sign In
Kiln

Kiln

by codeofaxel
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

trim_serve_processes

Destructive

Close leftover Kiln servers left by closed agent sessions to reclaim memory, keeping active sessions and blocking cleanup while a print is in progress.

Instructions

Close leftover Kiln servers left behind by closed sessions.

        Every agent session spawns its own background Kiln server;
        client apps don't reliably close them when a session ends, so
        they accumulate and quietly hold memory. This is the cleanup
        the pile-up warning (health_check / kiln_health / get_started)
        offers.

        WHY THIS IS SAFE: closing a server never stops a physical
        print — the printer keeps going regardless. What a close can
        end is MONITORING (a running watch loop). So this refuses to
        act while any printer has a job in flight, and otherwise the
        worst case is that a still-open session reconnects. This
        session's own server is never closed.

        AGENT CONTRACT (important):
          * ASK THE USER how many agent sessions they actually have
            open right now and pass it as open_sessions — they are
            the one source of truth for that, and it beats guessing
            from process age. Never ask them for a PID.
          * Confirm before acting. Called without confirm, this
            returns the plan (how many would close, how many stay)
            to show the user; pass confirm=True once they agree.
          * If it comes back blocked because something is printing,
            tell the user what's printing and leave it alone — offer
            to clean up after the print finishes rather than
            reaching for force.

        Args:
            confirm: Set True to actually close the leftovers.
            open_sessions: The user's own count of agent sessions
                currently open. Keeps that many most-recently-started
                servers and proposes the rest.
            force: Proceed even though a printer has a job in flight.
                Only when the user explicitly insists, knowing that
                monitoring for that job may stop.

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

Input Schema

NameRequiredDescriptionDefault
forceNoProceed even though a printer has a job in flight. Only when the user explicitly insists, knowing that monitoring for that job may stop. Default: false.
confirmNoSet True to actually close the leftovers. Default: false.
open_sessionsNoThe user's own count of agent sessions currently open. Keeps that many most-recently-started servers and proposes the rest.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv1.5.1
    • changedInput schema / properties / confirm / description
      Previous value: -"Default: false."New value: +"Set True to actually close the leftovers. Default: false."
    • changedInput schema / properties / force / description
      Previous value: -"Default: false."New value: +"Proceed even though a printer has a job in flight. Only when the user explicitly insists, knowing that monitoring for that job may stop. Default: false."
    • addedInput schema / properties / open_sessions / description
      Added value: +"The user's own count of agent sessions currently open. Keeps that many most-recently-started servers and proposes the rest."
  2. Changed5 schema fields changedv1.5.0
    • removedInput schema / properties / confirm / default
      Removed value: -false
    • addedInput schema / properties / confirm / description
      Added value: +"Default: false."
    • removedInput schema / properties / force / default
      Removed value: -false
    • addedInput schema / properties / force / description
      Added value: +"Default: false."
    • removedInput schema / properties / open_sessions / default
      Removed value: -null
  3. Addedv1.3.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description goes far beyond that: it explains the real blast radius (physical prints continue; only a watch loop can be lost), the guard that refuses action while a job is in flight, the guarantee that the current session's own server is never closed, and the dry-run-until-confirm behavior. That is exactly the context an agent needs before calling a destructive 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 one-line purpose, then rationale, safety, and an explicit agent contract with labeled sections and bullets. It is long, and the WHY-THIS-IS-SAFE block repeats guard behavior covered by the force parameter, but for a destructive process-cleanup tool nearly every sentence carries decision-relevant information.

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?

Complete for a destructive cleanup tool with three optional parameters and no output schema: the description supplies the pre-call protocol, the blocked-state handling, the retention policy, and the return-the-plan-without-confirm behavior. No output schema is present, yet the description still explains what a non-confirmed call yields, which is sufficient.

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 operational meaning the schema cannot: open_sessions is framed as the user's authoritative count rather than a guess from process age, and the keep-newest/propose-the-rest retention rule is spelled out. The confirm and force text largely mirrors the schema descriptions, which keeps this from a 5.

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?

States a specific verb and resource — closing leftover Kiln server processes orphaned by ended sessions — and explains the mechanism that creates them (each session spawns its own background server). This is clearly distinguishable from the many printing and health-check siblings; nothing in the sibling list does process cleanup.

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?

Explicitly ties invocation to a trigger (the pile-up warning surfaced by health_check / kiln_health / get_started), names the alternative behaviors to avoid (never reach for force after a blocked result; offer to clean up later instead), and mandates a confirm-then-act flow. It also says what to ask the user and what never to ask (a PID).

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