ako_config_upgrade

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

Description adds significant behavioral context beyond annotations: the write nature, two-step safety mechanism with dry_run and confirmed, error behavior on missing release, and that dry-run is always safe. Annotations provide only basic hints (non-readOnly, non-destructive, non-idempotent), so the description carries the burden well.

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?

Description is well-structured with a bold summary line, then paragraphs for process and safety, ending with an Args list. Every sentence is informative and necessary, no 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?

Given the low parameter count, existence of output schema, and annotations, the description covers the upgrade workflow, safety, error handling, and parameter behavior completely. No missing context for agent invocation.

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?

With 0% schema coverage, the description fully documents both parameters: dry_run explained as preview toggle (default true), confirmed as required for actual apply (default false, ignored when dry_run=true). This adds essential meaning beyond the schema's basic type and default.

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?

Description states the tool performs an AKO Helm upgrade with updated values, specifying the verb 'Upgrade' and resource 'AKO Helm config'. It details the discovery of the release in avi-system and the use of official Broadcom OCI chart, clearly differentiating it from sibling tools like ako_config_diff or ako_config_show.

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?

Description provides clear context for safe usage: defaults to dry_run=true, explains the confirmed flag for actual application, and warns about failure when no AKO release is installed. However, it does not explicitly compare to sibling tools or state when not to use this tool.

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