diff_environments

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

No annotations are provided, so the description carries the behavioral burden. It conveys that the operation resolves variables and reports differences, implying a read-only comparison. However, it does not disclose output format, possible failure modes, performance implications, or whether any resolution side effects occur.

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 one dense, purposeful sentence with no filler. It front-loads the core verb and resource, states the comparison scope, and communicates the output concept without redundancy.

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?

With five parameters, nested objects, no output schema, and no annotations, this description leaves important gaps: what 'files' represents, what values the selectors may contain, what a 'difference' report looks like, and when this tool is preferable to resolve_variable or trace_variable. The core idea is present, but an agent would struggle to call it correctly without guessing.

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 60%; variables and the two environment objects have descriptions, and the description reinforces that all discovered variables are included by default. However, the required 'files' parameter and 'projectRoot' have no schema descriptions and the description does not clarify their meaning, leaving a critical input unexplained.

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 names a specific action ('Resolves every variable') and a distinct resource ('two different environment/service/workload selectors'), then states the comparison outcome ('reports what differs'). This clearly separates it from siblings like resolve_variable, which handles a single variable, and trace_variable, which traces rather than diffs.

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 'under two different environment/service/workload selectors' gives clear context for when to invoke this tool: when an agent needs to compare resolved variables across two configurations. It does not explicitly exclude alternatives or name sibling tools, but the intended scenario is apparent.

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