scale_deployment

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false, so the safety profile is covered. The description adds genuine value beyond that: it discloses the return value ('previous_replicas so the change can be undone') and the dry_run preview semantics, including that previews record no undo. It doesn't discuss permissions or rollback caveats, but it meaningfully extends the annotations.

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 the operation tag and core statement, then return/undo behavior, then a structured Args list. Efficient overall, though the dry_run behavior is stated twice (once in prose, once in Args), which is a minor 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?

With no output schema, the description correctly discloses the return value (previous_replicas) and covers all parameters and the dry_run/undo semantics. For a medium-risk write tool this is close to complete; only permission requirements and confirmation of what happens to an in-flight scaling operation are absent.

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%, so the description must carry the param burden, and it documents all five via an Args block. It adds real meaning the schema lacks, e.g., namespace 'omit for the target's default namespace' and target 'k8s target name from config'. Values are terse but sufficient for correct invocation.

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+resource ('Scale a deployment to replicas'), and the [WRITE][risk=medium] tag immediately signals the operation class. The resource is unambiguous enough to distinguish it from the sibling scale_statefulset, and the inverse relationship ('restore previous count') clarifies its place in the write operations.

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 clear context on when to use dry_run=True (preview without changing anything, no undo recorded) and notes the inverse operation for reverting. It stops short of explicitly naming an alternative tool (e.g., rollout_undo_deployment or scale_statefulset) or stating when NOT to use it, but the operational guidance is concrete.

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