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

Annotations only declare write/destructive/open-world; the description adds the substantive behavior: exact costs and term lengths, the daily-check cadence, that results are published on a PUBLIC page with a badge image and signed copy (a real external side effect), the ~10 minute latency for the first result, and the owner-approval gate above a daily limit. It also clarifies that a repeated idempotency_key is a retry rather than a duplicate order, which usefully sharpens the `idempotentHint: false` annotation rather than contradicting it.

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?

Dense but front-loaded: the price and term open the description, then prerequisites, then behavioral caveats. Semicolon-chained clauses such as 'renew with buy and the badge's instance_id ($3 per 30 days)' take a re-read, but no sentence is filler.

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, and the description compensates by routing to `get_utility` for the first result and its timing, and by describing what the purchase produces (public page, badge image, signed copy). Gaps remain around failure/refund behavior and whether the paid term is cancellable, which matter for a destructive spend tool.

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%, so the baseline is 3; the description goes beyond by explaining that the same idempotency_key and domain produce a retry rather than a second order, and by tying the domain argument to a prior `prove_domain` call within 7 days. It does not explain max_price_cents behavior (what happens if the price exceeds the cap) or clarify how the badge's instance_id used for renewal relates to the inbox_instance_id parameter, leaving a small ambiguity.

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 identifies a specific transaction (spending balance) for a specific resource (a badge tied to daily site checks) at a specific price and term. It also implicitly separates itself from the sibling `buy` tool by explaining that renewal goes through `buy` with the badge's instance_id, and from `prove_domain` by naming it as a prerequisite. It never states the verb+resource plainly ('buys a badge subscription'), which keeps it just short of a 5.

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?

Explicit preconditions ('Needs the domain proved with prove_domain in the last 7 days'), an explicit alternative for renewal ('renew with buy'), an exclusions statement ('Not a security audit'), and an escalation path ('Above the daily limit it waits for your owner's approval'). An agent has everything needed to decide use vs. not-use and vs. which sibling.

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