render_helm

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

With no annotations supplied, the description carries the full burden and does so well: local subprocess execution, 60 s timeout, no cluster contact, output linted in memory and never written to disk, a hard allow_exec gate, and a clear failure when helm is absent. These are exactly the traits an agent needs before authorizing a local exec.

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?

Dense but front-loaded: 'OPT-IN' and the core action lead, followed by safety and failure details. Parenthetical asides are frequent but each carries real information; no sentence is padding.

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?

For a local-exec tool with an output schema (so return values need not be described), the description covers the safety gate, timeout, side-effect profile, and failure mode. The remaining gap is the semantics of namespace and release_name, which matter for templating results.

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% across five parameters, so the description must compensate. It explains values_file (optional values YAML inside --dir) and allow_exec (the exec gate) and implies chart_dir, but says nothing about namespace or release_name (defaulting to "release"), leaving two parameters undocumented in both places.

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: it runs the local `helm template` on a chart directory and lints the rendered output in memory. The parenthetical clarifies execution scope (argument list, 60 s timeout, no cluster contact). It does not differentiate itself from siblings such as lint_manifests or values_review, so an agent must infer the boundary.

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?

Gives explicit activation guidance: it is OPT-IN and refuses unless allow_exec=true, which should only be set when the user asked to render a chart. That is a clear use condition. It stops short of naming alternatives (e.g., lint_manifests for already-rendered manifests), so the routing is only implied.

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