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

Annotations are absent, so the description carries the full disclosure burden and delivers: the financial side effect ('Deducts from account balance'), the two-phase confirm-before-execute flow, the authentication requirement, the return type (actionId), and critical parameter-driveen behaviors — omitting operatingSystemId yields 'a server with NO operating system installed,' and no sshKeyId means 'without one you cannot log in.' This exceeds what typical annotations would cover.

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?

One dense paragraph ordered logically: purpose → side effect → auth → required params → optional params → return value and next step. Every clause earns its place; there is no filler and no repetition of schema facts — sessionKey is deliberately left to the schema. The most dangerous omission behavior (no OS, cannot log in) is front-loaded into its parameter description.

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 ​6-param tool with no annotations, no enums, no output schema, and no nested objects, the description tells the agent everything needed to call it correctly: allowed values, resolution sources, money impact, return type, and the exact next step (executeConfirmedAction after user approval). Small gaps — behavior on insufficient balance and packageId lookup — are covered by siblings getAccountBalance and listVpsPackges.

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 only ​17% (just sessionKey) and there are no enums, so the description compensates fully: paymentTerm enumerates all five allowed states, hostname gives an inline format example, operatingSystemId explains both resolution via listVpsOsTemplates and the no-OS consequence of omission, and sshKeyIds names its sources and the login consequence. Only packageId ('VPS package ID') restates the name, but sibling listVpsPackages covers resolution.

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: 'Stage an order for a new VPS instance.' The word 'Stage' plus the explicit confession that it returns an actionId to be confirmed via executeConfirmedAction distinguishes it from the confusable sibling buildVpsInstance, which implies immediate construction. The 'Deducts from account balance' sentence further scopes what this tool does.

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?

Provides strong workflow context: it names the follow-up call (executeConfirmedAction with the returned actionId) and instructs the agent to present the summary to the user before proceeding. It cross-references listVpsOsTemplates, listMySshKeys, and addSshKey for parameter resolution, and the 'Requires authentication' note routes the agent to the auth tools. It does not explicitly exclude alternatives such as buildVpsInstance, so no exclusions are stated.

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