Skip to main content
Glama

Claim Inbox Reward

horizon_claim_inbox
DestructiveIdempotent

Claim one inbox reward for the authenticated player: atomically mark the entry claimed and grant its configured values or return the exact escrowed item once.

Instructions

Claims an inbox reward once for the authenticated player. Use when: an explicit player action on an entry returned by horizon_get_inbox. Not for: changing the recipient or inventing attachment 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: Atomically marks the entry claimed and grants its configured values or restores its exact escrowed original item once. attachment.itemGift {giftId,instanceId,itemKey,direction} marks an item gift offer (direction offer) or return (direction return); claiming it moves that original instance. No automatic retries or new action IDs. Overdue unclaimed rewards remain claimable. Returns: {entryId,replayed,inbox,playerValues,items}. Replace the value cache with playerValues; item references are receipts, never instructions to mint an item. Explicitly refresh inventory after a claim. Never apply a reward delta again. 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>",
      "entryId": "<entryId>"
    },
    "name": "horizon_claim_inbox"
  }
}

Input Schema

NameRequiredDescriptionDefault
userIdYesPlayer UUID belonging to the selected project and player session
entryIdYesExact stable entry ID from the inbox snapshot, including message: or broadcast: prefix
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 past the annotations: atomic claim, grants configured values or restores the exact escrowed original, no automatic retries or new action IDs, overdue rewards stay claimable, and a detailed error taxonomy (409/UNCLAIMED_REWARD/MAX_BALANCE_REACHED/ENTRY_NOT_FOUND/401/403/429). Annotations already declare destructive=true and idempotent=true, and the described behavior (entry consumed, replay semantics) is consistent with both rather than contradicting them.

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 blocks (Use when / Not for / Requires / Side effects / Returns / Errors) so an agent can scan to the needed section. It is long and error-dense for a 3-parameter tool, but nearly every sentence carries operational information 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 supplies the return shape ({entryId,replayed,inbox,playerValues,items}), what to do with it (replace value cache, refresh inventory, never re-apply a delta), and full failure handling. Nothing material is missing for a destructive, idempotent mutation with authentication dependencies.

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: sessionToken must come from a horizon_signin_* accessToken and be the token for the passed userId, and entryId must be the exact stable ID from the inbox snapshot with no new action IDs on retry. The attachment.itemGift structure it references describes the entry payload rather than an input parameter, which is useful context but slightly out of scope.

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?

Opens with a specific verb+resource+scope: 'Claims an inbox reward once for the authenticated player.' The 'Use when' clause ties it to an entry returned by horizon_get_inbox and 'Not for' rules out adjacent behaviors, so it is distinguishable from horizon_get_inbox and horizon_remove_inbox without opening a 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?

Explicit when-to-use (explicit player action on an entry from horizon_get_inbox), explicit when-not (changing recipient, inventing attachment amounts), and explicit prerequisites (sign in via horizon_signin_email/anonymous and pass that accessToken). The alternative path is named rather than inferred.

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