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

Beyond the readOnlyHint annotation, the description reveals valuable non-obvious behavior: the vault address is deterministic per wallet, fund arrive automatically after 12 confirmations, no WAN is needed, and no second transaction is required. These operational details inform the agent's expectations and are not present in annotations. There is no contradiction with annotations.

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?

Two dense sentences with the primary purpose front-loaded. Every clause adds operational value — deterministic address, chain-agnostic bridging, confirmation threshold, and auth pointer. No filler or redundancy.

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 single-parameter tool with no output schema, the description covers purpose, funding workflow, determinism, confirmations, and where to find auth details. The main gap is that it doesn't explicitly state what the tool returns (e.g., an address string or an object with chain details), though 'get... vault address' strongly implies the return value. Overall quite complete for the tool's simplicity.

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?

The schema provides only a parameter named 'beneficiary' with zero description coverage, so the description carries the burden. It partially compensates: 'the same address every time for a given wallet' implies beneficiary is the wallet identifier for which the vault is deterministic. However, it does not specify the expected format or type of the beneficiary value (e.g., a WAN address or an EVM address), leaving some ambiguity.

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 opens with a specific verb and resource: 'Get your dedicated OrbitPay deposit vault address.' It clearly states what the tool produces (a vault address) and the mechanism (bridge assets to it for prepaid credit). This distinguishes it from sibling tools like orbitpay_info (auth scheme) and orbitpay_crosschain_history (transaction history), so an agent can tell them apart.

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?

The description explains how to use the result ('bridge wanUSDT or wanUSDC to it... set toAddress to the vault') and when credit lands, giving strong context for invocation. It points to orbitpay_info for the auth scheme and implies that checking credit requires a separate signed call. It doesn't explicitly state 'use this tool when X, not when Y,' but the usage context is clear enough.

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