zig_update

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

With no annotations to rely on, the description takes full responsibility for disclosing behavior. It states that dry_run changes nothing, that confirm=True combined with dry_run=False applies the upgrade, and warns about the danger of confirm=True without user consent. This is unusually clear for a mutation tool; it also implies a side effect (modifying the local toolchain) transparently.

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 compact and well-structured: one sentence states the purpose, the next two explain the two modes with their preconditions, and a final imperative warns about misuse. No filler or redundant information; each sentence earns its place.

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?

While the description covers the two critical operational aspects (dry-run and confirm), it omits the channel parameter entirely and does not mention what the output schema contains (e.g., what a successful upgrade returns). For a tool that mutates the local environment, the missing channel documentation is a real gap. The safety warning is strong, but the parameter coverage is incomplete, leaving the agent to guess about channel.

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?

The description competently explains dry_run and confirm, their defaults, and their interaction. However, the channel parameter is completely ignored. The schema provides no descriptions (0% coverage) and no enums, so the agent has no idea what values channel accepts or how it affects the upgrade (e.g., does 'stable' vs 'master' change the install method or version?). This is a significant gap for a parameter that likely affects the outcome.

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 a specific action ('upgrade the LOCAL zig toolchain') and distinguishes it from siblings like zig_version_status and zig_changelog which are about checking status or docs. It even explains the two modes (dry_run and apply) and which one is safe by default, leaving no ambiguity about what the tool accomplishes.

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?

Provides explicit when-to-use and when-not-to-use guidance: dry_run is the default, confirm should never be passed without the user explicitly requesting the update. This tells the agent exactly when to apply vs. just preview, and the warning about confirm covers safety. The mention of 'brew upgrade or official tarball' gives practical method context.

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