buy_vpn

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

With no annotations provided, the description carries the full burden and does so: it discloses that real on-chain payment occurs, that each invocation creates a new invoice, that retrying after a paid error is dangerous and must be replaced by fulfill_payment with recovery fields, and what the result's `vpn` object contains. These are exactly the irreversible-side-effect and idempotency facts an agent needs before calling a payment tool.

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?

Front-loaded with the preferred-tool marker and the workflow, and nearly every clause carries operational weight (no-retry, invoice creation, recovery path). It is dense to the point of being hard to scan, with several compound sentences packed into one block, but little is genuinely expendable.

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 high-stakes payment tool with no annotations and no output schema, the description covers the workflow, the failure/recovery path, and the shape of the returned `vpn` credentials. The remaining gap is the semantics of `country` and `network`, which an agent would have to guess at.

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 0% across four parameters. The description does add real meaning for `dry_run` (it creates a new invoice, so don't chain it into a buy) and points to list_vpn_catalog's `services` field as the way to choose `plan`, but `country` and `network` are never mentioned, leaving half the parameters undocumented anywhere.

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 and resource ("Buy VPN") and immediately enumerates the full operation chain: quote → pay on-chain → fulfill → save credentials. This makes it clearly distinguishable from the sibling tools sign_and_pay and fulfill_payment, which are individual steps of that chain.

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?

Explicitly marks itself as PREFERRED, says to call ONCE per purchase, forbids curl/shell against /pay, forbids the dry_run-then-buy sequence with a stated reason (each quote creates a new invoice), and routes the agent to fulfill_payment instead of retrying on post-payment errors. When-to-use, when-not-to-use, and the alternative are all named.

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