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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent, closed-world mutation, so the safety profile is covered structurally. The description adds genuinely useful behavior not in the annotations: the spark cost per tier (150 / 500) and a parking prerequisite. It still omits whether sparks are deducted and non-refundable, and the non-idempotentHint means a repeat call re-charges the user — a consequence the description never warns about.

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?

It is short and front-loads the primary action and prices, which is good. The second sentence is compressed to the point of ambiguity — "Cars: only when parked" does not clearly say what a car has to do with buying a badge, so brevity here costs clarity rather than serving it.

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 a 3-parameter mutation tool, full schema coverage, and no output schema, the description covers the essentials an agent needs: what it buys, what it costs, and the parking precondition. What is missing is the auth/payment consequence (sparks deducted, repeat purchase charges again), which matters for a non-idempotent purchase, but the structured fields carry most of the remaining load.

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 baseline is 3, but the description earns above baseline by attaching concrete prices to each `tier` enum value (select 150, private 500) and by explaining the otherwise opaque `parked` flag through the parking condition. The wording of the parked clause is cryptic ("Cars:") and forces interpretation, which keeps it from a 5.

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 verb+resource pair ("Buy an income badge") is concrete and the two tiers with their spark prices are named, so the core action is identifiable. However, the trailing "Cars: only when parked" clause introduces an unexplained object ("Cars") that is never connected to the badge purchase, leaving the agent unsure whether this tool also deals with vehicles. No sibling tool is named or excluded, though no direct alternative exists among the siblings.

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?

There is a conditional hint ("only when parked (parked: true)"), which is the only real usage guidance present. Nothing states when to choose this over place_bid or other purchase-adjacent siblings, nor any preconditions such as holding enough sparks or needing registration. The agent must infer the entire usage context.

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