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

Goes well past the annotations: it states the tool returns URLs only, that the user clicks to pay, and that it never charges silently — resolving the apparent tension of destructiveHint=false on a billing tool. It also discloses a real constraint absent from the schema (permanent tiers og/truebeliever/ogdev cannot downgrade) and the async side effect that a Stripe webhook flips tier server-side after checkout.

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 one-line guarantee, then a scannable intent-to-action table — no filler sentences. It is telegraphic in places ('next init reflects it' leaves 'init' undefined) and slightly dense, but nothing is wasted.

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 no output schema, the description does the work of describing returns: URLs for checkout/portal, tier/subscription/capabilities/SKU list for info, buyable SKU list for plans. The donate return value is left implicit, and the 'next init' post-checkout behavior could be spelled out, but an agent has enough to call and interpret each action 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?

Schema coverage is 100%, so the baseline would be 3, but the description adds genuine meaning: sku_id's provenance ('from plans') and amount_cents' effect (cumulative badge thresholds at 500/5000/25000 cents) are not in the schema. The remaining gap is minor formatting/syntax detail for amount_cents beyond the stated range.

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 specific scope, 'Account state + billing,' and then enumerates the five concrete operations (info/plans/checkout/portal/donate) with the data each one touches (tier, SKUs, Stripe URLs, donations). It is unmistakable against siblings like agent_manage or message, none of which touch billing.

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?

The 'Pick by intent' block maps user phrasings directly to actions ('what plan am I on?' -> info, 'upgrade me' -> checkout, 'cancel'/'invoices' -> portal, 'tip' -> donate), and even gives the fallback path for free users with no Stripe record (plans+checkout). Prerequisite routing like 'checkout (needs sku_id)' is stated inline.

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