Tools reference
Your assistant picks these for you, so you rarely need this page. It is here for checking what a tool does, and for building on the server. All 18 tools return JSON. Game ids come from list_my_games.
| Permission | Tools |
|---|---|
games:read |
list_my_games, get_game, list_categories, search_universes, get_verification_steps, get_sdk_status |
stats:read |
get_audience, get_retention, get_results, get_realtime |
games:write |
create_game, update_game, set_game_thumbnail, verify_domain_and_submit, claim_game, resubmit_game, verify_badge, delete_game |
Reading your games
Section titled “Reading your games”list_my_games
Section titled “list_my_games”The games this account owns or co-manages through a studio, most recently changed first, each with what to do next.
| Input | Type | Notes |
|---|---|---|
status |
draft, pending, approved or rejected |
Optional. pending also finds live games with an update in review |
limit |
1 to 100 | Default 50 |
offset |
Number | Default 0 |
Returns total and games, each with id, name, status, url, domainVerified, changesInReview and nextStep.
get_game
Section titled “get_game”Everything about one of your games: its settings, changes waiting for review, why it was rejected, and what to do next.
| Input | Type | Notes |
|---|---|---|
game_id |
String | Required |
Returns its details, including nextStep, rejectionReason, pendingChanges, domainVerified, badgeVerified, sdkLastSeenAt, pageUrl (once live) and dashboardUrl.
list_categories
Section titled “list_categories”The categories a game can belong to. create_game needs one of these ids. It takes no input, and returns id, name and description for each.
search_universes
Section titled “search_universes”Finds a universe: the franchise or world a game is drawn from, such as Pokémon or the NBA. A studio or author is never a universe, and most games have none.
| Input | Type | Notes |
|---|---|---|
query |
2 to 80 characters | Required. Accents are ignored |
Returns up to 20 matches, each with id, name and type.
get_verification_steps
Section titled “get_verification_steps”What to add to the game’s site to prove it is yours: a meta tag or a DNS record. Nothing changes until you call verify_domain_and_submit.
| Input | Type | Notes |
|---|---|---|
game_id |
String | Required |
Returns token, host, metaTag and dnsRecord (name, type, value).
get_sdk_status
Section titled “get_sdk_status”Whether the game reports results to Alldle, with the code to install. Rounds played from localhost show as “test” and are never counted.
| Input | Type | Notes |
|---|---|---|
game_id |
String | Required |
| Returned | Meaning |
|---|---|
connected |
True once the game has ever reported from somewhere other than localhost |
lastSeenAt |
The last report, localhost aside. Read this to know whether it is reporting now |
roundsLastWeek |
Rounds in the last 7 days per source, as source and rounds, with test and unfinished rounds included |
declaredModes, undeclaredModes |
Modes you declared, and those reported without being declared |
sdkVersions, onOldSdk |
Versions seen, and whether it is still on 0.1 |
install |
The script tag, the reporting line and the link to the docs, filled in for this game |
Reading your numbers
Section titled “Reading your numbers”These run one at a time per account, and repeating a question within 30 seconds returns the same answer. Without sections, they return a summary.
get_audience
Section titled “get_audience”Who visits and plays your games: totals only, never individual players. See The audience dashboard for what the numbers mean.
| Input | Type | Notes |
|---|---|---|
game_id |
String | Optional. Leave out for all your games |
period |
today, 24h, 7d, 30d, 90d, 12mo or all |
Default 30d |
sections |
List | Optional. timeseries, countries, cities, sources, devices, browsers, systems (returned as operatingSystems), languages, games, heatmap, frequency |
rows |
1 to 50 | Rows per section, largest first. Default 5 |
Returns summary, range, timezone, ritualMembers, your requested sections, dataSince and comparableWithPrevious. The comparison is left empty when the previous period reaches back before data existed.
get_retention
Section titled “get_retention”How many players of one game come back.
| Input | Type | Notes |
|---|---|---|
game_id |
String | Required |
Returns nextDay, withinWeek and dayThirty, each with rate and base, plus stickiness, dailyPlayers, monthlyPlayers and weekly cohorts.
get_results
Section titled “get_results”How players do in one game, from the SDK. It is empty until the SDK is installed.
| Input | Type | Notes |
|---|---|---|
game_id |
String | Required |
period |
Same as get_audience |
Default 30d |
sections |
List | Optional. modes, puzzles, sources, timeseries |
rows |
1 to 50 | Rows per section. Default 5 |
Returns summary with rounds, players, winRate, averageAttempts, averageDurationMs and completionRate, plus everReported, dataSince and your requested sections.
get_realtime
Section titled “get_realtime”How many people are on your games right now, with the last 30 minutes by country and by game. Totals only.
| Input | Type | Notes |
|---|---|---|
game_id |
String | Optional. Leave out for all your games |
Returns visitors and plays for the last 5 minutes. countries and games cover the last 30 minutes, so they can show someone even when visitors is 0.
Changing things
Section titled “Changing things”create_game
Section titled “create_game”Lists a game hosted on your own site, as a draft. Nothing is public yet. Repeating the call with the same address returns the same game. At most 10 new games a day.
| Input | Type | Notes |
|---|---|---|
name |
At most 50 characters | Required |
description |
String | Required |
url |
https:// address |
Required. On a site you control |
categoryId |
From list_categories |
Required |
isUnlimited |
Boolean | Required. false for one puzzle a day |
howToPlay |
At most 1,200 characters | Optional. Plain text |
languages |
List of codes, such as en |
Optional |
socialLinks |
Keys such as website, twitter, discord |
Optional |
universeId |
From search_universes |
Optional |
universeRequest |
At most 80 characters | Optional. A universe that search did not find |
Returns outcome, which is one of:
created, with the newgamealready-added, with your existinggamealready-listed, withgameIdandverificationSteps: the address is listed with no owner, so claim it
update_game
Section titled “update_game”Changes the given fields and leaves the rest alone.
| Input | Type | Notes |
|---|---|---|
game_id |
String | Required |
name, description, url, categoryId, isUnlimited, languages, socialLinks |
As in create_game |
Optional |
howToPlay, universeId, universeRequest |
As in create_game, or null to clear |
Optional |
modes |
List of strings | Optional. Applies at once, even on a live game |
Returns pendingReview, verificationReset, game, and a next hint if the game moved to another site. See what applies when.
set_game_thumbnail
Section titled “set_game_thumbnail”Fetches an image from a public address and hosts it on Alldle. For a file on your computer, use the Edit page. On a live game, the new image waits for review.
| Input | Type | Notes |
|---|---|---|
game_id |
String | Required |
image_url |
Public https:// address |
Required. PNG, JPEG, GIF or WebP, up to 5 MB |
Returns thumbnailUrl and pendingReview.
verify_domain_and_submit
Section titled “verify_domain_and_submit”Checks the site for the meta tag or DNS record. If it is there, a draft goes into the review queue and you get an email, so call it only when the game is ready. If it is not there, nothing changes and the result says so.
| Input | Type | Notes |
|---|---|---|
game_id |
String | Required |
Returns verified, method (meta-tag or dns) and sentForReview.
claim_game
Section titled “claim_game”Takes ownership of a game already listed with no owner, once its site carries the meta tag or DNS record.
| Input | Type | Notes |
|---|---|---|
game_id |
String | Required. Given by create_game when it finds such a listing |
Returns owner and method.
resubmit_game
Section titled “resubmit_game”Sends a rejected game back to review. Attempts are limited, so make the fix first. Calling it on a game already in review changes nothing.
| Input | Type | Notes |
|---|---|---|
game_id |
String | Required |
Returns status and alreadyInReview.
verify_badge
Section titled “verify_badge”Checks that the “Play on Alldle” badge is on the game’s page, which lists it among the community partners. See The badge.
| Input | Type | Notes |
|---|---|---|
game_id |
String | Required |
variant |
dark-compact-logo, dark-compact-text, dark-large-logo, dark-large-text, light-compact-logo, light-compact-text, light-large-logo, light-large-text |
Required |
Returns verified and variant.
delete_game
Section titled “delete_game”Permanently deletes a draft or a game still in review. A live game cannot be deleted this way.
| Input | Type | Notes |
|---|---|---|
game_id |
String | Required |
confirm_name |
String | Required. The game’s exact name, as a check that this is the right game |
Returns deleted and name.
The server
Section titled “The server”| Property | Value |
|---|---|
| Address | https://api.alldle.net/mcp |
| Transport | Streamable HTTP, answering in JSON |
| Sign-in | OAuth, with a metadata document or dynamic registration |
| Resources, prompts, subscriptions | None. It offers tools only |