resize_volume

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

The description discloses critical behavioral traits not present in annotations: it spends real money, requires confirmation, and is asynchronous. It also states the 'grow only' limitation, which is a significant behavioral boundary. Annotations only provide generic flags (readOnly=false, idempotent=false), so the description carries the full burden of warning about cost and async behavior—it does so clearly and concisely.

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 two tightly packed sentences. The first sentence states the core action and scope ('Resize a standalone volume (grow only)'), and the second adds two critical caveats (money + confirm, async). No filler or redundant information. It is front-loaded with the most important details and earns every word.

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 cost-incurring, asynchronous mutation, the description provides the necessary operational directives: confirmation and polling the status endpoint. It does not mention return value (but there is no output schema), error conditions, or prerequisites like volume existing or being unattached, but these are partially implied by 'standalone' and 'grow only.' Overall, it covers the critical aspects needed to call the tool correctly, with minor gaps that do not block usage.

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 must compensate. It explicitly explains the confirm parameter ('requires confirm=true'), which is crucial because it has a default of false and is not required in the schema. However, volume_id and size_gb are not elaborated beyond their names; while their meanings are fairly self-evident from the tool name, the description does not add detail on units or constraints (e.g., size_gb must be larger than current). It partially compensates but not fully.

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 states the exact operation: 'Resize a standalone volume (grow only).' It clearly identifies the verb, resource, and a key constraint (growth only), and differentiates from the sibling resize_vps by specifying 'standalone volume.' This leaves no ambiguity about what the 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?

It provides essential usage context: requires confirm=true and is asynchronous, directing the agent to poll get_volume_task_status. However, it does not explicitly state when to use this tool versus resize_vps or other volume operations, though the 'standalone volume' wording implies a distinction. Strong guidance on the critical prerequisites, but not exhaustive.

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