k8s__scale_deployment

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

No annotations provided, placing full burden on description. Only mentions dry-run diff preview, but does not disclose that scaling modifies the deployment spec, may cause pod restarts, or requires certain permissions. The behavioral traits of this mutation tool are insufficiently described.

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 extremely concise (5 words) and front-loaded with action and feature. No wasted words. However, it could be slightly expanded to improve completeness without sacrificing conciseness.

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 4 parameters, no output schema, and no annotations, the description is too sparse. It does not explain the dry-run diff preview output, the effect of scaling on the deployment, or prerequisites. Incomplete for a mutation tool that modifies cluster state.

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 0%; description adds minimal context for dry_run parameter ('dry-run diff preview') but nothing for name, namespace, or replicas. No details on format or meaning beyond what schema types imply. Fails to compensate for missing schema descriptions.

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 'Scale replicas with dry-run diff preview' clearly states the action (scale) and resource (replicas). The tool name includes 'deployment', so the resource type is implied. It distinguishes from siblings like k8s__rollout_restart or k8s__apply_manifest by specifying scaling with a dry-run preview feature.

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?

No guidance on when to use this tool vs alternatives like k8s__rollout_restart or k8s__apply_manifest. No prerequisites (e.g., deployment must exist) or context for when the dry-run feature is beneficial. The description lacks any usage context.

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