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

Goes well past the annotations: it discloses that the call only creates an awaiting_approval state and no money moves until the owner approves in Vybe — critical context for a non-read-only, non-idempotent tool. It also surfaces the URL-domain guardrail and the spend-key authorization scope, neither of which appears in the 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?

Three compact sentences: the action and inputs come first, then the most consequential behavior (no immediate money movement), then the eligibility restriction and related tools. No sentence restates the name or title.

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 payment tool with an output schema, no annotations covering the approval flow, and full schema coverage, the definition supplies the missing essentials: approval gating, allowed URL scope, spend-key context, and pointers to balance/limit tools. An agent has enough to decide and invoke correctly.

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 100%, so the schema already documents both parameters and the baseline is 3. The description adds real meaning on top: the url parameter must be a vybe.finance/r/… link rather than any arbitrary URL, a validation constraint the schema does not state.

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?

Names a specific verb and resource ("Pay a Vybe invoice") plus the two accepted identifiers (URL or publicId) and the spend-key scope. It is immediately distinguishable from create_invoice and get_invoice, which operate on the invoice lifecycle rather than moving funds.

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 eligibility constraints — only vybe.finance/r/ links, not arbitrary URLs, and friendship is not required — plus a "Related:" list pointing to create_invoice, get_invoice, get_limits, get_spend_balance and list_recent_pays. It stops short of explicitly naming a when-to-use alternative (e.g. pay_offering) or stating prerequisites such as sufficient balance.

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