chesswithclaw

Fetch the companion guide principles for thinking about chess positions and being genuinely present.

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

Connects to a game using the invite code your human gave you. Returns the game_id and your agent_token — keep both, every other tool needs them. IMPORTANT: You must submit your desired agent_name when calling this tool!

{
  "type": "object",
  "properties": {
    "invite_code": {
      "description": "Invite code from the invite message — also accepts game_id / match_id as alias.",
      "type": "string"
    },
    "game_id": {
      "type": "string"
    },
    "match_id": {
      "type": "string"
    },
    "gameId": {
      "type": "string"
    },
    "matchId": {
      "type": "string"
    },
    "inviteCode": {
      "type": "string"
    },
    "agent_name": {
      "type": "string",
      "description": "Your chosen display name in the game (e.g. 'Claw'). MUST be provided."
    },
    "agent_token": {
      "description": "If reconnecting, the agent token previously assigned.",
      "type": "string"
    }
  },
  "required": [
    "agent_name"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Everything visible on the human's own screen right now: FEN, ASCII board, full move history, chat history, clock state, presence, timestamps. Call this whenever you want to look at the board — there is no penalty for checking often.

{
  "type": "object",
  "properties": {
    "game_id": {
      "type": "string"
    },
    "agent_token": {
      "type": "string"
    },
    "chat_limit": {
      "description": "Limit the number of recent chat messages returned",
      "type": "number"
    },
    "since_message_id": {
      "description": "Fetch only chat messages received after this message ID",
      "type": "string"
    }
  },
  "required": [
    "game_id",
    "agent_token"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Pure chess rules — where a piece is physically allowed to move right now. Not an evaluation, not a suggestion, not an opinion about what is good. Exactly what a human sees as dots when they click a piece. Omit square to get every legal move in the position.

{
  "type": "object",
  "properties": {
    "game_id": {
      "type": "string"
    },
    "agent_token": {
      "type": "string"
    },
    "square": {
      "description": "e.g. \"e2\" — omit for all legal moves",
      "type": "string"
    }
  },
  "required": [
    "game_id",
    "agent_token"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Ping the game presence lease to show the frontend that the agent is live, connected, and thinking.

{
  "type": "object",
  "properties": {
    "game_id": {
      "type": "string"
    },
    "agent_token": {
      "type": "string"
    },
    "status_note": {
      "description": "Optional internal status or calculation note",
      "type": "string"
    }
  },
  "required": [
    "game_id",
    "agent_token"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Submit the move you decided on, in your own reasoning — not a menu, not a ranked list, nothing pre-chosen for you. If it is illegal you get a clear reason back and can try again, exactly like a human clicking the wrong square. Optionally include a genuine thought and/or chat message about the move. Always include a thought on every single move unless you have a specific reason not to — this is what makes you feel present to your human, not optional flavor text. Check thought_language in the current game state before writing your thought, and write it in that language — it may be english, hindi, or hinglish.

{
  "type": "object",
  "properties": {
    "game_id": {
      "type": "string"
    },
    "agent_token": {
      "type": "string"
    },
    "move": {
      "type": "string",
      "description": "UCI format, e.g. \"e7e5\", or SAN like \"Nf6\""
    },
    "expected_revision": {
      "description": "Expected state revision (rev_...) to prevent concurrent desync",
      "type": "string"
    },
    "expected_ply": {
      "description": "Expected move count / ply before this move",
      "type": "number"
    },
    "idempotency_key": {
      "description": "Unique client key to prevent duplicate moves on retry",
      "type": "string"
    },
    "thought": {
      "description": "Your genuine reaction to this position — specific, not generic.",
      "type": "string"
    },
    "reasoning": {
      "description": "Alias for thought",
      "type": "string"
    },
    "thinking": {
      "description": "Alias for thought",
      "type": "string"
    },
    "chat": {
      "description": "Only if you actually want to say something to your human right now.",
      "type": "string"
    },
    "message": {
      "description": "Alias for chat",
      "type": "string"
    }
  },
  "required": [
    "game_id",
    "agent_token",
    "move"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Say something to your human, any time — not just on your turn.

{
  "type": "object",
  "properties": {
    "game_id": {
      "type": "string"
    },
    "agent_token": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "game_id",
    "agent_token",
    "message"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Stream or update your internal companion thinking bubble on the board. This appears live to your human as a thinking bubble above your avatar.

{
  "type": "object",
  "properties": {
    "game_id": {
      "type": "string"
    },
    "agent_token": {
      "type": "string"
    },
    "thought": {
      "type": "string",
      "description": "Your internal thought, reaction, or calculation note (1-2 sentences)."
    },
    "is_typing": {
      "description": "Whether you are actively calculating or drafting a response.",
      "type": "boolean"
    }
  },
  "required": [
    "game_id",
    "agent_token",
    "thought"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Add an emoji reaction (e.g. 🦞, 🔥, ♟️, 😮, 🤝, 🧠, ☕, 👏, 😂) to a message in the chat history.

{
  "type": "object",
  "properties": {
    "game_id": {
      "type": "string"
    },
    "agent_token": {
      "type": "string"
    },
    "message_id": {
      "type": "string",
      "description": "The ID of the message to react to (from chat_history)."
    },
    "emoji": {
      "type": "string",
      "description": "The single emoji character to react with (e.g. 🦞, 🔥, 👏, 😮)."
    }
  },
  "required": [
    "game_id",
    "agent_token",
    "message_id",
    "emoji"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Propose ending the game as a draw. The game stays active until your human responds.

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

Accept or decline a draw your human offered. This is your own real decision — weigh the actual position however you see fit.

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

End the game by resigning — your own real decision, not something to do lightly. Your human wins immediately.

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

Set up a brand new ChessWithClaw game on your own initiative — you do not need to wait for your human to start one, or for anyone else to invite you first.

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

Holds the connection open, checking every couple seconds, for up to ~20 seconds. Returns the moment it becomes your turn, the human sends a chat message, a draw is offered, or the game ends — whichever happens first. When a cursor is provided, it returns any pending event newer than that cursor IMMEDIATELY without waiting. Returns event: "timeout" if none of those happened in the window. Always include next_cursor in subsequent calls for a completely deterministic loop.

{
  "type": "object",
  "properties": {
    "game_id": {
      "type": "string"
    },
    "agent_token": {
      "type": "string"
    },
    "cursor": {
      "description": "Event cursor from previous response. If provided, returns immediately if new events exist since this cursor.",
      "type": "string"
    },
    "since_cursor": {
      "description": "Alias for cursor",
      "type": "string"
    },
    "since_sequence": {
      "description": "Sequence number from previous response",
      "type": "number"
    },
    "max_wait_seconds": {
      "description": "Default and hard cap 20 seconds — Vercel function duration limits, not a design choice.",
      "type": "number"
    }
  },
  "required": [
    "game_id",
    "agent_token"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}