Skip to main content
Glama

Get Player Inbox

horizon_get_inbox
Read-onlyIdempotent

Reads a player's targeted messages and eligible project broadcasts, returning inbox entries, counts, cursors, and a polling interval for notifications or refresh.

Instructions

Reads targeted messages and eligible project broadcasts, counters and server polling interval. Use when: displaying notifications or refreshing on open, explicit action or the returned polling cadence; Inbox has no WebSocket topic. Not for: choosing rewards or writing messages from the player client. 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). Returns: {userId,cursor,revision,broadcastRevision,serverTime,pollAfterSeconds,unchanged,entries,counts,limits}. unchanged=true has empty entries: keep the cached entries. A changed snapshot replaces them completely. Entries of type item_gift and item_gift_return carry attachment.itemGift {giftId,instanceId,itemKey,direction}; decline an offer with horizon_decline_item_gift. Errors: 409 STATE_CONFLICT: retry the same entry ID. UNCLAIMED_REWARD: claim before removal. MAX_BALANCE_REACHED/DAILY_LIMIT_REACHED/INVENTORY_FULL leaves the reward or original item unclaimed. ENTRY_NOT_FOUND after removal/cleanup never grants again. 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_inbox"
  }
}

Input Schema

NameRequiredDescriptionDefault
sinceNoOpaque cursor from this same player/project; omit for a full snapshot
userIdYesPlayer UUID belonging to the selected project and player session
sessionTokenYesPlayer accessToken, sent only as Authorization Bearer

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.9.1

TDQS

A4.3/5.0
Behavior5/5

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

Beyond the annotations, the description discloses auth provenance (userId plus accessToken from horizon_signin_email/anonymous), that the call is read-only with no side effects, the polling model, and the exact semantics of unchanged=true vs a changed snapshot. It also enumerates error codes with corrective actions (409 retry same entry ID, 401 re-sign-in, 403 token/user mismatch, 429 rate limit) and the required HORIZON_API_KEY, which is substantial disclosure the annotations cannot carry.

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?

Dense but well structured with labeled sections (Use when / Not for / Requires / Side effects / Returns / Errors), and the core purpose and scoping are front-loaded. The long error catalog is useful for a session-plus-cursor read but borders on exhaustive verbosity.

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?

There is no output schema, so the description carries the return contract itself and does so fully: the response field list, the unchanged/replace snapshot rule, the item_gift attachment shape, and the decline path via horizon_decline_item_gift. Combined with auth and error guidance, an agent has everything needed to call and interpret this tool.

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 meaning the schema does not: where sessionToken comes from, that the token must belong to the supplied userId (the 403 case), and the cursor-based snapshot semantics implied by the 'unchanged' handling. The 'since' parameter is only explained by the schema, keeping this from a 5.

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

Purpose4/5

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

The first sentence gives a specific verb and resource ('Reads targeted messages and eligible project broadcasts, counters and server polling interval'), which is more precise than the title alone. The 'Not for' line clarifies the scope boundary. It stops short of naming the natural siblings (horizon_claim_inbox, horizon_mark_inbox_read, horizon_remove_inbox) that an agent would need to disambiguate among inbox operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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

Explicit 'Use when' conditions (displaying notifications, refreshing on open, honoring the returned polling cadence) plus a note that there is no WebSocket topic, and an explicit 'Not for' exclusion. It does not point to the specific alternative tools for claiming/removing/marking entries, so the routing guidance is directional but incomplete.

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