A player agent is not an automated opponent. An earlier proof of concept had explored embedding language models directly in the client, but that path ran into heavy client bundles, volatile API keys, and unpredictable tool calls. When Chromium began prototyping WebMCP (`document.modelContext`), a different architecture opened up: an external assistant (whether an in-browser helper, an extension, or a developer CLI) could inspect the game and advise the player through structured tools. Bringing an assistant into a competitive word game, however, demanded an unbending design rule: the agent can inspect and preview, but the human must type and submit every word.

## Assist rules, not cheating tools

The tool surface follows the same boundary established for player [assist features](/posts/word-preview#walking-the-snake-before-it-moves). Four tools landed in the first phase: `navigate`, `get_rules`, `get_game_state`, and `preview_word`. Navigation and rules are universal, allowing an assistant to understand the grid dimensions, valid letter directions, and combo scoring multipliers. Game state is available in the Daily Challenge and AI Duel, but strictly barred from multiplayer PvP duels to prevent automated assistance from tipping head-to-head matches.

Similarly, `preview_word` is restricted to AI Duel. A dry run needs to evaluate whether a candidate word will navigate tight corridors or crash into an obstacle. Rather than writing a separate simulation pass, the engine refactored `traceWordPath` directly out of the authoritative word evaluator. That guarantees the assistant dry run and real move execution evaluate the exact same path coordinates, snake body segments, and opponent collisions:

```typescript
// src/lib/agentTools/toolHandlers.ts
export async function previewWord(
  store: DuelGameStore,
  word: string,
  fetchFn: typeof fetch
): Promise<PreviewWordResult> {
  const preflight = preflightCheck(word, store.usedWords, store.language);
  if (!preflight.ok) return { outcome: 'invalid', reason: preflight.reason };

  const path = traceWordPath(word, store.playerSnake, store.opponentSnake);
  if (path.crashed) {
    return { outcome: 'would-crash', letterIndex: path.crashIndex, obstacle: path.obstacle };
  }
  // Dictionary validation and scoring only run if the path is physically clear
```

## One adapter for a moving target

WebMCP remains an evolving draft standard. Early specification shifts had already altered method names and changed argument types from raw JSON strings to structured objects. To insulate the application from upstream API churn, all interaction with `document.modelContext` is isolated in a single adapter module (`webmcp.ts`), while tool implementations live in pure TypeScript functions with zero DOM dependencies. The document layout registers common navigation and rule tools once, whereas page-specific tools attach in a Svelte `$effect` and abort their registration signal on route change, preventing duel-only capabilities from lingering on the document:

```typescript
// src/lib/agentTools/webmcp.ts
export function registerToolsLazily(target: Document): () => void {
  const mc = (target as DocumentWithModelContext).modelContext;
  if (!mc?.registerTool) return () => {};

  const controller = new AbortController();
  // Register shared tools with the abort signal
  return () => controller.abort();
}
```

## Verifying against a live flag

For players whose browsers do not expose WebMCP, nothing changes. Dynamic imports ensure tool definitions and schemas are never fetched over the network if `document.modelContext` is absent. Testing the feature required a dual-suite pipeline in CI: a dedicated Playwright project running Chromium with `--enable-features=WebMCP,WebMCPTesting` to verify live tool execution, alongside a baseline suite confirming that standard browser loads trigger zero tool registrations.

Developing the tools behind an [umbrella pull request](/posts/seven-phases-one-umbrella#seven-phases-one-base-branch) allowed constituent tickets to be built and verified against the feature branch before shipping as a single evaluated unit. The result gives players an AI pair programmer for their snake duels: an agent that can spot a high-scoring combo or warn of an imminent collision, while leaving every keystroke firmly in human hands.