nix-agent

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.

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.

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.

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.

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.

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.

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

No annotations exist, so the description carries the full burden and does disclose real behavior: which linters run, that lint returns a structured findings list, that dry-build/dry-activate are non-mutating previews, the tail-with-log_truncated plus local log_paths on success, and capped diagnostics on failure. It omits any mention of permissions or how long a dry-build may take, keeping it short of a 5.

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?

One dense paragraph that leads with the tool's core purpose and then ordered level detail; every sentence adds information. It is somewhat long but not padded, and the output-behavior sentence earns its place given absent annotations.

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?

Covers purpose, level semantics, platform restriction, and success/failure output shape for a three-parameter tool with no annotations. The main gap is the silent treatment of 'mode' and 'flake_uri'; the output schema existing means return values need not be elaborated, so the added output note is a bonus rather than a necessity.

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% and there are no enums, yet the description supplies the critical semantics for 'level' by naming and explaining each of its three values. It says nothing about 'mode' (which defaults to nixos) or 'flake_uri', leaving two of three parameters undocumented in both schema and description.

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 a specific action (validation of the configuration) and enumerates the three levels with concrete meaning: lint runs statix+deadnix, dry-build evaluates/plans the closure, dry-activate shows activation changes. It distinguishes the levels clearly but does not distinguish this tool from siblings like build or eval_config, which overlap in scope.

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?

The 'fast to slow' ladder framing gives clear guidance on choosing a level (lint for quick checks, dry-build for closure evaluation, dry-activate for NixOS activation preview). However, there is no explicit statement of when to prefer this tool over siblings such as build, switch, or eval_config, and the NixOS-only restriction on dry-activate is only implied for the other levels.

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

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

With no annotations provided, the description carries the full burden and discloses the key side effect: it switches by default unless the user asked only to preview or check. It also explains the fallback diff mechanism (nvd, then nix store diff-closures) and when raw diff text is returned instead of structured packages.

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?

The description is front-loaded with the core action and output shape, then covers default switching and the fleet alternative. It is dense but every sentence carries operational information; the parenthetical fallback detail is useful rather than redundant.

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?

An output schema exists, so the description need not explain return values, and it does explain side effects and fallback output behavior. However, for a tool with two undocumented parameters at 0% schema coverage, the description leaves a meaningful gap about how mode and flake_uri control the closure being built and diffed.

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%, and the description never mentions the two parameters, mode or flake_uri, nor explains how they affect the build or diff. Because parameter coverage is low, the description should compensate, but here it adds no parameter meaning beyond the schema's bare property names.

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?

The description states a specific verb and resource: build the new closure and diff it against the running system, with structured package changes and closure_size. It also distinguishes the tool from preview/check behavior and fleet deployment via the orchestrator, so an agent can identify its role among siblings.

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?

It gives explicit default behavior ('Include the changeset in the reply and switch unless the user asked only to preview or check') and names the alternative for coordinated fleet deployment. This covers when to use it, when to avoid switching, and when to use a different orchestration path.

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

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

With no annotations, the description carries the full burden and discloses substantial behavior: flake_uri/mode auto-resolution, batching multiple attrs into one call, per-attr results with failed_count/succeeded_count, status='partial'/'failed' semantics, and truncation via a size guard (truncated: true with a hint). It still omits cost/latency of `nix eval`, and read-only status is only implied.

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 core action and an example, then a compact sequence of behavioral facts (batching, status, truncation). Dense but every sentence adds an actionable detail; no filler or repetition.

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?

An output schema exists, so return-shape explanation is optional, yet the description still covers batch result fields, partial/failed status, and truncation — good coverage for a batch-capable eval tool. The remaining gap is the unexplained `mode` parameter and the absence of any guidance about evaluation cost.

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%, so the description must compensate. It does explain that `attr` accepts a single string or a list (batch), and that `flake_uri` and `mode` auto-resolve when omitted, which is meaningful beyond the schema. However, it never says what `mode` values mean (nixos vs. home-manager or similar), leaving one of three parameters semantically opaque.

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 a specific verb + resource: evaluate the final merged value of an attribute in the user's actual NixOS/Home Manager config via `nix eval`, with a concrete example (attr='services.openssh.enable'). This clearly distinguishes it from siblings like `locate_option` (find an option) or `check`/`build`/`switch` (act on the system).

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?

Usage is only implied: 'the user's actual ... configuration' suggests reading real merged state, but there is no explicit when-to-use vs. when-to-use-an-alternative guidance (e.g. use this instead of locate_option to see the resolved value). No exclusions or prerequisites are stated.

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

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

With no annotations, the description carries full responsibility for behavioral disclosure. It details that list includes dates and current marker, NixOS entries include path when profile link exists, and rollback can target a specific generation or default to previous. This goes beyond a bare function statement.

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?

The description is concise and front-loaded, using a single paragraph with action-oriented sentences. Every sentence contributes meaningful information without redundancy or fluff.

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?

Given the tool's complexity and the existence of an output schema, the description covers the main use cases adequately. It explains both list and rollback behaviors and parameter options. However, it omits potential edge cases like error handling or destructive consequences, but the core functionality is well documented.

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%, so the description must compensate. It thoroughly explains the meaning and usage of all three parameters: 'action' values, 'generation' as id/path, and 'mode' for home-manager. This fully clarifies the parameter semantics.

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?

The description clearly states the tool performs two specific actions: listing generations and rolling back to a previous generation. It provides distinct verbs and resources, distinguishing it from sibling tools like build, switch, and diff, which handle other operations.

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?

The description implies usage by defining the two actions and explaining when to use each (list to enumerate, rollback to revert). However, it does not explicitly compare to sibling tools or state when NOT to use this tool, leaving the selection guidance implicit.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool returns files declaring and defining an option with contributed values, which is the primary behavior. It does not mention side effects (none expected) or permissions, but given the read-only nature implied (locating, not modifying), this is adequate.

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?

The description is extremely concise: two sentences and one parenthetical example. It is front-loaded with the main purpose and provides an example immediately. Every sentence adds value, with no wasted words.

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?

Given the tool has 3 parameters, 1 required, and an output schema exists, the description covers the 'attr' parameter and return values implicitly. However, it omits 'mode' and 'flake_uri', which are important for context (e.g., NixOS vs Home Manager mode). The Home Manager mention partially addresses this but not fully.

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 coverage is 0%, so the description must add meaning. It only explains the 'attr' parameter with an example and a special Home Manager syntax. The 'mode' and 'flake_uri' parameters are not mentioned, leaving their semantics undocumented. Thus, it only partially compensates for the lack of schema descriptions.

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?

The description clearly states the tool locates where a configuration option is set, listing files and contributed values. It uses a specific verb ('locate') and resource ('option'), and the example attr='services.openssh.enable' clarifies the purpose. While it distinguishes itself from siblings like 'build' or 'check', it does not explicitly compare, so it's very clear but not perfect.

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?

The description implies usage for discovery and editing ('bridge from mcp-nixos discovery to editing the right file') and provides a special case for Home Manager. However, it does not explicitly state when not to use this tool versus alternatives like eval_config or inspect_flake, nor does it mention prerequisites or error conditions.

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

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

With no annotations, the description carries the full burden and does so richly: it discloses that rollback_generation is recorded first, that the raw log is trimmed to a tail unless full_log=True, that status becomes 'degraded' when units newly fail, and that sudo auth failure yields a 'privilege' diagnosis. These are behaviors an agent could not infer from the schema alone.

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?

Dense and front-loaded — the core action and side effect (rollback generation) come first, then return shape, then the validate/privilege/local-only caveats. It is a single run-on paragraph, but essentially every clause carries decision-relevant information.

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?

Output schema exists, yet the description still helpfully summarizes the return shape (summary fields, gen before/after) and degraded/privilege states. Combined with the mutation side effects and the local-only scope, an agent has everything needed to invoke it correctly.

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%, so the description must compensate: it explains full_log (default tail vs everything) and validate (gate on dry-build) with meaning beyond the bare types, and the two commands imply mode values. flake_uri is never addressed, leaving one of four parameters undocumented.

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 a specific verb and resource — 'Activate the configuration' — and names the concrete underlying commands (nixos-rebuild switch / home-manager switch). It also implicitly carves itself out from siblings like check and build by describing what activation does versus dry-run validation.

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?

Explicitly tells the agent when to pass validate=True (to gate on check('dry-build')) and when not to (no implicit validation by default), and gives a hard exclusion: hosts requiring cluster cordon/drain and readiness gating must use their fleet orchestrator instead. That is a clear when/when-not/alternative triple.

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