zadig_build_update

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

With no annotations, the description must carry the behavioral burden. It helpfully discloses that dry_run defaults to true and that confirm=true is required, which is an important safety gate for a mutation tool. However, it doesn't explain what happens when confirm is false, whether changes are reversible, or how the update actually persists, leaving significant behavioral gaps.

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 two short sentences with no fluff. The action is front-loaded, and the second sentence adds important safety-relevant information. Every clause 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?

Despite the tool being a mutation with seven parameters, a nested build object, and no annotations, the description provides only a one-line purpose and a safety note. It does not explain the build object structure, the role of update_api, or how confirm gates the write. The output schema exists, but that doesn't compensate for the missing input and usage context.

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%, and the description only touches dry_run and confirm, without even defining what they do beyond their defaults/requirement. It provides no meaning for build_name, the nested build object, update_api, project_key, or allow_redacted. This is inadequate for a seven-parameter tool, especially one with an open-ended nested object.

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 the action and resource: 'Update one Zadig build configuration.' This distinguishes it from workflow, service, and template tools at a high level. It doesn't explicitly differentiate from closely related siblings like build_apply or build_update_from_template, so it stops short of a 5.

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?

There is no guidance about when to use this tool versus alternatives such as zadig_build_apply, zadig_build_create, or zadig_build_update_from_template. The dry_run/confirm note is operational guidance, not usage-selection guidance, so the description leaves the agent to infer the appropriate context.

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