Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@speedrun-mcp What's the current world record for Super Mario 64 16-star?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol server for speedrun.com — let an AI assistant query games, categories, leaderboards, world records, players and their personal bests, and (with an API key) submit and moderate runs.
"What's the current Super Mario 64 16-star world record, and who holds it?"
Built on speedrun.com's official REST API. The read tools need no account or API key — add a key (see Authenticated features) to unlock identity reads and, optionally, run submission and moderation. Results come back as compact, model-friendly JSON (player ids resolved to names, durations formatted, subcategory variables labeled).
Ask "the SM64 16-star world record?" and the model calls get_world_record,
which returns resolved JSON. An excerpt:
{
"game_name": "Super Mario 64",
"category_name": "16 Star",
"world_record": {
"players": ["Suigi"],
"time": "14m 35.5s",
"date": "2023-03-22",
"video": "https://youtu.be/1_vkwkniHuI"
}
}Related MCP server: Chess MCP Server
Tool | What it does |
| Fuzzy-search games by name → ids & abbreviations |
| A game's details plus its categories (and optionally levels) |
| A game's categories ( |
| Subcategory/filter variables and their value ids |
| Platform / region ids for the |
| A ranked leaderboard (top N; filter by variable / platform / region / timing) |
| The current #1 run for a game/category, plus any runs tied for first |
| Every category's records for a game in one call (defaults to world records) |
| Fuzzy-search game series (e.g. |
| A series' details and the games it contains |
| Find players by username (partial, fuzzy match) |
| A player's PBs across all games |
| Details of a single run |
| Runs filtered by player / game / category / status / examiner |
| A game's runs awaiting verification (the moderation queue) |
| The profile that owns your API key (only shown when a key is set) |
| Your speedrun.com notifications (only shown when a key is set) |
A typical flow: search_games → list_categories (and list_variables for
subcategories) → get_leaderboard / get_world_record. Use list_platforms /
list_regions when you need an id for the platform / region filters.
With write tools enabled (see below), submit_run, verify_run, reject_run,
set_run_players and delete_run are also available.
Search tools, list_runs, list_unverified_runs, and list_notifications return
an object with results, returned, offset, limit, has_more, and
next_offset. This replaces their earlier bare-list output. Pass next_offset
as offset to continue with the same filters. has_more: null means the API
omitted pagination metadata, so completeness is unknown. get_series.games
uses the same envelope; continue with game_offset.
pagination_note explains the continuation evidence: an API next-page link
can lead to an empty page and does not establish a total result count.
get_game_records follows all pages. Notifications scan up to scan_limit
source records and report scanned; an empty unread result is not evidence of
no unread notifications when has_more is true or unknown.
Run rows preserve account/guest identity in player_details, all video links
in videos, and separate source commentary in video_text. Personal-best rows
include game/category IDs, level, and raw variable choices. Variable details and
subcategory maps are keyed by variable ID to avoid collisions between names.
Leaderboard applied_filters includes the API's system filters and resolved
variables; requested_filters separately records the call's filters, including
historical dates. A missing requested timing is marked unavailable rather than
replaced by the primary time. Each displayed time identifies its source field.
returned_runs and omitted_from_response count rows from the fetched response,
not the full leaderboard.
Write errors that leave completion uncertain explicitly warn against automatic retries. A success response that cannot be parsed preserves its HTTP status and resource location when supplied.
Requires Python 3.10+.
# from PyPI
pipx install speedrun-mcp # or: uv tool install speedrun-mcp
# from source
git clone https://github.com/williamcodes/speedrun-mcp
cd speedrun-mcp
pip install -e .The server speaks MCP over stdio:
speedrun-mcp # console script
python -m speedrun_mcp # equivalentAdd to your MCP client config (e.g. claude_desktop_config.json):
{
"mcpServers": {
"speedrun": {
"command": "speedrun-mcp"
}
}
}If you installed from source into a virtualenv, point command at that
interpreter, e.g. "command": "/path/to/.venv/bin/speedrun-mcp".
For Claude Code:
claude mcp add speedrun -- speedrun-mcp
# with authenticated features (optional):
claude mcp add speedrun \
-e SPEEDRUN_API_KEY=your-key-here \
-e SPEEDRUN_ENABLE_WRITES=1 \
-- speedrun-mcpAn API key is entirely optional. With no key, the server exposes only the public read tools (leaderboards, games, players, the moderation queue) and works exactly as described above — no account required. Adding your key unlocks more:
Set this env var | Effect |
| Puts the server in read-only authenticated mode. Adds the identity reads — |
| Switches to read-write mode: arms the write tools so they actually submit/moderate. Requires |
Read-only is the default. Just adding a key never changes anything on speedrun.com — you get identity reads, and everything keeps working perfectly. If a write tool is invoked while writes are off, it doesn't silently fail; it returns:
This server is in read-only mode, so this write action is disabled. To allow run submission and moderation, set the environment variable SPEEDRUN_ENABLE_WRITES=1 (alongside SPEEDRUN_API_KEY) and restart the server.
So the way to switch to read-write mode is always discoverable from the error itself.
Log in to speedrun.com.
Go to your account settings.
In the left-hand nav, find the Developers section and click API Key.
Copy the key shown there.
Treat the key like a password — anyone who has it can act as you on speedrun.com. If it ever leaks, regenerate it from that same page.
Add the key to your MCP client config under env. It is read only from the
environment — never passed as a tool argument — so it can't leak into the
model's context or transcripts. Add SPEEDRUN_ENABLE_WRITES=1 only when you want
writes to actually run; with the key alone you stay safely read-only.
{
"mcpServers": {
"speedrun": {
"command": "speedrun-mcp",
"env": {
"SPEEDRUN_API_KEY": "your-key-here",
"SPEEDRUN_ENABLE_WRITES": "1"
}
}
}
}Or with Claude Code:
claude mcp add speedrun -e SPEEDRUN_API_KEY=your-key-here -- speedrun-mcp
# add -e SPEEDRUN_ENABLE_WRITES=1 as well if you want the write toolsKeep the key out of version control — put it in your client config or a local,
git-ignored .env, never in a committed file. All tools carry MCP read-only /
destructive hints so clients can flag the write and moderation actions.
Copy .env.example to .env and fill in the settings you need.
The template leaves the API key empty and disables writes. Git ignores .env.
The server reads exported environment variables and does not load .env
automatically. To load your local file and start the server from a shell:
set -a
. ./.env
set +a
speedrun-mcpReads need no key; writes are opt-in. Leaderboards, games, players and the
moderation queue are open reads. Run submission and moderation need
SPEEDRUN_API_KEY and SPEEDRUN_ENABLE_WRITES (see above).
Rate limit: speedrun.com allows 100 requests/minute per IP and responds with HTTP 420 when exceeded; the client surfaces a clear error if you hit it.
Game and category arguments accept either an id (o1y9wo6q) or an
abbreviation (sm64). For precise subcategory leaderboards (e.g. 16 Star),
discover the variable/value ids with list_variables and pass
variables={variable_id: value_id}.
Errors are explanatory. Invalid ids/filters raise an error that includes
speedrun.com's own message — e.g. passing a level to a full-game category
returns "The selected category is for full-game runs, but a level was selected."
Times reflect the leaderboard's sort timing. When you pass timing
(realtime / realtime_noloads / ingame), the reported time /
time_seconds match that ranking, not the game's default timing.
get_leaderboard returns returned_runs (the number of runs returned,
bounded by top and ties — not the full board size) and a runs list with
resolved player names, formatted times, and labeled subcategories.
get_world_record returns world_record (the place-1 run, or null if
the board is empty) plus tied (a list of any other runs sharing first place).
get_user_personal_bests returns returned (how many came back, capped by
limit) and total_available (the player's true PB count), plus the
personal_bests list with game/category names and resolved players.
The package uses a flat src/speedrun_mcp/ layout:
client.py handles HTTP requests, API errors, and pagination.
format.py converts API payloads into tool results without network access.
server.py owns MCP tools, configuration, and the shared client's lifecycle.
__main__.py provides the python -m speedrun_mcp entry point.
__init__.py exposes mcp on demand, so importing the client or format helpers
does not initialize the server.
Tests live in tests/. Unit tests cover each layer; package and MCP protocol
tests cover imports and startup. test_live.py contains the live API checks,
selected with the network marker.
pip install -e ".[dev]"
pre-commit install
# The checks run by CI:
ruff check .
ruff format --check .
mypy
pytest -m "not network"
# Apply safe lint fixes and formatting locally:
ruff check --fix .
ruff format .
# Optional: include live API tests.
pytestRuff checks source and tests for common bugs, security issues, async mistakes,
overly complex functions, and pytest mistakes. It also sorts imports and formats
Python code. Tests may use assert; the other lint rules apply to both source
and tests. Print and debugger statements are rejected because the server uses
stdout for the MCP protocol.
Ruff is pinned to the same version in the dev dependencies, its required-version
setting, and pre-commit. Update all three together. The hooks apply safe lint fixes
and formatting before running mypy; CI checks without changing files.
MIT
Get a game's details plus its categories (and optionally its levels).
The embedded categories give you the category_id needed for
get_leaderboard.
| Name | Required | Description | Default |
|---|---|---|---|
| game | Yes | Game id or abbreviation (e.g. 'sm64' or 'o1y9wo6q'). | |
| include_levels | No | Also include individual levels (for IL leaderboards). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds value by stating that the response embeds categories (and optionally levels), which is behavioral context beyond the schema. It does not repeat the read-only nature, which is appropriate. It does not describe the full response shape, but the core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. The primary purpose is front-loaded, and the follow-up sentence adds a practical usage tip. Every word earns its place, making it highly efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 params, no output schema). The description covers what is returned (details, categories, optional levels) and how to use the result (category_id for get_leaderboard). While the exact response structure is not spelled out, the description gives enough for an agent to make the correct call and use the output appropriately. It could be more explicit about the response fields, but for a read-only tool with clear purpose, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (game and include_levels) are already documented. The description mentions 'optionally its levels', reinforcing the include_levels parameter, but adds no new information beyond the schema's own description. Baseline 3 is appropriate because the schema already carries the semantic load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a game's details, its categories, and optionally its levels. It also explicitly connects the output to a downstream use (category_id for get_leaderboard), which differentiates it from siblings like search_games or list_categories. The verb and resource are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a concrete use case: obtaining the category_id needed for get_leaderboard. It implies this tool is the way to get a game's categories without needing a separate call, but it does not explicitly mention alternatives or exclusion criteria. There is clear context for when to use it, but no direct comparison with siblings like list_categories.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a game's records across all its categories in one call.
With top=1 (default) this is every category's world record at once —
handy for "show me all the records for ". include_levels=True also
pulls every individual-level board, which can be large for level-heavy games.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Places per category (1 = world records). | |
| game | Yes | Game id or abbreviation. | |
| include_levels | No | Include individual-level boards as well as full-game. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal readOnlyHint=true and openWorldHint=true, so the description carries a lower burden. It adds useful behavior beyond annotations: with top=1 it returns every category's world record at once, and include_levels=True can produce large responses for level-heavy games. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core behavior appears in the first sentence, followed by two short sentences explaining the top parameter and the include_levels size caveat. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, the schema describes all parameters, and annotations cover read-only/open-world behavior, the description is largely complete. It explains the default behavior and the main risk (level-heavy games producing large payloads). It stops short of describing the response shape, but that is a minor gap for a relatively straightforward list/records tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by clarifying the real-world meaning of top=1 ('every category's world record at once') and warning that include_levels=True 'pulls every individual-level board' and can be large. Game is simple enough that the schema already covers it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Get a game's records across all its categories in one call.' It clearly distinguishes this aggregate tool from siblings like get_world_record or get_leaderboard by emphasizing the all-categories-at-once scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear intended use case: 'handy for "show me all the records for <game>"' and explains the default top=1 behavior. It does not explicitly name alternatives like get_world_record or get_leaderboard or say when not to use them, but the context is clear enough for an agent to infer the right scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a ranked leaderboard for a game/category (full-game or individual level).
Players, subcategory labels and the category name are resolved for you. For
subcategory filters, discover ids with list_variables first.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Return the top N places. | |
| date | No | ISO date; only runs on or before this date. | |
| game | Yes | Game id or abbreviation. | |
| level | No | Level id for an individual-level (IL) leaderboard. | |
| region | No | Region id to filter by. | |
| timing | No | Sort by 'realtime', 'realtime_noloads', or 'ingame'. | |
| category | Yes | Category id or URL slug (e.g. '120_Star'). | |
| platform | No | Platform id to filter by. | |
| emulators | No | True = emulators only, False = real devices only. | |
| variables | No | Subcategory/variable filters as {variable_id: value_id}. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint and openWorldHint already declared, the description adds valuable behavior context: it states that players, subcategory labels, and category names are resolved automatically. This is genuinely useful beyond the annotations, though it stops short of describing pagination or response structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, with the core purpose front-loaded. Every sentence earns its place: the purpose, the resolution behavior, and the subcategory-filter prerequisite. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with a fully described 10-parameter schema, the description provides enough context to call it correctly: required game/category, optional level, and the workflow for variables. The main gap is not contrasting it with closely related leaderboard/list siblings, but the annotation and schema coverage carry much of the burden.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by linking 'full-game or individual level' to the level parameter and by explaining that subcategory filters require variable ids discovered via list_variables. This goes beyond the schema's bare descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource: a ranked leaderboard for a game/category, including full-game or individual level. It is unambiguous but does not explicitly distinguish it from similar siblings like get_world_record or get_game_records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a useful workflow hint: for subcategory filters, discover ids with list_variables first. However, it does not explain when to prefer get_leaderboard over get_world_record or get_game_records, nor does it state any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a run's players, times, game/category, status, system and variable values.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | The run's id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is clear. The description adds useful context about which fields are returned, but does not disclose response shape, pagination, or error behavior, which are not covered elsewhere.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise, well-structured sentence with no filler. It states the tool's purpose directly and front-loades the key output attributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-id tool with a single documented parameter and annotations covering read-only/open-world behavior, the description adequately lists the core returned fields. It lacks explicit notes on response format or error cases, but those are not essential for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single required parameter run_id is fully documented in the schema with 'The run's id.' The description adds no additional semantic information beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Get'), a specific resource ('a run'), and lists the exact attributes returned (players, times, game/category, status, system, variable values). This makes it easy to distinguish from sibling tools like list_runs or get_leaderboard.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool instead of alternatives such as list_runs or get_world_record, and it does not mention any exclusions or prerequisites. The intended usage is only implied by the tool name and parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a series' details and (by default) the games it contains.
The returned game ids/abbreviations feed the other tools (get_game,
list_categories, get_leaderboard).
| Name | Required | Description | Default |
|---|---|---|---|
| series | Yes | Series id or abbreviation. | |
| game_limit | No | Max games to list. | |
| game_offset | No | Start offset for the games page. | |
| include_games | No | Also list the games in the series. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. Description adds that games are included by default and that returned ids feed other tools, which is useful behavioral context beyond annotations. No mention of pagination or output format, but given annotations, this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main purpose, no redundant information. Efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with well-described schema and read-only annotations, the description covers the core use case and the relationship to downstream tools. Does not explicitly mention alternatives, but the context is sufficient for an agent to decide.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides full descriptions for all 4 parameters (100% coverage). Description adds minimal param semantics beyond 'by default' for include_games, which is already in schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Get) and resource (series) and clarifies that it also returns games by default. Differentiates from search_series (which searches) and get_game (which gets a game) by noting the ids feed other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage when you have a series id/abbreviation and need its games to feed into get_game, list_categories, get_leaderboard. Does not explicitly exclude alternatives but gives clear context. Lacks explicit 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a player's personal best runs across all games, with game/category names.
/personal-bests is unpaginated, so total_available is the player's true
PB count and returned is how many came back after applying limit.
| Name | Required | Description | Default |
|---|---|---|---|
| user | Yes | User id or exact username. | |
| limit | No | Max personal bests to return. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering safety and scope. The description adds valuable behavioral detail: it explains that the endpoint is unpaginated, clarifying the meaning of total_available vs returned after applying limit. This goes beyond annotations and helps the agent interpret results correctly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: the first sentence states the core purpose, and the second adds a crucial pagination caveat. There is no fluff; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description gives a reasonable outline of what is returned (personal bests with game/category names) and explains the pagination fields. It does not detail the full structure of each PB or error handling, but for a read-only, open-world tool this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (user and limit) are already well-documented. The description does not add additional meaning to the parameters themselves; it only references limit in the pagination note, which is more about output semantics. Baseline of 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'a player's personal best runs', and specifies that it spans all games and includes game/category names. It distinguishes this tool from siblings like get_game_records or list_runs, as it is uniquely focused on per-user personal bests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this is for fetching a user's PBs across all games, which implies when to use it. However, it does not explicitly mention alternatives or exclusion conditions, so it stops short of a 5. The context is clear enough that an agent can infer the appropriate use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current world record (place 1) for a game/category.
A convenience wrapper over get_leaderboard. Returns the leaderboard
metadata plus world_record (the single fastest run, or None if the
leaderboard is empty) and tied (any other runs also at place 1; usually
empty).
| Name | Required | Description | Default |
|---|---|---|---|
| game | Yes | Game id or abbreviation. | |
| level | No | Level id for an IL world record. | |
| category | Yes | Category id or URL slug (e.g. '120_Star'). | |
| variables | No | Subcategory/variable filters as {variable_id: value_id}. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint and openWorldHint already declared, the description adds meaningful behavioral detail beyond the annotations: it explains that world_record is the single fastest run, can be None for empty leaderboards, and that tied contains other place-1 runs. This is valuable because there is no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a one-sentence purpose, followed by the wrapper relationship and return semantics. Every sentence earns its place, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only convenience wrapper, the description covers the essential context: what it returns, the None case, the tie case, and its relationship to get_leaderboard. Combined with full schema coverage and read-only annotations, nothing critical is missing for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameters are fully documented in the input schema. The description does not add any parameter-specific semantics beyond naming game/category in the purpose statement, which matches the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Get the current world record (place 1) for a game/category.' It further distinguishes itself from get_leaderboard by framing itself as a 'convenience wrapper' that returns only the top-ranked run plus tie metadata. This is unambiguous and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly identifies get_leaderboard as the underlying alternative and implies this tool is the simpler choice for retrieving only the world record. It does not explicitly state when not to use it, but the wrapper framing provides clear context for the common decision.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a game's categories (e.g. 'Any%', '120 Star'), with their ids and rules.
| Name | Required | Description | Default |
|---|---|---|---|
| game | Yes | Game id or abbreviation. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to restate safety. It adds that the result includes ids and rules, which is useful. However, it does not disclose pagination, ordering, or whether categories include subcategories or miscellaneous flags, which would be relevant for a list endpoint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the action and resource, and includes concrete examples and return fields. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with one fully documented parameter and an output schema, the description is nearly complete. It could mention whether the result is paginated or if categories are ordered, but the output schema likely covers return structure. The annotations cover safety, so nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: the only parameter 'game' is described as 'Game id or abbreviation.' The description adds the context that the game's categories are being listed, but it does not add format or syntax details beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and resource ('a game's categories'), and gives concrete examples of category names ('Any%', '120 Star') plus what is returned ('ids and rules'). This clearly distinguishes it from sibling tools like list_variables or get_leaderboard.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for retrieving category metadata for a game, and the required 'game' parameter makes the context clear. It does not explicitly state when to use it over alternatives, but the sibling list is broad and the tool's narrow scope is evident. A small deduction for not naming alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List speedrun.com platforms (consoles/systems) with their ids and names.
Use a returned id as the platform filter for get_leaderboard
(the leaderboard API requires the platform id, not its name).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, so the safe, read-only nature is established. The description adds useful behavioral context by revealing that the returned ids are meaningful to get_leaderboard and that names are insufficient there, which goes beyond the bare schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler: the first states the purpose and return fields, the second gives the critical usage note. The essential id-versus-name warning is front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless, read-only list tool with an output schema and annotations, the description is complete. It tells the agent what is returned, how to use those results, and why names alone are insufficient—nothing needed for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the input schema is empty, so there is nothing for the description to explain. Per the rubric, 0 params warrants a baseline of 4; the description appropriately avoids inventing parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List speedrun.com platforms (consoles/systems) with their ids and names.' It clearly distinguishes this from its siblings by positioning it as the platform-listing tool, and the companion instruction about using ids for get_leaderboard reinforces its role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains how to consume the output: use the returned id as the platform filter for get_leaderboard. It also gives a concrete exclusion—use the id, not the name—which prevents a common misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List speedrun.com regions (e.g. USA/NTSC, EUR/PAL) with their ids and names.
Use a returned id as the region filter for get_leaderboard
(the leaderboard API requires the region id, not its name).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and open world. The description adds context that the returned ids are used for leaderboard filtering, which is helpful but not a behavioral disclosure about the tool itself. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the primary function, followed by a usage note. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with an output schema present, the description fully explains the purpose and how to use the output (id for leaderboard). No missing information needed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty (no parameters), so the description does not need to explain parameters. Baseline 4 for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States specifically that it lists speedrun.com regions with ids and names. The verb 'list' and resource 'regions' are clear, and it distinguishes from siblings which target different resources (games, categories, etc.).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a concrete usage example: using the returned id as the region filter for get_leaderboard, and notes that the leaderboard API requires the id, not the name. However, it does not explicitly state when to use this tool vs alternatives, though the alternatives are for different resources.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List runs with filters — e.g. a player's recent submissions, or a game's verified/rejected runs. Newest first; combine filters to narrow down.
For just one game's moderation queue, list_unverified_runs is simpler.
| Name | Required | Description | Default |
|---|---|---|---|
| game | No | Filter to a game (id or abbreviation). | |
| user | No | Filter to a player's runs (user id or username). | |
| limit | No | Max runs to return. | |
| offset | No | Start offset; use next_offset to continue. | |
| status | No | Filter by status: 'new', 'verified', or 'rejected'. | |
| category | No | Filter to a category id. | |
| examiner | No | Filter to runs examined by this user id or username. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds the behavioral detail 'Newest first' (ordering) and notes that filters can be combined to narrow results. It does not contradict annotations and adds useful context beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short paragraphs, each earning its place. The first sentence states the core purpose and examples; the second provides a targeted alternative. No fluff or redundancy, and the key differentiator is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with 7 optional parameters and no output schema, the description covers ordering, filtering, and an alternative. It doesn't explain pagination, but the schema includes offset and next_offset, and the lack of an output schema is acceptable. It could mention AND semantics of combining filters, but 'narrow down' implies that. Overall, complete enough for an agent to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is documented with its own description. The tool description does not add new parameter-specific meaning, only illustrates usage with examples. Baseline of 3 is appropriate because the schema already handles parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('runs') and provides concrete examples (player's recent submissions, game's verified/rejected runs). It also distinguishes itself from the sibling 'list_unverified_runs' by naming the simpler alternative for a single game's moderation queue, so an agent can tell them apart without reading schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly names an alternative tool ('list_unverified_runs') and the condition under which it is simpler (for one game's moderation queue). This provides clear when-to-use and when-not-to-use guidance, and the examples illustrate typical use cases for this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a game's runs awaiting verification — the moderation queue.
A public read (no API key needed). Pair with verify_run / reject_run
(which do require a moderator key) to clear the queue.
| Name | Required | Description | Default |
|---|---|---|---|
| game | Yes | Game id or abbreviation. | |
| limit | No | Max runs to return. | |
| offset | No | Start offset; use next_offset to continue. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds that no API key is needed, which is valuable auth context not present in annotations. It also reinforces the read-only nature with 'public read.' No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first states the core purpose immediately, and the second adds auth context and pairing suggestions. Every word earns its place; no fluff or redundancy. Excellent structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that annotations cover read-only and open-world hints, and the schema fully documents parameters, the description covers the essential purpose, auth requirements, and the moderation workflow. There is no output schema, so return details are not required. The only minor gap is that it doesn't mention pagination behavior, but the schema's offset description already covers next_offset.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all three parameters (game, limit, offset), each with clear descriptions. The tool description does not add any parameter-specific details beyond what the schema already provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists 'a game's runs awaiting verification — the moderation queue.' This is a specific verb and resource, and it distinguishes this from the general list_runs sibling by focusing on unverified runs. However, it does not explicitly contrast with list_runs, so it loses a point for not naming the alternative, though the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes that it's 'a public read (no API key needed)' and suggests pairing with verify_run/reject_run to clear the queue. This gives clear context for when to use it (moderation workflow). It does not explicitly state when not to use it or mention alternatives like list_runs, but the intended use case is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a game's variables — the subcategories and filters a leaderboard accepts.
Each variable has an id and a values map of {value_id: label}. Pass these
to get_leaderboard/get_world_record as variables={variable_id: value_id}
to target a specific subcategory (e.g. '16 Star', difficulty 'Hard').
| Name | Required | Description | Default |
|---|---|---|---|
| game | Yes | Game id or abbreviation. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds valuable context beyond the annotations by explaining the values map structure and how the returned ids are consumed by other tools, which helps the agent understand the behavioral role of the output even without inspecting the output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. The first sentence front-loads the core purpose, and the second adds the essential data shape and cross-tool usage in compact, well-formatted code spans. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read-only list tool with an output schema and annotations, the description is complete. It explains what variables are, what each entry contains, and how to use the result with sibling leaderboard tools, leaving no critical gaps for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the single 'game' parameter with 'Game id or abbreviation.' The description does not add parameter-specific semantics beyond implying the game context, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'List a game's variables', and defines them as 'the subcategories and filters a leaderboard accepts.' This clearly distinguishes the tool from siblings like list_categories and get_leaderboard by explaining what variables are and how they relate to leaderboards.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete downstream usage: 'Pass these to get_leaderboard/get_world_record as variables={variable_id: value_id} to target a specific subcategory.' This is clear contextual guidance, though it does not explicitly contrast with list_categories or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fuzzy-search games by name. Returns ids, abbreviations and release years.
Use the returned id (or abbreviation) with the other tools.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Game title or partial title containing a Latin letter or ASCII digit. | |
| limit | No | Max games to return. | |
| offset | No | Start offset; use next_offset to continue. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint and openWorldHint, so the safety profile is known. The description adds meaningful behavioral context by revealing fuzzy matching behavior and the exact return fields, plus the integration pattern of using the returned id with other tools. It does not discuss rate limits or pagination, but the schema covers pagination parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and well-structured: one sentence states purpose and return values, and a second sentence gives downstream usage guidance. There is no redundant or filler content, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with annotations and a fully documented schema, the description is largely complete: it names the search behavior, return fields, and how to use the result. Since there is no output schema, it could have been slightly richer about the response shape, but the listed return fields are sufficient for selecting and invoking the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the name, limit, and offset parameters. The description adds little about parameter semantics beyond mentioning search by name; it does not elaborate on limit or offset behavior, which is already provided in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Fuzzy-search games by name.' It also distinguishes the tool from siblings like search_users and search_series by specifying games and game-specific return fields (ids, abbreviations, release years). This makes the tool's purpose immediately identifiable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when an agent needs to find a game by name, and it explains how to use the returned id/abbreviation with other tools. However, it does not explicitly state when to prefer this tool over alternatives like search_series or search_users, nor does it mention exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fuzzy-search game series (e.g. 'Mario', 'Zelda') by name.
A series groups related games; pass a returned id to get_series to list
the games it contains.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Series title or partial title containing a Latin letter or ASCII digit. | |
| limit | No | Max series to return. | |
| offset | No | Start offset; use next_offset to continue. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety/exploratory profile is covered. The description adds useful behavior—fuzzy matching and the series-groups-games relationship—but does not describe sorting, pagination, or return shape. This is acceptable given the annotations and simple search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with the purpose front-loaded. The second sentence earns its place by explaining the series model and pointing to the next step. There is no filler or redundant restatement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool with one required parameter and optional limit/offset, the description is sufficient to invoke it and interpret the result (returned id → get_series). A note about the return value structure would make it complete, but nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters. The description reinforces that name is a partial/fuzzy title, but it adds no new semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('fuzzy-search') and resource ('game series') with concrete examples ('Mario', 'Zelda'). It clearly distinguishes itself from search_games at the resource level and connects to get_series as the natural follow-up.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear task context: use search_series to find a series, then pass the returned id to get_series to list contained games. It does not explicitly state when not to use it (e.g., for searching individual games), so it falls just short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for speedrun.com users by name. Returns ids, countries and signup dates.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Username (or partial), at least 3 characters. | |
| limit | No | Max users to return. | |
| offset | No | Start offset; use next_offset to continue. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and openWorldHint. The description adds return field details (ids, countries, signup dates) beyond annotations. It does not mention pagination behavior, but that is covered in the schema. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with purpose and return fields, zero fluff. Perfectly sized for a simple search tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description mentions return fields. Pagination is documented in the schema, and annotations cover open-world and read-only aspects. It could explicitly state it returns a list, but this is implied for a search tool. Completeness is adequate for the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are well-documented. The description adds no additional parameter semantics beyond the schema, only implying the 'name' parameter via 'by name'. No compensation needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Search' and the resource 'speedrun.com users', distinguishing it from sibling search_games and search_series by specifying the entity type. Also mentions return fields (ids, countries, signup dates), which further clarifies its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use vs alternatives. The description implies it is for user searches, but does not mention when not to use it or contrast with search_games or search_series. The agent must infer from the resource type.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.2get_gameget_game_recordsget_leaderboardget_runget_seriesget_user_personal_bestsget_world_recordlist_categorieslist_platformslist_regionslist_runslist_unverified_runslist_variablessearch_gamessearch_seriessearch_usersScored across 16 tools
Most tools target a distinct resource/action such as games, categories, variables, leaderboards, users, runs, platforms, regions, and series. The main overlap is that get_game already returns categories and get_world_record is a wrapper over get_leaderboard, but the descriptions clarify when each should be used.
All tool names consistently follow a snake_case verb_noun pattern using only search, get, and list as verbs. Multiword nouns like get_user_personal_bests and get_game_records remain predictable and no mixed conventions appear.
Sixteen tools is slightly above the typical ideal range, but each tool covers a distinct read-only aspect of the speedrun.com API. The count feels reasonable for the domain, with only a few convenience helpers adding mild extra weight.
Core discovery and leaderboard workflows are well covered: searching games and users, retrieving game details, categories, variables, leaderboards, world records, runs, platforms, regions, and series. However, list_unverified_runs references verify_run/reject_run that are not included in the tool set, leaving a moderation dead end, and there is no direct user profile lookup beyond personal bests.
Query your Twitch streams, events, supporters, raids & rankings from an AI assistant via OAuth.
Enables AI assistants to natively interact with the Serpzilla link-building marketplace.
Query your SEO data in plain language: rankings, audits, backlinks, competitors and AI visibility.
Provides AI assistants with access to Seltz's powerful Web Search capabilities.
