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

Annotations only declare write/idempotent/destructive booleans; the description adds real behavioral context beyond them: it explains merge semantics, that the change is committed to the cluster's GitOps repository, and a non-obvious side effect of rollback_on_failure (re-applying prior manifests can resurrect rotated-away credentials). This is valuable, hard-to-infer context an agent should know before mutating.

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 purpose and merge semantics, but the third sentence is long and tangential, diving into a specific rollback_on_failure failure mode with a run-on clause. Useful but heavier than it needs to be.

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 3-param mutation with a nested settings object and no output schema, the description covers purpose, merge behavior, GitOps commit side effect, and a key get-setting hazard. No return-value explanation is needed without an output schema, though it could mention whether there is any confirmation/async behavior.

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 100% and the schema already documents all three params including the settings object members. The description goes beyond the schema by explaining the sparse-merge semantics of settings and giving concrete operational guidance on when to set rollback_on_failure false, which is meaningful added interpretation not present in the schema.

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 (update) and resource (an installed addon's operational settings) and enumerates the exact setting members affected. It is trivially distinguishable from siblings like update_addon_configuration, get_addon_settings, and rollback_addon because it scopes to operational settings members.

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?

It clarifies partial-update semantics ('only the members present in the settings object change'), which tells the agent this is a sparse patch rather than a full replace. But it never says when to prefer this over siblings like update_addon_configuration or when to use rollback_addon instead, and it gives no prerequisites.

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