Cancel an in-flight gift and receive the refund amount. Free. Only possible before the booklet goes to print; once printing has started it fails with cancel_too_late. Pass the gift_id from create_gift and an optional reason for your records.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | Optional human-readable reason for the cancellation, recorded on the order. | |
| gift_id | Yes | The gift_id returned by create_gift, identifying the order to cancel. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description covers key traits: cancellation is free, has a timing constraint with specific error, and reason is optional. Could mention irreversibility or refund details, but adequate.
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 concise sentences with no wasted words. Action verb first, prerequisites and constraints clearly stated.
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?
No output schema, but description explains the cancellation process and parameters. Lacks explicit mention of return value or side effects, but sufficient for a simple cancellation tool given sibling context.
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% with descriptions for both parameters. Description adds value by specifying the provenance of gift_id and the purpose of reason, exceeding schema information.
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 cancels an in-flight gift and obtains a refund. It uses specific verbs ('Cancel') and resource ('gift'), distinguishing it from siblings like create_gift and get_gift.
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 states when to use (before printing starts) and when it fails (cancel_too_late). Also specifies source of gift_id (from create_gift) and that reason is optional.
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.