billing

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

Annotations already cover readOnly/idempotent/openWorld/non-destructive, so the bar is lower, and the description still adds real behavioral context: credit expiry (14 days), the once-per-card 400 JPY grant, prepaid charging rates (previews free to 2 GPU-min/day, finals 0.1 JPY per GPU-second), and a tell_user relay directive that appears nowhere in structured fields. There is a mild tension between readOnlyHint=true and the topup_yen path that creates a Stripe checkout link, but the description frames it as link generation with no charge, so it is not a clear contradiction.

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?

The body is effectively one enormous sentence dense with nested parentheses enumerating the pricing ladder, expiry windows, and offer flags. It is front-loaded with the core purpose, but the run-on structure makes it hard to scan and several clauses (deposit mechanics, per-second rates) are crammed together rather than separated.

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?

With an output schema present, return values need not be explained, and the description still covers the operational rules an agent needs: what is reported, the topup threshold, credit expiry/reset, and the tell_user relay. It is close to complete for a one-parameter tool; only the read-only-vs-checkout tension is left unaddressed.

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 description coverage is 100% and the single parameter is fully documented in the schema, so the baseline is 3. The description contextualises the topup path (creating a checkout link) but adds no syntax or format meaning beyond what the schema already states.

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 states a specific verb+resource ('Check what this key can still render for free and its credit'), then catalogues exactly what is reported: free GPU time, balance in yen, price per GPU-second, pending checkout link, and card/autocharge offers. It is clearly a billing/quota tool rather than a renderer, so an agent can place it against the render_* siblings. It stops short of naming any sibling or exclusion explicitly.

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?

Usage is implied rather than stated: checking credits/balance is the obvious 'use' and the schema's topup_yen documents the one conditional action. There is no explicit when-to-use vs when-not, no prerequisites, and no reference to alternatives, so guidance is only adequate.

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