puppet_server

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

With no annotations, the description carries the full burden and does well: it discloses that start is redundant due to autostart, that idle shutdown happens automatically after idle_stop_min, that stop returns a token-savings report, and that settings are fixed in a toml file rather than passed in. It does not explain what restart actually does operationally (whether it re-reads the toml, whether in-flight work is lost) or what happens if the server is not running.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the verb and resource, then the operational warning, then the usage conditions. Every clause carries information — config location, autostart, idle timeout, token reporting, memory pressure — with no filler or restatement of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter lifecycle tool with no output schema and no annotations, the description covers the config source, autostart interplay, idle shutdown, and stop's reporting behavior — close to everything an agent needs. The remaining gap is restart's behavior and any failure/precondition handling, which matters because restart is one of only three available actions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the single parameter is a self-documenting enum, so the description only needs to add routing meaning. It does so for start (avoid it) and stop (when and why), but the restart value is named in the opening line and never given any semantics or usage condition, leaving one of three enum values explained only by its name.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States specific verbs (start/stop/restart) against a specific resource (the local Flint llama-server) and names the fixed config source (~/.puppet-master/server.toml). This is clearly distinguishable from siblings like puppet_read, puppet_write, or puppet_apply, which operate on Puppet resources rather than on the server process itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-not guidance ("Never call start first: every Flint tool autostarts it, and it stops itself after idle_stop_min") plus three concrete when-to-use conditions for stop: after finishing delegated work, when the user needs RAM back, and before memory-heavy commands like compiling. That is about as close to an explicit decision rule as a single-param tool gets.

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