Purchase Player Value Offer

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

Annotations already declare destructive=true and idempotent=true, but the description goes well beyond them: atomic debit+credit, replay-by-same-ID semantics with no automatic retry, distinct fresh-vs-replay return shapes, and a specific error taxonomy (409/OPERATION_CONFLICT/OPERATION_EXPIRED/INSUFFICIENT_BALANCE/401/403/429) with recovery instructions. Nothing here contradicts the annotations; the destructive and idempotent hints are actively explained.

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?

Well front-loaded and clearly segmented into Use when / Not for / Requires / Side effects / Returns / Errors. It is long, but for a destructive monetary operation with no output schema most sentences carry operational weight; the only mild redundancy is the repeated warning about not generating a new operation ID ('no automatic retries or new IDs' vs. 'never silently generate another ID').

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 four required parameters, no output schema, and destructive+idempotent semantics, the description covers everything an agent needs: auth acquisition path, API key requirement, idempotency contract, return shape including the operation object, and failure handling for each documented status. Nothing material is left to inference.

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; the description still adds real value by stating where each value comes from (offerKey from horizon_get_player_value_offers, sessionToken from horizon_signin_email/anonymous) and by emphasizing the operationId lifecycle ('persist before the first request', never mint a new ID on conflict/expiry). That is meaningful guidance beyond the schema's field-level text, though the schema already documents operationId formatting and reuse fairly well.

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 verb and resource ('Purchases one configured offer') and immediately scopes it ('atomic costs and value/item rewards, retaining only a minimal public duplicate guard'). It also names the sibling that produces the input (horizon_get_player_value_offers), so the agent can distinguish this from the read-side offer tool without opening either schema.

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 'Use when' and 'Not for' clauses: only after a player confirms an offer returned by horizon_get_player_value_offers, and never for arbitrary cost/reward selection. This is exactly the when/when-not/alternative structure that routes an agent correctly among 100+ siblings.

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