Skip to main content
Glama
ProjectMakersDE

horizOn MCP Server

Official
by ProjectMakersDE
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Unlock Manual Achievement

horizon_unlock_achievement
Idempotent

Unlocks one configured manual achievement once for an authenticated player when a game event matches its rule; requires userId, sessionToken, and stable key. Repeating the key never grants twice.

Instructions

Unlocks one configured manual achievement once for the authenticated player. Use when: an explicit game event meets this manual achievement's rule. Not for: statistic achievements or client-chosen reward amounts. 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: Commits the permanent completion bit and configured Player Values rewards in one transaction, immediately. No new Inbox or reward-history copy. Repeating the same key never grants twice, including after archival. This tool does not retry automatically. Returns: {achievements,newlyUnlocked,replayed,deliveryResults:[]}. On success explicitly refresh Player Values to replace the balance cache; do not claim or add a reward locally. Errors: 409 STATE_CONFLICT: reconcile and retry the same key. ACHIEVEMENT_NOT_MANUAL: report the configured statistic instead. MIGRATION_REQUIRED preserves legacy reward originals for the verified cold operator; it never authorizes a replacement reward or Inbox delivery. 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

NameRequiredDescriptionDefault
keyYesStable configured achievement key; never replace it to retry an unlock
userIdYesSigned-in player UUID matching the session
sessionTokenYesPlayer accessToken, sent only as Authorization Bearer

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.9.1

TDQS

A4.8/5.0
Behavior5/5

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

Goes well beyond the annotations (readOnly=false, idempotent=true, destructive=false) by disclosing the transactional commit of the completion bit plus Player Values rewards, absence of an Inbox/reward-history copy, permanent no-double-grant semantics surviving archival, and no automatic retry. Auth requirements (HORIZON_API_KEY, session vs userId), and specific 401/403/409/429 behaviors are spelled out.

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?

Front-loads the core sentence, then uses labeled sections (Use when, Not for, Requires, Side effects, Returns, Errors) that make skimming easy. The Errors paragraph is dense and somewhat sprawling, but nearly every clause carries actionable behavior rather than filler.

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?

With no output schema, the description compensates by naming the return shape ({achievements,newlyUnlocked,replayed,deliveryResults}) and the required post-call step of refreshing Player Values. Combined with full side-effect and error coverage for a non-idempotent-looking write tool, an agent has everything needed to call it correctly.

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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: userId must match the signed-in session and sessionToken is the accessToken from a signin call, plus the retry rule that the key must never be replaced. Only the key's pattern/length constraints remain schema-only.

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?

States a precise verb and resource ('Unlocks one configured manual achievement once for the authenticated player') including the 'once' cardinality and the 'manual' qualifier. The 'Not for: statistic achievements or client-chosen reward amounts' clause cleanly separates it from horizon_update_statistics and horizon_get_achievements.

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?

Explicit 'Use when: an explicit game event meets this manual achievement's rule' and 'Not for' exclusions, plus a concrete prerequisite path naming horizon_signin_email / horizon_signin_anonymous as the way to obtain sessionToken. Nothing about selection is left to inference.

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