Get Auto Topup

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantive domain behavior beyond them: if `paymentMethodOnFile` is false the settings are inert and auto top-up will never fire, and a card can only be saved on porkbun.com. It further discloses charge fallback ordering (primary then backups) and card status semantics including `retryAfter` and `lastDeclineCode`.

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?

Front-loaded with purpose and the key field list before the operational caveats, and each sentence carries information an agent needs (inert-settings warning, card ordering, status values). The second paragraph on cards is dense but not padded; only minor tightening is possible.

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 exists, so the description carries the full burden of explaining return values — and it does so thoroughly, covering all fields, the cards array ordering, status enums, and the Link wallet edge case. Nothing an agent needs to interpret or relay the result is missing.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The space is instead used productively to explain the shape of the returned data.

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?

Opens with a precise verb+resource ('Read the account's auto top-up configuration') and immediately enumerates the concrete fields returned (threshold, amount, paymentMethodOnFile, effectiveAmount). It also distinguishes itself from the write-side siblings by explaining that effectiveAmount is what `top_up_account_credit` would charge right now, so an agent can separate reading config from initiating a charge.

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 the use case: 'Use it to tell the user which card would be charged, or that a card needs attention.' It also implicitly routes configuration changes elsewhere by noting cards are added/removed/reordered only on porkbun.com. It does not explicitly name `configure_auto_topup` as the mutation alternative, which keeps it short of a 5.

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