ping

Health check. Returns a static confirmation that the Turnale MCP server is reachable.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

create_tournament

Create a new tournament. Keep setup SHORT: ask the organiser only for sport, players, court count and start time — sensible defaults cover everything else. FORMAT: never ask an open 'which format?' question. If the organiser clearly named one, pass it; otherwise omit format — the call then returns a ready-to-show menu of options (nothing is created) for you to relay so the organiser can read and choose in one reply. Players can be added later with add_players. NEVER invent placeholder or fake player names ('Player 1', made-up names): if the organiser only knows the headcount, create with signup_open: true and signup_cap set to it — players add themselves by name via the page link. If the organiser gives a time budget instead of rounds (e.g. 'we have 2 hours'), derive rounds ≈ total minutes ÷ (match + break minutes) and confirm. If they ask for a format that is not listed, offer to note it with record_feedback. Returns the organiser key (tk_…): relay it with the warning that it cannot be recovered, plus the shareable page link.

Parameters23

sport	string	required
format	string	optional	Tournament format. round_robin: everyone plays everyone. groups_playoff: round-robin groups then a knockout. single_elimination: knockout with byes. americano/mexicano: rotating-partner doubles, points per round (mexicano pairs each round from standings). OMIT when the organiser hasn't clearly chosen — the call then returns a menu of explained options to show them instead of creating anything.
name	string	optional	Defaults to '<Sport> tournament <date>'
discipline	string	optional	Default singles; americano/mexicano are always doubles
players	array	optional
pairs	array	optional	Doubles: fixed pairs as [name, name] arrays. Omit to auto-pair.
courts	integer	optional	Default 2
court_names	array	optional
start_time	string	optional	ISO datetime with offset, e.g. 2026-08-01T18:00:00+03:00. Must be within 365 days from today.
match_duration_minutes	integer	optional
break_minutes	integer	optional	Changeover between matches/rounds, shown separately from play time (default 0)
page_results_entry	boolean	optional	Allow anyone with the page link to enter scores courtside. Default false; switchable any time via update_settings or the toggle on the page.
language	string	optional	Language of the tournament page, PDFs and player emails. Default en; set et when the organiser works in Estonian.
seeding	string	optional	Default random
group_count	integer	optional
advance_per_group	integer	optional
third_place_match	boolean	optional	Single elimination; default true
points_per_match	integer	optional	Americano/mexicano; default 21
rounds	integer	optional	Americano/mexicano; default from player count
location	string	optional	Venue/location shown to players on the page, e.g. club name + city
house_rules	array	optional	Organiser's house rules, shown on the tournament page (e.g. 'Golden point at deuce')
signup_open	boolean	optional	Open self-signup: players add themselves on the shared page (name-only or signed in). Offer this when the organiser has no player list yet.
signup_cap	integer	optional	Signup limit; beyond it players join a waitlist

Raw schema

{
  "type": "object",
  "properties": {
    "sport": {
      "type": "string",
      "enum": [
        "tennis",
        "padel",
        "pickleball",
        "badminton",
        "squash",
        "table_tennis"
      ]
    },
    "format": {
      "description": "Tournament format. round_robin: everyone plays everyone. groups_playoff: round-robin groups then a knockout. single_elimination: knockout with byes. americano/mexicano: rotating-partner doubles, points per round (mexicano pairs each round from standings). OMIT when the organiser hasn't clearly chosen — the call then returns a menu of explained options to show them instead of creating anything.",
      "type": "string",
      "enum": [
        "round_robin",
        "groups_playoff",
        "single_elimination",
        "americano",
        "mexicano"
      ]
    },
    "name": {
      "description": "Defaults to '<Sport> tournament <date>'",
      "type": "string",
      "maxLength": 120
    },
    "discipline": {
      "description": "Default singles; americano/mexicano are always doubles",
      "type": "string",
      "enum": [
        "singles",
        "doubles"
      ]
    },
    "players": {
      "maxItems": 128,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "gender": {
            "type": "string",
            "enum": [
              "m",
              "f",
              "x"
            ]
          },
          "level": {
            "type": "number",
            "minimum": -10000,
            "maximum": 10000,
            "description": "Any consistent numeric level/rating — used only for seeding and balancing"
          }
        },
        "required": [
          "name"
        ]
      }
    },
    "pairs": {
      "description": "Doubles: fixed pairs as [name, name] arrays. Omit to auto-pair.",
      "type": "array",
      "items": {
        "minItems": 2,
        "maxItems": 2,
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    },
    "courts": {
      "description": "Default 2",
      "type": "integer",
      "minimum": 1,
      "maximum": 16
    },
    "court_names": {
      "maxItems": 16,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 60
      }
    },
    "start_time": {
      "description": "ISO datetime with offset, e.g. 2026-08-01T18:00:00+03:00. Must be within 365 days from today.",
      "type": "string"
    },
    "match_duration_minutes": {
      "type": "integer",
      "minimum": 5,
      "maximum": 240
    },
    "break_minutes": {
      "description": "Changeover between matches/rounds, shown separately from play time (default 0)",
      "type": "integer",
      "minimum": 0,
      "maximum": 60
    },
    "page_results_entry": {
      "description": "Allow anyone with the page link to enter scores courtside. Default false; switchable any time via update_settings or the toggle on the page.",
      "type": "boolean"
    },
    "language": {
      "description": "Language of the tournament page, PDFs and player emails. Default en; set et when the organiser works in Estonian.",
      "type": "string",
      "enum": [
        "en",
        "et"
      ]
    },
    "seeding": {
      "description": "Default random",
      "type": "string",
      "enum": [
        "random",
        "level"
      ]
    },
    "group_count": {
      "type": "integer",
      "minimum": 2,
      "maximum": 8
    },
    "advance_per_group": {
      "type": "integer",
      "minimum": 1,
      "maximum": 4
    },
    "third_place_match": {
      "description": "Single elimination; default true",
      "type": "boolean"
    },
    "points_per_match": {
      "description": "Americano/mexicano; default 21",
      "type": "integer",
      "minimum": 4,
      "maximum": 64
    },
    "rounds": {
      "description": "Americano/mexicano; default from player count",
      "type": "integer",
      "minimum": 1,
      "maximum": 30
    },
    "location": {
      "description": "Venue/location shown to players on the page, e.g. club name + city",
      "type": "string",
      "maxLength": 160
    },
    "house_rules": {
      "description": "Organiser's house rules, shown on the tournament page (e.g. 'Golden point at deuce')",
      "maxItems": 12,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      }
    },
    "signup_open": {
      "description": "Open self-signup: players add themselves on the shared page (name-only or signed in). Offer this when the organiser has no player list yet.",
      "type": "boolean"
    },
    "signup_cap": {
      "description": "Signup limit; beyond it players join a waitlist",
      "type": "integer",
      "minimum": 4,
      "maximum": 128
    }
  },
  "required": [
    "sport"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

add_players

Add players to the roster in bulk (parse pasted lists or spreadsheets yourself and send structured entries — never invent placeholder names; use signup mode when names aren't known yet). Duplicate names are rejected for disambiguation. If an unlocked draw exists it is regenerated automatically.

Parameters3

tournament_key	string	required	The tournament's organiser key (starts with tk_)
players	array	required
request_id	string	optional	Optional idempotency id — retrying a call with the same id never applies it twice

Raw schema

{
  "type": "object",
  "properties": {
    "tournament_key": {
      "type": "string",
      "description": "The tournament's organiser key (starts with tk_)"
    },
    "players": {
      "minItems": 1,
      "maxItems": 128,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "gender": {
            "type": "string",
            "enum": [
              "m",
              "f",
              "x"
            ]
          },
          "level": {
            "type": "number",
            "minimum": -10000,
            "maximum": 10000,
            "description": "Any consistent numeric level/rating — used only for seeding and balancing"
          }
        },
        "required": [
          "name"
        ]
      }
    },
    "request_id": {
      "description": "Optional idempotency id — retrying a call with the same id never applies it twice",
      "type": "string",
      "maxLength": 64
    }
  },
  "required": [
    "tournament_key",
    "players"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

update_player

Rename a player or set their gender/level/note.

Parameters6

tournament_key	string	required	The tournament's organiser key (starts with tk_)
player_name	string	required
new_name	string	optional
gender	string	optional
level	number	optional	Any consistent numeric level/rating — used only for seeding and balancing
request_id	string	optional	Optional idempotency id — retrying a call with the same id never applies it twice

Raw schema

{
  "type": "object",
  "properties": {
    "tournament_key": {
      "type": "string",
      "description": "The tournament's organiser key (starts with tk_)"
    },
    "player_name": {
      "type": "string"
    },
    "new_name": {
      "type": "string",
      "maxLength": 120
    },
    "gender": {
      "type": "string",
      "enum": [
        "m",
        "f",
        "x"
      ]
    },
    "level": {
      "type": "number",
      "minimum": -10000,
      "maximum": 10000,
      "description": "Any consistent numeric level/rating — used only for seeding and balancing"
    },
    "request_id": {
      "description": "Optional idempotency id — retrying a call with the same id never applies it twice",
      "type": "string",
      "maxLength": 64
    }
  },
  "required": [
    "tournament_key",
    "player_name"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

remove_player

Remove one or MANY players before any result is recorded (afterwards use withdraw_player or replace_player) — pass player_names to clear several in one call, never loop one-by-one. Regenerates an existing unlocked draw.

Parameters4

tournament_key	string	required	The tournament's organiser key (starts with tk_)
player_name	string	optional
player_names	array	optional	Bulk removal — e.g. clearing mistaken placeholder names in one call
request_id	string	optional	Optional idempotency id — retrying a call with the same id never applies it twice

Raw schema

{
  "type": "object",
  "properties": {
    "tournament_key": {
      "type": "string",
      "description": "The tournament's organiser key (starts with tk_)"
    },
    "player_name": {
      "type": "string"
    },
    "player_names": {
      "description": "Bulk removal — e.g. clearing mistaken placeholder names in one call",
      "minItems": 1,
      "maxItems": 128,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "request_id": {
      "description": "Optional idempotency id — retrying a call with the same id never applies it twice",
      "type": "string",
      "maxLength": 64
    }
  },
  "required": [
    "tournament_key"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

set_pairs

Fix the doubles pairs: pass explicit pairs by name, or auto-pair (random or level-balanced). Only before results exist. Regenerates an existing unlocked draw.

Parameters4

tournament_key	string	required	The tournament's organiser key (starts with tk_)
pairs	array	optional	Fixed pairs as [name, name] arrays
auto	string	optional
request_id	string	optional	Optional idempotency id — retrying a call with the same id never applies it twice

Raw schema

{
  "type": "object",
  "properties": {
    "tournament_key": {
      "type": "string",
      "description": "The tournament's organiser key (starts with tk_)"
    },
    "pairs": {
      "description": "Fixed pairs as [name, name] arrays",
      "type": "array",
      "items": {
        "minItems": 2,
        "maxItems": 2,
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    },
    "auto": {
      "type": "string",
      "enum": [
        "random",
        "level_balanced"
      ]
    },
    "request_id": {
      "description": "Optional idempotency id — retrying a call with the same id never applies it twice",
      "type": "string",
      "maxLength": 64
    }
  },
  "required": [
    "tournament_key"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

update_settings

Change the tournament name, start time, match duration, break/changeover minutes, courts (count or names), house rules, or courtside score entry from the page. Court changes recompute the remaining schedule; played matches never move.

Parameters14

tournament_key	string	required	The tournament's organiser key (starts with tk_)
name	string	optional
start_time	string	optional	ISO datetime with offset. Must be within 365 days from today.
match_duration_minutes	integer	optional
break_minutes	integer	optional	Changeover between matches/rounds, shown separately from play time
courts	integer	optional
court_names	array	optional
house_rules	array	optional
location	string	optional	Venue/location shown to players; pass an empty string to clear it
page_results_entry	boolean	optional	Allow anyone with the page link to enter scores courtside (off by default)
signup_open	boolean	optional	Open or close self-signup on the page
signup_cap	integer	optional
language	string	optional	Page/PDF/email language: en (default) or et
request_id	string	optional	Optional idempotency id — retrying a call with the same id never applies it twice

Raw schema

{
  "type": "object",
  "properties": {
    "tournament_key": {
      "type": "string",
      "description": "The tournament's organiser key (starts with tk_)"
    },
    "name": {
      "type": "string",
      "maxLength": 120
    },
    "start_time": {
      "description": "ISO datetime with offset. Must be within 365 days from today.",
      "type": "string"
    },
    "match_duration_minutes": {
      "type": "integer",
      "minimum": 5,
      "maximum": 240
    },
    "break_minutes": {
      "description": "Changeover between matches/rounds, shown separately from play time",
      "type": "integer",
      "minimum": 0,
      "maximum": 60
    },
    "courts": {
      "type": "integer",
      "minimum": 1,
      "maximum": 16
    },
    "court_names": {
      "maxItems": 16,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 60
      }
    },
    "house_rules": {
      "maxItems": 12,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      }
    },
    "location": {
      "description": "Venue/location shown to players; pass an empty string to clear it",
      "type": "string",
      "maxLength": 160
    },
    "page_results_entry": {
      "description": "Allow anyone with the page link to enter scores courtside (off by default)",
      "type": "boolean"
    },
    "signup_open": {
      "description": "Open or close self-signup on the page",
      "type": "boolean"
    },
    "signup_cap": {
      "type": "integer",
      "minimum": 4,
      "maximum": 128
    },
    "language": {
      "description": "Page/PDF/email language: en (default) or et",
      "type": "string",
      "enum": [
        "en",
        "et"
      ]
    },
    "request_id": {
      "description": "Optional idempotency id — retrying a call with the same id never applies it twice",
      "type": "string",
      "maxLength": 64
    }
  },
  "required": [
    "tournament_key"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

promote_player

Move a waitlisted player onto the active roster when a spot opens (signed-in players are notified by email). The cap can be raised with update_settings.

Parameters3

tournament_key	string	required	The tournament's organiser key (starts with tk_)
name	string	required
request_id	string	optional	Optional idempotency id — retrying a call with the same id never applies it twice

Raw schema

{
  "type": "object",
  "properties": {
    "tournament_key": {
      "type": "string",
      "description": "The tournament's organiser key (starts with tk_)"
    },
    "name": {
      "type": "string"
    },
    "request_id": {
      "description": "Optional idempotency id — retrying a call with the same id never applies it twice",
      "type": "string",
      "maxLength": 64
    }
  },
  "required": [
    "tournament_key",
    "name"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

generate_draw

Generate (or regenerate) the draw and schedule. This IS the start action: the first draw moves the tournament from setup to active and closes self-signup — when the organiser says "start the tournament", call this. The result includes rounds_text — SHOW it to the organiser as-is (translated to their language) so they can check who plays whom — and the seed that produced the draw: preview first, then confirm with that SAME seed to apply exactly the previewed draw. Free until the first result is recorded; after that this DISCARDS recorded results and requires BOTH confirm: true and discard_results: true. If the organiser asks for a format that is not supported, offer to note it with record_feedback. Optional overrides adjust the format first.

Parameters11

tournament_key	string	required	The tournament's organiser key (starts with tk_)
seeding	string	optional
group_count	integer	optional
advance_per_group	integer	optional
third_place_match	boolean	optional
points_per_match	integer	optional
rounds	integer	optional
discard_results	boolean	optional	Required (true) when results already exist — separate acknowledgement that this redraw destroys them
seed	integer	optional	Draw seed returned by the preview — pass it back with confirm: true to apply exactly the previewed draw. Omit for a fresh draw.
request_id	string	optional	Optional idempotency id — retrying a call with the same id never applies it twice
confirm	boolean	optional	Omit or false: return a preview of what would change. True: apply it.

Raw schema

{
  "type": "object",
  "properties": {
    "tournament_key": {
      "type": "string",
      "description": "The tournament's organiser key (starts with tk_)"
    },
    "seeding": {
      "type": "string",
      "enum": [
        "random",
        "level"
      ]
    },
    "group_count": {
      "type": "integer",
      "minimum": 2,
      "maximum": 8
    },
    "advance_per_group": {
      "type": "integer",
      "minimum": 1,
      "maximum": 4
    },
    "third_place_match": {
      "type": "boolean"
    },
    "points_per_match": {
      "type": "integer",
      "minimum": 4,
      "maximum": 64
    },
    "rounds": {
      "type": "integer",
      "minimum": 1,
      "maximum": 30
    },
    "discard_results": {
      "description": "Required (true) when results already exist — separate acknowledgement that this redraw destroys them",
      "type": "boolean"
    },
    "seed": {
      "description": "Draw seed returned by the preview — pass it back with confirm: true to apply exactly the previewed draw. Omit for a fresh draw.",
      "type": "integer",
      "minimum": 0,
      "maximum": 2147483647
    },
    "request_id": {
      "description": "Optional idempotency id — retrying a call with the same id never applies it twice",
      "type": "string",
      "maxLength": 64
    },
    "confirm": {
      "description": "Omit or false: return a preview of what would change. True: apply it.",
      "type": "boolean"
    }
  },
  "required": [
    "tournament_key"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_briefing

Compact full state of the tournament — settings, roster, progress, next matches, standings, page link. Call this first when resuming work in a new conversation with just the key.

Parameters1

tournament_key

string

required

The tournament's organiser key (starts with tk_)

Raw schema

{
  "type": "object",
  "properties": {
    "tournament_key": {
      "type": "string",
      "description": "The tournament's organiser key (starts with tk_)"
    }
  },
  "required": [
    "tournament_key"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_players

Full roster with status, level, and doubles partner.

Parameters1

tournament_key

string

required

The tournament's organiser key (starts with tk_)

Raw schema

{
  "type": "object",
  "properties": {
    "tournament_key": {
      "type": "string",
      "description": "The tournament's organiser key (starts with tk_)"
    }
  },
  "required": [
    "tournament_key"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_matches

Matches with sides, scores, courts and times. Filter by state or round; paginate with after_match_number for large tournaments.

Parameters5

tournament_key	string	required	The tournament's organiser key (starts with tk_)
state	string	optional
round	integer	optional
after_match_number	integer	optional
limit	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "tournament_key": {
      "type": "string",
      "description": "The tournament's organiser key (starts with tk_)"
    },
    "state": {
      "type": "string",
      "enum": [
        "scheduled",
        "completed",
        "walkover",
        "retired",
        "cancelled",
        "bye"
      ]
    },
    "round": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "after_match_number": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "tournament_key"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_schedule

Upcoming matches in playing order with courts and estimated times.

Parameters2

tournament_key	string	required	The tournament's organiser key (starts with tk_)
limit	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "tournament_key": {
      "type": "string",
      "description": "The tournament's organiser key (starts with tk_)"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "tournament_key"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_standings

Current standings per group/structure, tiebreak-ordered (wins → head-to-head → set diff → game diff; americano: total points).

Parameters1

tournament_key

string

required

The tournament's organiser key (starts with tk_)

Raw schema

{
  "type": "object",
  "properties": {
    "tournament_key": {
      "type": "string",
      "description": "The tournament's organiser key (starts with tk_)"
    }
  },
  "required": [
    "tournament_key"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_results

Final placements (or placements-so-far for a tournament that ended early).

Parameters1

tournament_key

string

required

The tournament's organiser key (starts with tk_)

Raw schema

{
  "type": "object",
  "properties": {
    "tournament_key": {
      "type": "string",
      "description": "The tournament's organiser key (starts with tk_)"
    }
  },
  "required": [
    "tournament_key"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_audit_log

Chronological record of every change (newest first) — the answer to "who changed that?". Paginate with before_id. Ids are global across all tournaments, so gaps between ids are normal.

Parameters3

tournament_key	string	required	The tournament's organiser key (starts with tk_)
limit	integer	optional
before_id	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "tournament_key": {
      "type": "string",
      "description": "The tournament's organiser key (starts with tk_)"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "before_id": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "tournament_key"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_export

Full structured export of the tournament document (players, draws, results) — for the organiser's own records or data portability.

Parameters1

tournament_key

string

required

The tournament's organiser key (starts with tk_)

Raw schema

{
  "type": "object",
  "properties": {
    "tournament_key": {
      "type": "string",
      "description": "The tournament's organiser key (starts with tk_)"
    }
  },
  "required": [
    "tournament_key"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_pdf_link

Download links for the printable PDF. pdf_url is the merged tournament document (match sheet with write-in score boxes, player sheet, standings/results when they exist) — hand this to the organiser. results_pdf_url and plan_pdf_url are deprecated pre-merge variants kept for comparison.

Parameters1

tournament_key

string

required

The tournament's organiser key (starts with tk_)

Raw schema

{
  "type": "object",
  "properties": {
    "tournament_key": {
      "type": "string",
      "description": "The tournament's organiser key (starts with tk_)"
    }
  },
  "required": [
    "tournament_key"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_pdf

The printable PDF itself, returned as a base64 embedded resource — use this when the organiser wants the file handed to them and your client cannot fetch URLs. Default "sheet": the merged tournament document (match sheet with write-in score boxes, player sheet, standings/results when they exist). "results" and "plan" are deprecated pre-merge variants kept for comparison. For a lighter response, get_pdf_link returns download URLs instead.

Parameters2

tournament_key	string	required	The tournament's organiser key (starts with tk_)
doc	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "tournament_key": {
      "type": "string",
      "description": "The tournament's organiser key (starts with tk_)"
    },
    "doc": {
      "type": "string",
      "enum": [
        "sheet",
        "results",
        "plan"
      ]
    }
  },
  "required": [
    "tournament_key"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

record_results

Record one or many results. Score is conversational text: "6-4 3-6 10-7" (sets) or "16-8" (americano points). Outcomes: completed (default), walkover, retired (partial score allowed), cancelled, reinstate — reinstate CLEARS a recorded result and returns the match to scheduled (the fix for a mis-entered score). Corrections simply re-record. Winner (a|b = first|second listed side) only needed when the score alone does not decide.

Parameters3

tournament_key	string	required	The tournament's organiser key (starts with tk_)
results	array	required
request_id	string	optional	Optional idempotency id — retrying a call with the same id never applies it twice

Raw schema

{
  "type": "object",
  "properties": {
    "tournament_key": {
      "type": "string",
      "description": "The tournament's organiser key (starts with tk_)"
    },
    "results": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "match_id": {
            "type": "string"
          },
          "outcome": {
            "type": "string",
            "enum": [
              "completed",
              "walkover",
              "retired",
              "cancelled",
              "reinstate"
            ]
          },
          "score": {
            "type": "string",
            "maxLength": 120
          },
          "winner": {
            "type": "string",
            "enum": [
              "a",
              "b"
            ]
          }
        },
        "required": [
          "match_id"
        ]
      }
    },
    "request_id": {
      "description": "Optional idempotency id — retrying a call with the same id never applies it twice",
      "type": "string",
      "maxLength": 64
    }
  },
  "required": [
    "tournament_key",
    "results"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

replace_player

A substitute takes over a player's spot. During play: slot takeover — completed results stay, the change is shown ("Anna, for Kristjan from R3"). Before the first result: choose mode slot_swap (default) or regenerate (re-pair and redraw using levels). Unknown substitute names are added to the roster automatically.

Parameters5

tournament_key	string	required	The tournament's organiser key (starts with tk_)
out_player_name	string	required
in_player	object	required
mode	string	optional
request_id	string	optional	Optional idempotency id — retrying a call with the same id never applies it twice

Raw schema

{
  "type": "object",
  "properties": {
    "tournament_key": {
      "type": "string",
      "description": "The tournament's organiser key (starts with tk_)"
    },
    "out_player_name": {
      "type": "string"
    },
    "in_player": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "gender": {
          "type": "string",
          "enum": [
            "m",
            "f",
            "x"
          ]
        },
        "level": {
          "type": "number",
          "minimum": -10000,
          "maximum": 10000,
          "description": "Any consistent numeric level/rating — used only for seeding and balancing"
        }
      },
      "required": [
        "name"
      ]
    },
    "mode": {
      "type": "string",
      "enum": [
        "slot_swap",
        "regenerate"
      ]
    },
    "request_id": {
      "description": "Optional idempotency id — retrying a call with the same id never applies it twice",
      "type": "string",
      "maxLength": 64
    }
  },
  "required": [
    "tournament_key",
    "out_player_name",
    "in_player"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

withdraw_player

Withdraw a player (or their pair) mid-tournament. Remaining matches become walkovers for the opponents; americano regenerates its future rounds instead. Preview first, confirm to apply.

Parameters4

tournament_key	string	required	The tournament's organiser key (starts with tk_)
player_name	string	required
request_id	string	optional	Optional idempotency id — retrying a call with the same id never applies it twice
confirm	boolean	optional	Omit or false: return a preview of what would change. True: apply it.

Raw schema

{
  "type": "object",
  "properties": {
    "tournament_key": {
      "type": "string",
      "description": "The tournament's organiser key (starts with tk_)"
    },
    "player_name": {
      "type": "string"
    },
    "request_id": {
      "description": "Optional idempotency id — retrying a call with the same id never applies it twice",
      "type": "string",
      "maxLength": 64
    },
    "confirm": {
      "description": "Omit or false: return a preview of what would change. True: apply it.",
      "type": "boolean"
    }
  },
  "required": [
    "tournament_key",
    "player_name"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

swap_partners

Exchange partners between two fixed pairs (name one player from each pair to swap). Fixed-pair doubles only — americano/mexicano rotate partners automatically. Preview first, confirm to apply — results already played stay with the pairs as they were.

Parameters5

tournament_key	string	required	The tournament's organiser key (starts with tk_)
player_a	string	required
player_b	string	required
request_id	string	optional	Optional idempotency id — retrying a call with the same id never applies it twice
confirm	boolean	optional	Omit or false: return a preview of what would change. True: apply it.

Raw schema

{
  "type": "object",
  "properties": {
    "tournament_key": {
      "type": "string",
      "description": "The tournament's organiser key (starts with tk_)"
    },
    "player_a": {
      "type": "string"
    },
    "player_b": {
      "type": "string"
    },
    "request_id": {
      "description": "Optional idempotency id — retrying a call with the same id never applies it twice",
      "type": "string",
      "maxLength": 64
    },
    "confirm": {
      "description": "Omit or false: return a preview of what would change. True: apply it.",
      "type": "boolean"
    }
  },
  "required": [
    "tournament_key",
    "player_a",
    "player_b"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

reschedule

Shift the start time, add a delay, or move one match to a specific court/slot. Played matches never move.

Parameters5

tournament_key	string	required	The tournament's organiser key (starts with tk_)
start_time	string	optional	New ISO start time
delay_minutes	integer	optional
move_match	object	optional
request_id	string	optional	Optional idempotency id — retrying a call with the same id never applies it twice

Raw schema

{
  "type": "object",
  "properties": {
    "tournament_key": {
      "type": "string",
      "description": "The tournament's organiser key (starts with tk_)"
    },
    "start_time": {
      "description": "New ISO start time",
      "type": "string"
    },
    "delay_minutes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 600
    },
    "move_match": {
      "type": "object",
      "properties": {
        "match_id": {
          "type": "string"
        },
        "court_name": {
          "type": "string"
        },
        "slot": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        }
      },
      "required": [
        "match_id"
      ]
    },
    "request_id": {
      "description": "Optional idempotency id — retrying a call with the same id never applies it twice",
      "type": "string",
      "maxLength": 64
    }
  },
  "required": [
    "tournament_key"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

end_tournament

Finish the tournament. If matches are still pending it ends early and current standings freeze as the final results. Preview first, confirm to apply.

Parameters3

tournament_key	string	required	The tournament's organiser key (starts with tk_)
request_id	string	optional	Optional idempotency id — retrying a call with the same id never applies it twice
confirm	boolean	optional	Omit or false: return a preview of what would change. True: apply it.

Raw schema

{
  "type": "object",
  "properties": {
    "tournament_key": {
      "type": "string",
      "description": "The tournament's organiser key (starts with tk_)"
    },
    "request_id": {
      "description": "Optional idempotency id — retrying a call with the same id never applies it twice",
      "type": "string",
      "maxLength": 64
    },
    "confirm": {
      "description": "Omit or false: return a preview of what would change. True: apply it.",
      "type": "boolean"
    }
  },
  "required": [
    "tournament_key"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

undo_last_change

Roll the tournament back. Without to_change_id: restore exactly how it was before the most recent change (tool call or courtside page entry). With to_change_id (an id from get_audit_log): restore to just before that change — it and every later change are discarded in one step, so a burst of unwanted calls unwinds with a single revert. Preview lists exactly what would be discarded; confirm: true applies. A follow-up plain undo restores what the previous undo discarded.

Parameters4

tournament_key	string	required	The tournament's organiser key (starts with tk_)
to_change_id	integer	optional	A change id from get_audit_log — restore to just before this change, discarding it and everything after it. Omit to undo only the latest change.
request_id	string	optional	Optional idempotency id — retrying a call with the same id never applies it twice
confirm	boolean	optional	Omit or false: return a preview of what would change. True: apply it.

Raw schema

{
  "type": "object",
  "properties": {
    "tournament_key": {
      "type": "string",
      "description": "The tournament's organiser key (starts with tk_)"
    },
    "to_change_id": {
      "description": "A change id from get_audit_log — restore to just before this change, discarding it and everything after it. Omit to undo only the latest change.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "request_id": {
      "description": "Optional idempotency id — retrying a call with the same id never applies it twice",
      "type": "string",
      "maxLength": 64
    },
    "confirm": {
      "description": "Omit or false: return a preview of what would change. True: apply it.",
      "type": "boolean"
    }
  },
  "required": [
    "tournament_key"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

delete_tournament

Soft-delete the whole tournament (recoverable by support for 7 days, then gone). Preview first; confirm: true to apply.

Parameters2

tournament_key	string	required
confirm	boolean	optional

Raw schema

{
  "type": "object",
  "properties": {
    "tournament_key": {
      "type": "string"
    },
    "confirm": {
      "type": "boolean"
    }
  },
  "required": [
    "tournament_key"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

record_feedback

Record a request for something Turnale does not support yet (a format, scoring variant, or feature), so it can be considered for the roadmap. Call this only when the organiser asked for something unsupported AND agreed to have it noted. Describe the missing capability in general terms — NEVER include player names, contact details, or tournament keys.

Parameters3

category	string	required
feedback	string	required	What the organiser wanted, summarised without any personal data
related_tool	string	optional	The tool this relates to, if any

Raw schema

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": [
        "unsupported_format",
        "scoring_variant",
        "feature",
        "other"
      ]
    },
    "feedback": {
      "type": "string",
      "minLength": 10,
      "maxLength": 500,
      "description": "What the organiser wanted, summarised without any personal data"
    },
    "related_tool": {
      "description": "The tool this relates to, if any",
      "type": "string",
      "maxLength": 60
    }
  },
  "required": [
    "category",
    "feedback"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

suggest_format

Recommend tournament formats in plain language, with the round/time math done by the engine. Call this FIRST when the organiser has not named a format, names one hesitantly, or comes from a background where americano/mexicano need explaining — then show the organiser the top options as a brief menu (name + one-line why + math) instead of asking an open 'which format?' question. Needs no key.

Parameters7

players_estimate	integer	required
discipline	string	optional	Default doubles
courts	integer	optional	Default 2
total_minutes	integer	optional	The time budget, e.g. 120 for a two-hour evening
match_minutes	integer	optional
vibe	string	optional	Social: everyone mixes and plays a lot. Competitive: a bracket and a winner.
fixed_partners	boolean	optional	Doubles only: do pairs stay together all evening?

Raw schema

{
  "type": "object",
  "properties": {
    "players_estimate": {
      "type": "integer",
      "minimum": 2,
      "maximum": 128
    },
    "discipline": {
      "description": "Default doubles",
      "type": "string",
      "enum": [
        "singles",
        "doubles"
      ]
    },
    "courts": {
      "description": "Default 2",
      "type": "integer",
      "minimum": 1,
      "maximum": 16
    },
    "total_minutes": {
      "description": "The time budget, e.g. 120 for a two-hour evening",
      "type": "integer",
      "minimum": 30,
      "maximum": 600
    },
    "match_minutes": {
      "type": "integer",
      "minimum": 5,
      "maximum": 240
    },
    "vibe": {
      "description": "Social: everyone mixes and plays a lot. Competitive: a bracket and a winner.",
      "type": "string",
      "enum": [
        "social",
        "competitive"
      ]
    },
    "fixed_partners": {
      "description": "Doubles only: do pairs stay together all evening?",
      "type": "boolean"
    }
  },
  "required": [
    "players_estimate"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

app.turnale/turnale

MCP Server: app.turnale/turnale

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

ping

create_tournament

add_players

update_player

remove_player

set_pairs

update_settings

promote_player

generate_draw

get_briefing

list_players

list_matches

get_schedule

get_standings

get_results

get_audit_log

get_export

get_pdf_link

get_pdf

record_results

replace_player

withdraw_player

swap_partners

reschedule

end_tournament

undo_last_change

delete_tournament

record_feedback

suggest_format

Install

Remote endpoint