nix-agent

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 by disclosing non-activation, success output (store path), and failure payload (failed_derivation with drv and log_tail). It does not mention store side effects or mode behavior, but the core behavioral traits are covered.

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 two sentences, front-loaded with the action and object, and contains no filler. Every sentence adds value: purpose, output, and failure behavior.

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?

The description adequately covers purpose, output, and failure modes, and an output schema likely covers return values. However, parameter semantics are entirely missing, and there is no explicit guidance on how this differs from 'switch' beyond 'without activating it', leaving the description incomplete for effective tool selection.

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 'mode' or 'flake_uri'. The agent gets no additional meaning beyond the parameter names and defaults, leaving significant ambiguity about valid values and their purpose.

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's purpose with a specific verb ('Build'), resource ('full system/HM closure'), and key scope ('without activating it'). This distinguishes it from activation-related siblings like '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?

The phrase 'without activating it' gives clear context for when to use this tool (pre-activation/build-only), and the mention of 'output store path' suggests inspecting build results. However, it does not explicitly name alternatives or state when not to use it.

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?

In the absence of annotations, the description discloses that lint returns a structured findings list, and it warns that dry-activate is NixOS only. However, it does not explicitly state that the tool is read-only, does not discuss side effects or permissions, and leaves the behavior of mode and flake_uri unaddressed.

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 a single, front-loaded sentence that efficiently conveys the core purpose and lists the level options with specific details. 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 three parameters and no annotations, the description explains the primary parameter (level) well and the overall workflow, but the silence on mode and flake_uri leaves a significant semantic gap. The presence of an output schema reduces the need to describe return values, but the overall context is only moderately complete.

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?

The description defines the possible values for the required 'level' parameter, giving meaningful semantics to lint, dry-build, and dry-activate. However, it says nothing about the 'mode' or 'flake_uri' parameters, which are left entirely to the schema's bare property names and defaults, so schema coverage is effectively 0% and the description does not compensate.

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 defines 'check' as a validation ladder for the configuration with three specific levels (lint, dry-build, dry-activate), each with a distinct verb and outcome. It distinguishes from sibling tools like 'build' and 'switch' by focusing on validation rather than execution.

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 phrase 'fast to slow' establishes a clear progression for when to use each level, and the explicit context for 'dry-activate' (NixOS only) provides a constraint. However, it does not explicitly contrast with sibling tools or state when to avoid this tool in favor of alternatives.

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. The description discloses a critical behavioral trait: the tool not only computes a diff but also switches the system to the new closure unless the user only wants a preview. However, it does not detail the side effects of switching (e.g., reversibility, downtime, permission requirements), which would be valuable for an agent to understand the impact. This is a moderate disclosure, so a 3 is given.

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 a single sentence that packs in the purpose, method, and usage conditions without redundancy. It is reasonably concise, though slightly dense, but every part contributes to understanding the tool. It earns a 4 for efficiency and lack of 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 that an output schema exists, return values need not be described. The description covers the main action and the switch behavior, but it lacks parameter semantics and does not explain the 'mode' or 'flake_uri' context. For a tool with only 2 optional params, this is a moderate gap, so a 3 is appropriate.

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 does not mention the parameters 'mode' or 'flake_uri' at all. The schema defines them with types and defaults, but without any semantic context in the description, an agent must infer their meaning from the names alone. This is a significant gap because the description should compensate for the lack of schema documentation, but it does not.

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: 'diff' the 'new closure' against the running system. It also mentions the key content of the diff (package additions, removals, version changes), which clarifies what the tool does. While it doesn't name sibling tools explicitly, the mention of 'switch' and 'check' as actions gives context that helps distinguish it from related 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 gives clear context for when to use this tool: when the user wants a diff and potentially a switch. It also specifies an exclusion condition: 'unless the user asked only to preview or check', which tells the agent when not to perform the switch. This is more than implied usage but less than naming explicit alternative tools, so a 4 is appropriate.

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 key behaviors: auto-resolution of flake_uri and mode, batch evaluation returning per-attr results, and size guard degrading large values. It does not mention authentication or side effects, but as a read-only evaluation, 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 concise with two sentences, front-loads the main action, and includes important details (auto-resolution, batch, truncation) without unnecessary fluff. It could be slightly more structured but is efficient.

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 an output schema, the description need not detail return types. It covers the core functionality (evaluation, batch, truncation) and mentions key constraints (size guard). Minor gaps about mode options and flake_uri auto-resolution do not significantly hinder understanding.

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 compensate. It explains that attr can be a string or array for batch mode, mentions defaults for mode and flake_uri, and gives an example ('services.openssh.enable'). However, it does not describe possible mode values or flake_uri format, leaving gaps.

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 evaluates the final merged value of an attribute in NixOS/Home Manager configuration via `nix eval`, with batch capability for multiple attributes. It distinguishes itself from siblings like build or check by focusing on evaluation of config values.

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 evaluating configuration attributes, but provides no explicit guidance on when to use this tool versus alternatives (e.g., build, check). It lacks exclusionary statements or context about when not to use it.

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 disclosure burden and meets it thoroughly: it discloses the side effect of recording rollback_generation first, the 'degraded' status semantics when units newly fail, log-tail trimming on success, and the 'privilege' diagnosis on sudo auth failure. These are exactly the behavioral traits an agent cannot infer from 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?

Six sentences, each carrying a distinct fact: purpose, rollback recording, structured summary return, log trimming, degraded status, validation behavior, and privilege error handling. There is no filler and no repetition of schema defaults, making the density of useful information exceptionally high.

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 an output schema exists, the detailed return-format description is a bonus rather than a necessity, and the description covers side effects, status semantics, validation behavior, and error edge cases. The main gap is flake_uri, whose interaction with mode (e.g., which flake to activate from) is undocumented in both schema and description. Slightly less complete than the rest of the definition.

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 compensate — and it does for three of four parameters: full_log (tail trimmed unless True), validate (gates on check('dry-build')), and mode (via the nixos-rebuild vs home-manager switch pairing). However, flake_uri is never mentioned, leaving its semantics entirely to inference. This is strong partial compensation for a fully undocumented schema.

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 opening verb 'Activate' names the precise operation — deploying the configuration as the active generation — and the parenthetical '(sudo -n nixos-rebuild switch / home-manager switch)' pins down the exact underlying commands. This clearly differentiates it from siblings like build, check, and diff, none of which activate a new generation.

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 gives some routing context by referencing check('dry-build') as the pre-activation validation gate and by implying this is the activation step in a workflow. However, it never explicitly states when to prefer this over build or diff, nor does it give a when-not-to-use condition. Guidance is largely implicit rather than explicit.

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