horizOn MCP Server

Official

by ProjectMakersDE

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

Prepare Gift Code Intent

horizon_prepare_gift_code

Read-onlyIdempotent

Prepare a gift-code redemption by reading the V2 campaign identity and exact current count without reserving or consuming it; persist the returned intent before redeeming.

Instructions

Reads a compact V2 campaign identity and exact current sequence without reserving or consuming a redemption. Use when: starting an explicit new action after prior outcomes are resolved; persist the returned intent before horizon_redeem_gift_code. Not for: recovering an uncertain action; retry its saved original intent with horizon_redeem_gift_code instead. 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: None (read only); no server intent or reservation is stored. Returns: {valid,intent}; intent is null when invalid, otherwise exactly protocolVersion,projectScope,userId,code,campaignId,expectedCount,configRevision. Counts/revisions are exact Int64 decimal strings; projectScope binds the local host/project without exposing credentials. Persist all seven fields, never the session token. Errors: 409 UPGRADE_REQUIRED closes V1; MIGRATION_REQUIRED needs operator migration; COUNT_AHEAD, CAMPAIGN_CHANGED, COUNTER_EXHAUSTED and STATE_CONFLICT require explicit reconciliation. Keep the original intent on every uncertain outcome, never prepare or advance automatically. 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

Name	Required	Description
`code`	Yes	Original visible gift code, retained with the prepared campaign identity
`userId`	Yes	Player user ID (UUID) from horizon_signup_* or horizon_signin_*
`sessionToken`	Yes	Current accessToken of the intent's original user, sent only as a Bearer header

Output Schema

Name	Required	Description	Default
`valid`	No
`intent`	No

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.9.1Oct 23, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the read-only annotations, the description clarifies that no server intent or reservation is stored and that all seven returned identity fields must be persisted while the session token must not be. It also documents authentication requirements, token provenance, rate-limit behavior, and specific error meanings, giving the agent unusually rich behavioral context.

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?

The description is long but well structured around Use when, Not for, Requires, Side effects, Returns, and Errors, with the core purpose front-loaded. The length is largely justified by the operation's many error and recovery conditions, though the extensive error catalogue is denser than strictly necessary.

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?

The tool has an output schema, but the description still gives a precise return summary: valid plus intent, with intent null when invalid and otherwise containing exactly seven persisted fields. Combined with authentication, side-effect, and error details, the description is complete enough for correct invocation and handling.

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

Parameters4/5

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

Input schema coverage is 100%, so the schema already explains the three parameters. The description adds useful semantics beyond the schema by explaining that sessionToken is the accessToken from horizon_signin_email or horizon_signin_anonymous, that userId must match the signed-in user, and that the token is sent only as a Bearer header.

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?

The description names a specific operation on a specific resource: preparing a V2 campaign gift-code intent by reading identity and sequence without reserving or consuming a redemption. It clearly distinguishes this from recovery and redemption paths by directing uncertain cases to horizon_redeem_gift_code with the saved intent.

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?

It explicitly states when to use the tool: starting a new action after prior outcomes are resolved, and persisting the returned intent before redemption. It also states when not to use it: recovering an uncertain action should retry the saved original intent with horizon_redeem_gift_code instead.

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

Deploy Server