horizOn MCP Server

Official

by ProjectMakersDE

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

List Leaderboard Boards

horizon_list_leaderboards

Read-onlyIdempotent

Lists leaderboards for the API key with keys, sort order, and validated-only status, so you can pick a leaderboardKey before submitting or fetching scores.

Instructions

Lists the leaderboard boards of this API key with their keys, sort order and whether they accept only validated runs. Use when: first, when a game has several boards (weekly, per level) or before submitting, to learn the leaderboardKey values and whether a board is validatedOnly. Not for: reading entries (use horizon_get_leaderboard_top, horizon_get_user_rank or horizon_get_leaderboard_around). Side effects: None (read only). Returns: {boards: [{key, name, sortOrder, isActive, scoreCount, validatedOnly}], totalElements}. Pass a key as leaderboardKey to the submit, top, rank and around tools; without it they use the default board. validatedOnly true means scores are accepted only through horizon_start_run plus horizon_submit_validated. Errors: 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

Name	Required	Description	Default
No arguments

Output Schema

Name	Required	Description	Default
`boards`	No
`totalElements`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.6.0Oct 2, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "properties": {
+    "boards": {
+      "anyOf": [
+        {
+          "description": "Boards of the API key",
+          "items": {
+            "additionalProperties": {},
+            "properties": {
+              "isActive": {
+                "anyOf": [
+                  {
+                    "description": "false when the board is disabled",
+                    "type": "boolean"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "key": {
+                "anyOf": [
+                  {
+                    "description": "Board key to pass as leaderboardKey",
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "name": {
+                "anyOf": [
+                  {
+                    "description": "Display name",
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "scoreCount": {
+                "anyOf": [
+                  {
+                    "description": "Number of entries",
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "sortOrder": {
+                "anyOf": [
+                  {
+                    "description": "DESC (higher wins) or ASC (lower wins)",
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "validatedOnly": {
+                "anyOf": [
+                  {
+                    "description": "true when only horizon_submit_validated may write scores",
+                    "type": "boolean"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "totalElements": {
+      "anyOf": [
+        {
+          "description": "Number of boards",
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "type": "object"
+}

First observedv1.5.4Sep 28, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the description's 'Side effects: None (read only)' is redundant. It earns credit for the downstream-key contract ('pass a key as leaderboardKey... without it they use the default board') and the validatedOnly semantics, but the errors section partially overlaps with the output schema and general MCP error patterns.

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 Use/Not-for/Side effects/Returns/Errors sections. Dense but well-organized. The errors paragraph names a specific 401/429 interplay with horizon_test_connection that is useful, though slightly verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists, the return values needn't be restated, yet the description does so anyway (helpful for agents that don't parse schemas). The auth/error contract (HORIZON_API_KEY, 401/429 semantics, test_connection cross-reference) fills a real gap for a zero-param read 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?

Zero parameters, so baseline is 4. The description adds value by explaining how returned keys are consumed by other tools, which is param-adjacent semantics not present in the (empty) schema.

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?

Specific verb+resource ('Lists the leaderboard boards of this API key') with the returned fields enumerated, and sibling tools for reading entries are named as out-of-scope. An agent can distinguish this discovery/listing tool from horizon_get_leaderboard_top without opening either 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 'Use when' clauses (multiple boards, before submitting to learn leaderboardKey/validatedOnly) plus an explicit 'Not for' clause naming the three alternative tools for reading entries. This is the strongest form of routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server