Start the purchase of a prepaid unit pack (s: 1.2M units $10 · m: 7M $50 · l: 32M $200, +5 % units when bought here). Returns a checkout URL for the account owner to complete on the card; units become available the moment the payment lands and are consumed after the plan's monthly quota. Valid 12 months. Read balances with billing_status.
| Name | Required | Description | Default |
|---|---|---|---|
| size | Yes | Pack size: s, m or l |
Changes observed during successful MCP inspections. Dates show when Glama detected each change.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it is unusually rich: a checkout URL is returned, units become available when payment lands, consumption happens after the monthly quota, packs are valid 12 months, and there is a +5% bonus. It also clarifies the purchaser must be the account owner completing on card. This fully discloses the tool's side effects and timing.
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 sentences pack all essential information with no filler; purchase options are front-loaded, followed by the flow, timing, and valid duration. Every sentence earns its place.
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 one-parameter, no-output-schema tool, the description covers what the call returns, who can complete it, when units activate, how they are consumed, and validity. Nothing essential is missing for an agent to select and invoke it 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?
The schema only says size is s, m, or l; the description adds exact units, prices, and the +5% bonus, making the choice meaningful. Since schema coverage is 100% and only one parameter exists, the description has already done the needed semantic enhancement.
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 starts with a specific verb-resource pair: 'Start the purchase of a prepaid unit pack,' and immediately enumerates the three pack sizes with units and prices. It also distinguishes itself from billing_status by pointing balance reads to that sibling, so an agent can tell which tool handles purchasing vs. reading balances.
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?
It states clear context for use: buying prepaid units, and gives the alternative for balance reads via 'Read balances with billing_status.' It doesn't explicitly describe when not to use buy_pack beyond the balance-read case, but the purchase context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.