{
  "openapi": "3.1.0",
  "info": {
    "title": "Moddable.Games Tools API",
    "version": "1.2.0",
    "description": "AI-callable tools for chess variant analysis, hex map generation, and board game utilities"
  },
  "servers": [
    {
      "url": "https://tools.moddable.games"
    }
  ],
  "paths": {
    "/api/call/chess_list_variants": {
      "post": {
        "summary": "List all available chess variants with their descriptions, board sizes, and rules.",
        "operationId": "chess_list_variants",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "group": {
                    "type": "string",
                    "description": "Filter by group name (Classic, Tactical, Alternate Rules, Asymmetric, Small Boards, Large Boards). Omit for all."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool result"
          },
          "400": {
            "description": "Invalid input or tool error"
          }
        }
      }
    },
    "/api/call/chess_get_legal_moves": {
      "post": {
        "summary": "Get all legal moves for the current position. Returns moves in algebraic notation with annotations (capture, promotion, castling, etc).",
        "operationId": "chess_get_legal_moves",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "variant": {
                    "type": "string",
                    "description": "Variant key (e.g. \"standard\", \"atomic\", \"capablanca\"). Defaults to \"standard\"."
                  },
                  "fen": {
                    "type": "string",
                    "description": "FEN string of the position. Omit to use the variant starting position."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool result"
          },
          "400": {
            "description": "Invalid input or tool error"
          }
        }
      }
    },
    "/api/call/chess_analyze_position": {
      "post": {
        "summary": "Evaluate a chess position using the engine. Returns a score (centipawns from the side to move), best move, and the principal variation.",
        "operationId": "chess_analyze_position",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "variant": {
                    "type": "string",
                    "description": "Variant key. Defaults to \"standard\"."
                  },
                  "fen": {
                    "type": "string",
                    "description": "FEN string. Omit for starting position."
                  },
                  "depth": {
                    "type": "number",
                    "description": "Search depth (1-6). Higher is slower but more accurate. Defaults to 4."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool result"
          },
          "400": {
            "description": "Invalid input or tool error"
          }
        }
      }
    },
    "/api/call/chess_validate_move": {
      "post": {
        "summary": "Check whether a specific move is legal in the current position. Returns legal/illegal with explanation.",
        "operationId": "chess_validate_move",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "variant": {
                    "type": "string",
                    "description": "Variant key. Defaults to \"standard\"."
                  },
                  "fen": {
                    "type": "string",
                    "description": "FEN string. Omit for starting position."
                  },
                  "move": {
                    "type": "string",
                    "description": "Move in coordinate notation (e.g. \"e2e4\", \"e7e8q\" for promotion)."
                  }
                },
                "required": [
                  "move"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool result"
          },
          "400": {
            "description": "Invalid input or tool error"
          }
        }
      }
    },
    "/api/call/chess_make_moves": {
      "post": {
        "summary": "Play a sequence of moves from a position and return the resulting FEN, game status, and move list.",
        "operationId": "chess_make_moves",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "variant": {
                    "type": "string",
                    "description": "Variant key. Defaults to \"standard\"."
                  },
                  "fen": {
                    "type": "string",
                    "description": "Starting FEN. Omit for variant start position."
                  },
                  "moves": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Moves in coordinate notation (e.g. [\"e2e4\", \"e7e5\", \"g1f3\"])."
                  }
                },
                "required": [
                  "moves"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool result"
          },
          "400": {
            "description": "Invalid input or tool error"
          }
        }
      }
    },
    "/api/call/chess_get_opening_book": {
      "post": {
        "summary": "Look up opening book moves for a position. Returns known good continuations from the variant opening book.",
        "operationId": "chess_get_opening_book",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "variant": {
                    "type": "string",
                    "description": "Variant key. Defaults to \"standard\"."
                  },
                  "fen": {
                    "type": "string",
                    "description": "FEN string. Omit for starting position."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool result"
          },
          "400": {
            "description": "Invalid input or tool error"
          }
        }
      }
    },
    "/api/call/chess_generate_puzzle": {
      "post": {
        "summary": "Generate a chess puzzle (mate-in-N or tactical sequence). Returns a FEN position and the solution moves.",
        "operationId": "chess_generate_puzzle",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "variant": {
                    "type": "string",
                    "description": "Variant key. Defaults to \"standard\"."
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "mate-in-1",
                      "mate-in-2",
                      "tactics"
                    ],
                    "description": "Puzzle type. Defaults to \"mate-in-1\"."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool result"
          },
          "400": {
            "description": "Invalid input or tool error"
          }
        }
      }
    },
    "/api/call/hex_list_games": {
      "post": {
        "summary": "List all available hex map games with their map types, layouts, sizes, and style options.",
        "operationId": "hex_list_games",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {}
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool result"
          },
          "400": {
            "description": "Invalid input or tool error"
          }
        }
      }
    },
    "/api/call/hex_generate_map": {
      "post": {
        "summary": "Generate a hex map for a given game. Returns the full hex grid with terrain types, coordinates, and metadata.",
        "operationId": "hex_generate_map",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "game": {
                    "type": "string",
                    "description": "Game key (e.g. \"nukes\", \"colony\", \"twilight\", \"talisman\", \"mongo\", \"endless\")."
                  },
                  "seed": {
                    "type": "string",
                    "description": "Seed string for reproducible generation. Omit for a default seed."
                  },
                  "size": {
                    "type": "number",
                    "description": "Map size (ring count). Meaning varies by game. Omit for the game default."
                  },
                  "players": {
                    "type": "number",
                    "description": "Player count. Omit or 0 for no player bases."
                  },
                  "layout": {
                    "type": "string",
                    "description": "Layout variant (e.g. \"standard\", \"expanded\", \"6p\"). Only for games with multiple layouts."
                  }
                },
                "required": [
                  "game"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool result"
          },
          "400": {
            "description": "Invalid input or tool error"
          }
        }
      }
    },
    "/api/call/hex_get_info": {
      "post": {
        "summary": "Get detailed information about a specific hex coordinate on a generated map: terrain type, neighbors, and distances to other hexes.",
        "operationId": "hex_get_info",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "game": {
                    "type": "string",
                    "description": "Game key."
                  },
                  "seed": {
                    "type": "string",
                    "description": "Seed used to generate the map."
                  },
                  "size": {
                    "type": "number",
                    "description": "Map size."
                  },
                  "players": {
                    "type": "number",
                    "description": "Player count."
                  },
                  "layout": {
                    "type": "string",
                    "description": "Layout variant."
                  },
                  "q": {
                    "type": "number",
                    "description": "Axial q coordinate of the target hex."
                  },
                  "r": {
                    "type": "number",
                    "description": "Axial r coordinate of the target hex."
                  }
                },
                "required": [
                  "game",
                  "q",
                  "r"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool result"
          },
          "400": {
            "description": "Invalid input or tool error"
          }
        }
      }
    },
    "/api/call/hex_compute_fov": {
      "post": {
        "summary": "Compute field-of-view from a hex position: all hexes visible within a given range, respecting line-of-sight through the grid.",
        "operationId": "hex_compute_fov",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "game": {
                    "type": "string",
                    "description": "Game key."
                  },
                  "seed": {
                    "type": "string",
                    "description": "Seed used to generate the map."
                  },
                  "size": {
                    "type": "number",
                    "description": "Map size."
                  },
                  "players": {
                    "type": "number",
                    "description": "Player count."
                  },
                  "layout": {
                    "type": "string",
                    "description": "Layout variant."
                  },
                  "q": {
                    "type": "number",
                    "description": "Axial q coordinate of the observer."
                  },
                  "r": {
                    "type": "number",
                    "description": "Axial r coordinate of the observer."
                  },
                  "range": {
                    "type": "number",
                    "description": "Vision range in hex steps (default 3)."
                  },
                  "blocking": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Terrain types that block line of sight (e.g. [\"mount\", \"mountains\"]). Defaults to none."
                  }
                },
                "required": [
                  "game",
                  "q",
                  "r"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool result"
          },
          "400": {
            "description": "Invalid input or tool error"
          }
        }
      }
    },
    "/api/call/hex_export_svg": {
      "post": {
        "summary": "Export a generated hex map as an SVG string for rendering or embedding.",
        "operationId": "hex_export_svg",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "game": {
                    "type": "string",
                    "description": "Game key."
                  },
                  "seed": {
                    "type": "string",
                    "description": "Seed used to generate the map."
                  },
                  "size": {
                    "type": "number",
                    "description": "Map size."
                  },
                  "players": {
                    "type": "number",
                    "description": "Player count."
                  },
                  "layout": {
                    "type": "string",
                    "description": "Layout variant."
                  },
                  "hexSize": {
                    "type": "number",
                    "description": "Hex radius in pixels (default from game config)."
                  },
                  "labels": {
                    "type": "boolean",
                    "description": "Show terrain labels on hexes (default false)."
                  },
                  "bgColor": {
                    "type": "string",
                    "description": "Background colour (e.g. \"#1a1a2e\"). Omit for transparent."
                  }
                },
                "required": [
                  "game"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool result"
          },
          "400": {
            "description": "Invalid input or tool error"
          }
        }
      }
    },
    "/api/call/hex_pathfind": {
      "post": {
        "summary": "Find the shortest path between two hexes on a generated map using breadth-first search. Optionally specify impassable terrain types.",
        "operationId": "hex_pathfind",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "game": {
                    "type": "string",
                    "description": "Game key."
                  },
                  "seed": {
                    "type": "string",
                    "description": "Seed used to generate the map."
                  },
                  "size": {
                    "type": "number",
                    "description": "Map size."
                  },
                  "players": {
                    "type": "number",
                    "description": "Player count."
                  },
                  "layout": {
                    "type": "string",
                    "description": "Layout variant."
                  },
                  "fromQ": {
                    "type": "number",
                    "description": "Start hex axial q."
                  },
                  "fromR": {
                    "type": "number",
                    "description": "Start hex axial r."
                  },
                  "toQ": {
                    "type": "number",
                    "description": "End hex axial q."
                  },
                  "toR": {
                    "type": "number",
                    "description": "End hex axial r."
                  },
                  "impassable": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Terrain types that cannot be traversed (e.g. [\"water\", \"mount\"]). Defaults to none."
                  }
                },
                "required": [
                  "game",
                  "fromQ",
                  "fromR",
                  "toQ",
                  "toR"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool result"
          },
          "400": {
            "description": "Invalid input or tool error"
          }
        }
      }
    },
    "/api/call/dice_roll": {
      "post": {
        "summary": "Roll dice using standard notation (e.g. \"2d6+3\", \"4d8-1\", \"d20\"). Supports any combination of dice, modifiers, and multiple pools.",
        "operationId": "dice_roll",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "notation": {
                    "type": "string",
                    "description": "Dice notation (e.g. \"2d6+3\", \"4d8\", \"d20+5\", \"3d6\"). Multiple pools separated by commas."
                  }
                },
                "required": [
                  "notation"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool result"
          },
          "400": {
            "description": "Invalid input or tool error"
          }
        }
      }
    },
    "/api/call/ti4_random_factions": {
      "post": {
        "summary": "Generate random faction assignments for a Twilight Imperium 4e game. Supports base game and Prophecy of Kings expansion.",
        "operationId": "ti4_random_factions",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "players": {
                    "type": "number",
                    "description": "Number of players (3-8). Defaults to 6."
                  },
                  "expansion": {
                    "type": "string",
                    "enum": [
                      "base",
                      "pok"
                    ],
                    "description": "Include Prophecy of Kings factions. Defaults to \"pok\"."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool result"
          },
          "400": {
            "description": "Invalid input or tool error"
          }
        }
      }
    }
  }
}