eval_config

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.