Return a hosted Stripe link for the buyer to save a card or wallet to the account. After that, create_gift without a shared_payment_token charges the saved card.
| Name | Required | Description | Default |
|---|---|---|---|
| return_url | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden. It only states it returns a link and implies a sequential use with create_gift, but fails to disclose details like link expiry, idempotency, or potential side effects, which is insufficient for a payment-related 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?
Two sentences front-load the purpose and provide a usage hint, with no wasted words. The structure is efficient and clear.
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?
The description covers the basic purpose and links to the next step, but omits parameter documentation and behavioral details. For a simple tool, it is minimally viable but leaves gaps that an agent would need to infer.
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 input schema has one parameter (return_url) with 0% description coverage, and the description does not explain its purpose or behavior. This is a critical gap as the parameter is entirely undocumented in both schema and description.
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 clearly states the tool returns a hosted Stripe link for saving a card or wallet to an account, and it distinguishes itself from sibling tools like create_gift and cancel_gift by focusing on payment setup rather than gift operations.
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 explicitly says to use this tool before create_gift without a shared_payment_token to charge the saved card, providing clear context for when to use it. However, it does not mention when not to use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Each tool has a clearly distinct purpose: gift lifecycle (create, get, cancel, list), account info, pricing, resource listings, and brief validation. No overlap or ambiguity.
All tools follow a consistent verb_noun pattern in snake_case (e.g., create_gift, list_voices, validate_brief), making it predictable for agents.
12 tools is well-scoped for a gift ordering service, covering creation, retrieval, cancellation, pricing, account management, and resource listings without bloat.
The tool surface covers the full gift lifecycle and supporting operations (pricing, validation, account info, payment setup), with no obvious gaps for the intended domain.