Skip to main content
Glama

Get Player Achievements

horizon_get_achievements
Read-onlyIdempotent

Reads visible achievement definitions and completion progress for a signed-in player, so you can load or refresh achievement status after unlocks or user actions.

Instructions

Reads visible achievement definitions and permanent completion bits. Use when: loading progress or refreshing after newlyUnlocked statistics or explicit user action; achievements have no WebSocket topic. Not for: changing balances or revealing locked hidden achievements. 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). Does not grant anything. Returns: {userId,revision,definitionVersion,definitions,progress,limits,serverTime}. definitions=null retains matching cached definitions; [] clears them. Scope caches to host/project/player/session. Compact progress has rewardState=complete, nullable unknown unlockedAt and no pendingReward/inboxEntryId copy. Legacy unsettled originals remain visible until verified cold settlement. 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).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "userId": "<userId>",
      "sessionToken": "<sessionToken>"
    },
    "name": "horizon_get_achievements"
  }
}

Input Schema

NameRequiredDescriptionDefault
userIdYesSigned-in player UUID matching the session
sessionTokenYesPlayer accessToken, sent only as Authorization Bearer
definitionVersionNoOpaque version from the matching cached snapshot; omit for full definitions

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?

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial context beyond them: no granting of anything, cache scoping to host/project/player/session, the null-vs-[] definitionVersion cache semantics, how compact progress differs (rewardState=complete, nullable unlockedAt, no pendingReward copy), legacy unsettled originals behavior, and a full error taxonomy (409/401/403/429, ACHIEVEMENT_NOT_MANUAL, MIGRATION_REQUIRED, missing HORIZON_API_KEY). Nothing here contradicts the annotations.

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-loaded with purpose then labeled sections (Use when / Not for / Requires / Side effects / Returns / Errors), which makes a very dense block navigable. The error paragraph is long and mixes several unrelated failure modes, but nearly every sentence carries operational value an agent would otherwise have to discover by failing.

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, and the description compensates by naming every return field and explaining the tricky ones (definitions, progress, limits, serverTime). Auth prerequisites, rate limits, and error recovery are all covered for a read tool with an open-world hint.

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 schema documents all three parameters; the description nonetheless adds real meaning by specifying that sessionToken is the accessToken from horizon_signin_email/horizon_signin_anonymous and that userId must match the signed-in session (403 if not). The definitionVersion cache behavior is partially stated but the null-vs-empty-array semantics are stated ambiguously ("definitions=null" vs the parameter name).

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?

"Reads visible achievement definitions and permanent completion bits" gives a specific verb plus resource with an explicit scope qualifier (visible, permanent). The 'Not for' clause separates it from balance-changing siblings like horizon_adjust_player_value and from hidden-achievement reveal, so an agent can route correctly without opening schemas.

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 when-to-use is given: loading progress or refreshing after newlyUnlocked statistics or explicit user action, plus the key detail that achievements have no WebSocket topic (so polling is the only path). Explicit when-not is also given (changing balances, revealing locked hidden achievements).

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