Skip to main content
Glama
Sign In
JEFF7712

nix-agent

by JEFF7712
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

build

Starts a persistent background NixOS or Home Manager closure compilation without activation and returns a job ID for polling status and new log output.

Instructions

Start a persistent background build of the system/HM closure, without activation. Returns job_id promptly. Poll build(job_id=...) for bounded live log tails and status: running, ok, failed, or interrupted. Pass the previous poll's log_offset to receive only new stderr. Jobs survive MCP disconnects and server restarts; repeated starts for the same running target reuse its job. On success returns store_path; successful output is a short tail with log_truncated and full local log_paths. on build failure includes failed_derivation{drv, log_tail} when available.

Input Schema

NameRequiredDescriptionDefault
modeNonixos
job_idNo
flake_uriNo
log_offsetNo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.14.0
    • addedInput schema / properties / log_offset
      Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}
  2. Changed1 schema field changedv0.13.0
    • addedInput schema / properties / job_id
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}
  3. Addedv0.5.0

TDQS

A4.3/5.0
Behavior5/5

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

With no annotations provided, the description carries the full behavioral burden and does so well: jobs survive MCP disconnects and server restarts, polling returns bounded log tails, success includes store_path and truncated log details, and failures include failed_derivation when available. These are concrete operational traits beyond the schema.

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 description is dense but well front-loaded, starting with the core action and then describing polling and return behavior. It is longer than ideal, but most sentences carry useful operational detail.

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 no-annotation tool with an output schema, the description covers the important lifecycle and return behavior: job_id, polling statuses, persistence, log offsets, success store_path, and failure derivation data. The main gap is that mode and flake_uri are not explained, which matters because schema coverage is 0%.

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 0%, so the description must compensate for all four parameters. It explains job_id and log_offset behavior clearly, but does not explain mode or flake_uri semantics, leaving half the parameters underspecified.

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 description gives a specific verb and resource: start a persistent background build of the system/HM closure. It also scopes the operation by stating 'without activation,' which implicitly distinguishes it from the activation-oriented sibling switch.

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 clearly explains the start-then-poll workflow, including passing job_id to build and using the previous poll's log_offset. It also states that repeated starts for the same running target reuse the job, but it does not explicitly name when to use sibling tools like check or switch instead.

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