Estimate change cost

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

Directly reconciles with the annotations: it explains that it never mutates anything and that readOnlyHint=false exists only because tf_dir triggers `terraform plan` and its provider plugins. It also discloses the verdict vocabulary (ok/warn/over_budget/no_budget) and the no-budget fallback behavior — context the annotations cannot convey.

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 verdict, then the safety caveat, then the input routes and triggers. Slightly repetitive ('cost preflight' restated in triggers and examples), but every section carries usable signal.

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?

No output schema exists, and the description compensates by naming the primary return fields: machine verdict, monthly and annual cost delta, and budget headroom. Combined with the mutation disclaimer, an agent has everything needed to call it and interpret the result.

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%, yet the description documents all six parameters meaningfully: it groups terraform_plan_json/terraform_plan_file/tf_dir/helm_diff as alternative ways to describe the change, explains monthly_delta_usd as an escape hatch with a concrete example, and explains budget_name's default and the no-budget outcome. The only gap is precedence when multiple inputs are supplied.

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 ('Cost preflight for a proposed change') and immediately names the scope: estimates and checks budget fit but never applies anything. The distinction from siblings such as get_cost_summary and check_ai_budget is clear from the 'proposed change before apply' framing.

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?

Explicit timing guidance: 'Call this BEFORE applying an infrastructure change', plus good triggers ('will this fit my budget', 'cost preflight'). It names input routes and an escape hatch, but never explicitly contrasts itself with the sibling cost/budget tools, so the when-not-this-tool case is left implicit.

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