Skip to main content
Glama

Rotate Player Session

horizon_refresh_session
Destructive

Rotates an opted-in player refresh token once, issuing a new access token and refresh token pair for long sessions. Use it for a single refresh per token family; store the returned pair atomically.

Instructions

Rotates one opted-in player refresh token once, replacing both access and refresh credentials. Use when: a player opted into a long session and its client needs a new access token, with only one refresh in flight per token family. Not for: access-only sessions (use horizon_signin_*), concurrent refreshes, periodic auth polling or replay after a timeout/lost response. Read horizon://docs/auth first. Requires: the latest refreshToken in platform secure storage and the same project API key as its issuing signin. Never put the token in logs, analytics, crash reports or general preferences. Side effects: consumes the token and invalidates its old access token. Reuse revokes the entire family. Atomically store the returned pair before any later refresh. This tool performs one request and never retries. Returns: {accessToken, refreshToken, accessTokenExpiresAt, refreshTokenExpiresAt, tokenType: Bearer}; access has a one-hour sliding lifetime and the new refresh token expires 30 days after rotation. Errors: REFRESH_TOKEN_INVALID/EXPIRED/REVOKED/REUSED, REFRESH_TOKEN_SCOPE_MISMATCH and REFRESH_USER_INVALID are surfaced with HTTP status. On REUSED clear local family credentials and sign in again. After an uncertain response never resubmit the old token: require fresh signin. 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). For refresh, never retry a token after an uncertain response; obtain a fresh signin instead.

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": {
      "refreshToken": "<refreshToken>"
    },
    "name": "horizon_refresh_session"
  }
}

Input Schema

NameRequiredDescriptionDefault
refreshTokenYesLatest single-use refreshToken from an explicitly opted-in signin/signup or successful rotation, never an access token (max 512 characters)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.11.1

TDQS

A4.8/5.0
Behavior5/5

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

Annotations declare destructive/not-idempotent, but the description goes well beyond: it discloses that the token is consumed, the old access token invalidated, family revocation on reuse, the one-request-no-retry policy, required API key, rate limits, and specific error codes with handling guidance.

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?

Well structured with labeled sections (Use when, Not for, Requires, Side effects, Returns, Errors) and front-loaded purpose. It loses a point for redundancy: the no-retry-on-uncertain-response rule appears three times and the API key requirement is restated, adding avoidable length.

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?

For a single-parameter, non-idempotent auth-rotation tool with no output schema, the description fully covers prerequisites, side effects, return shape and lifetimes, and error handling, so an agent has everything needed to call it correctly and safely.

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: the token must be the latest from secure storage, must come from the same project API key as its issuing signin, and must never be logged or stored in general preferences.

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: 'Rotates one opted-in player refresh token once, replacing both access and refresh credentials.' This makes clear it is not a plain signin and explicitly routes access-only flows to horizon_signin_*.

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', 'Not for' with named alternatives (horizon_signin_* for access-only sessions), plus exclusions for concurrent refreshes, auth polling, and replay after timeout. Also says to read horizon://docs/auth first, leaving nothing 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