Scale Serving

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

Adds substantial context beyond the annotations: which edits are gated behind confirm=true, which apply immediately, the two-phase preview-then-confirm protocol, and the retry rule after a timeout. The operation_id guidance (reuse the ID; a new ID means a new operation) directly explains the idempotentHint=true contract in operational terms.

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?

Mutation surface is front-loaded in the first sentence and the confirm rule follows immediately, so the important information leads. The second sentence is an em-dash run-on that packs three cases together, costing some readability, but no sentence is disposable.

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?

An output schema exists, so return values need not be re-described, and the description still tells the agent that a preview returns current state plus the requested change. For a 7-parameter mutation tool the operational story is complete; only the serving identifier format is left implicit.

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%, so the description carries the load, and it does explain confirm, autoscale, min/max replicas, price_cap_per_hour, and operation_id semantics well. The one gap is the required `serving` parameter—identity format (numeric ID vs name) and min<=max constraints are never stated.

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?

Opens with a specific verb and resource plus the exact mutables: 'Change a serving's replica range, autoscaling, or per-replica price cap.' That cleanly separates it from deploy_serving, pause_serving, and delete_serving, which are the adjacent siblings an agent could confuse it with.

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?

Strong conditional routing inside the tool: cost-raising changes with confirm=false only preview, while lowering the range / disabling autoscale / lowering the cap apply immediately. It does not name sibling alternatives (e.g. deploy_serving for initial creation, pause_serving for stopping), so an agent must infer those from the sibling list.

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