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

Annotations already mark it read-only and non-open-world, yet the description adds substantial operational depth: how capacity_now/wait_reason affect ordering, that queued upgrades apply automatically within ~24h and never move hosts, that pending_upgrade suppresses options, and how refunds/credits work. This goes well beyond what the annotations convey.

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?

Purpose is front-loaded in the first clause, and every subsequent sentence carries distinct information (modes, option fields, constraints, capacity semantics, math). It is dense and could be split for readability, but little is wasted.

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 having no output schema, the description enumerates the returned fields (product_id, name, monthly, prorated_topup, mode, line, capacity_now, wait_reason, pending_upgrade, options, unused_credit, new_cost) and explains their meaning and interactions. It is complete enough for an agent to interpret results and reason about a follow-up change_plan call.

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?

Only one parameter and schema coverage is 100%, with the schema already explaining the service_id format. The description mentions required auth ('token') but adds nothing about service_id semantics, so the structured field carries the burden — the correct baseline of 3.

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 (List) and resource (plans this VPS can switch to IN PLACE), and names the three operation modes (resize, convert, convert_to_nat) with their effects. It is clearly distinguishable from list_plans (generic catalog) and change_plan (executes the change).

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 explicit preconditions ('The server must be active') and hard exclusions ('Shrinking vCPU/RAM/disk is not possible'), and ties the result to the follow-up action change_plan. It stops short of explicitly routing against sibling tools like list_plans, so it is strong but not a full when/when-not/alternatives statement.

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