eval_config

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions using nix eval but does not state whether the operation is read-only, destructive, or requires specific permissions. It also fails to mention side effects, rate limits, or performance characteristics.

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 includes an example and key details about default behavior. It is concise and front-loaded with the primary action. No unnecessary 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 no annotations, the description provides adequate context for basic usage but lacks details about return values or confirmation that output schema conveys return structure. It would benefit from noting that the tool outputs the evaluated value.

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 that attr is a config attribute path with an example, and that flake_uri and mode auto-resolve when omitted. However, it does not describe valid mode values (e.g., 'nixos' vs 'home-manager') or the expected format for flake_uri.

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 a NixOS/Home Manager config attribute via nix eval, with an example. It distinguishes from siblings like build or switch by focusing on config value inspection rather than system mutation. However, it could explicitly contrast with sibling tools like check or diff.

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 checking config values but provides no explicit when-to-use or when-not-to-use guidance. It mentions auto-resolution of flake_uri and mode but does not clarify when users should override these defaults or how this tool compares to alternatives like diff for inspecting changes.

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