Skip to main content
Glama
ProjectMakersDE

horizOn MCP Server

Official
by ProjectMakersDE
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Redeem Gift Code

horizon_redeem_gift_code

Redeem a gift code for a player, using one redemption and returning reward data and cosmetic unlocks. Use when the player confirms a code, after checking it with horizon_validate_gift_code.

Instructions

Redeems a gift code for a player: uses up one redemption and returns the reward data and any cosmetic unlocks. Use when: the player confirms a code in the game. Check it first with horizon_validate_gift_code when unsure. Not for: only checking a code (use horizon_validate_gift_code, which uses nothing up). Requires: userId and the player's session: sign in with horizon_signin_email or horizon_signin_anonymous and pass its accessToken as sessionToken. Side effects: each successful call uses up one redemption and cannot be undone; cosmetic grants are added to the player's unlocks. A repeat redeems again or fails when the per-player limit is reached. Returns: {success, message, giftData, grantedUnlocks}. giftData is a JSON string with the reward set in the dashboard, which the game must parse and apply. grantedUnlocks lists the cosmetic IDs from giftData.grants the player owns after this redemption ([] without grants); show them with horizon_get_profile. Errors: 404 for an unknown code. 400 for an expired or revoked code or a reached limit: tell the player the code does not work. 409 UNLOCK_LIMIT_REACHED when the player would own more than 25 unlocks; the code is not used up. 401 means the session is missing or expired: sign in again and retry with the new accessToken. 403 for a session means the token belongs to another user: pass the userId that signed in. Needs HORIZON_API_KEY. Every failure returns an error result (isError) with the HTTP status and body: a 401 that horizon_test_connection also returns means HORIZON_API_KEY is wrong, 429 means the account's per-minute rate limit was reached (wait a minute, then retry).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
codeYesGift code as the player typed it (max 50 characters)
userIdYesPlayer user ID (UUID) from horizon_signup_* or horizon_signin_*
sessionTokenYesaccessToken from horizon_signin_email or horizon_signin_anonymous for this userId; sent as a Bearer session

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv1.6.0
    • changedInput schema / properties / code / description
      Previous value: -"Gift code to redeem (max 50 characters)"New value: +"Gift code as the player typed it (max 50 characters)"
    • addedInput schema / properties / code / minLength
      Added value: +1
    • addedInput schema / properties / sessionToken
      Added value: +{
+  "description": "accessToken from horizon_signin_email or horizon_signin_anonymous for this userId; sent as a Bearer session",
+  "maxLength": 256,
+  "minLength": 1,
+  "type": "string"
+}
    • changedInput schema / properties / userId / description
      Previous value: -"User ID (UUID) returned by a horizon_signup_* or horizon_signin_* tool"New value: +"Player user ID (UUID) from horizon_signup_* or horizon_signin_*"
    • changedInput schema / required
      Previous value: -[
-  "code",
-  "userId"
-]New value: +[
+  "code",
+  "userId",
+  "sessionToken"
+]
  2. Changed1 schema field changedv1.5.5
    • changedInput schema / properties / userId / description
      Previous value: -"User ID (UUID)"New value: +"User ID (UUID) returned by a horizon_signup_* or horizon_signin_* tool"
  3. First observedv1.5.4

TDQS

A4.6/5.0
Behavior5/5

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

Annotations (readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false) only sketch the safety profile; the description adds far more: one redemption is consumed per success, the action cannot be undone, repeat calls redeem again or fail at the per-player limit, unlock grants mutate the player's unlocks, HORIZON_API_KEY is required, and per-minute rate limits apply. It also spells out the full error taxonomy (404, 400 expired/revoked/limit, 409 UNLOCK_LIMIT_REACHED with the code not consumed, 401 vs 403 semantics) and the isError result contract.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Densely labeled with 'Use when', 'Not for', 'Requires', 'Side effects', 'Returns', 'Errors', and front-loads the core action and its cost before the detail. Every section carries actionable content, though the error enumeration is long enough that an agent must read past several lines to reach the auth/rate-limit notes.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, yet the description fully specifies the return shape ({success, message, giftData, grantedUnlocks}), explains that giftData is a JSON string the game must parse and apply, and clarifies that grantedUnlocks lists post-redemption cosmetic IDs. Combined with auth prerequisites, side effects, and error handling, an agent has everything needed to invoke and interpret this call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so code, userId, and sessionToken are already documented at the field level, including that the token is sent as a Bearer session. The description restates the acquisition path ('sign in with horizon_signin_email or horizon_signin_anonymous and pass its accessToken as sessionToken') but adds no format, constraint, or edge-case detail beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Starts with a specific verb+resource ('Redeems a gift code for a player') and immediately scopes what the call does: consumes a redemption and returns reward data plus cosmetic unlocks. It explicitly names the sibling it is not (horizon_validate_gift_code), so an agent can distinguish redeem from validate 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.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when ('the player confirms a code in the game'), when-not ('only checking a code'), and the alternative (horizon_validate_gift_code, noted as using nothing up). The routing decision between redeem and validate is fully specified with the cost trade-off that motivates it.

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

Deploy Server

Other Tools