An MCP server that lets AI agents play NetHack via a small action DSL
nethack-mcp has well-structured tool definitions with complete input schemas and clear descriptions. All 8 tools are explicitly registered with schemars-derived JSON schemas. Descriptions are detailed (100-300 chars) and explain WHAT, WHEN, and HOW. However, parameter descriptions are inconsistent, some params lack guidance on valid ranges or formats. Output schemas are fully typed and documented. Error handling is present but generic (ok/error fields without recovery guidance). No tool annotations (readOnlyHint/destructiveHint) despite clear risk levels. Naming is verb-forward and clear. Composition is sound, each tool has one responsibility.
Return the DSL cheat sheet.
Run a chunk of NetHack actions written in the action DSL and return the resulting game state. Actions are separated by `;` or newlines. Quoted strings may contain semicolons. IMPORTANT: `move <dir> [n]` means WALK that many single-tile steps in the given compass direction (default 1) — it is NOT a path-to-destination command. The hero steps one tile at a time and will stop early if blocked. Example: `move n; move n; wait 3; wield a; quaff b; fight e; descend`.
Open the inventory menu and return its text.
Full ASCII screen (for when the nearby window isn't enough).
Snapshot the current LLM-friendly game state.
Interactively select a character (role, race, gender, alignment) from the NetHack character creation menu.
Missing tool annotations (readOnlyHint, destructiveHint). Tools like start_game, execute_actions, send_keys, and pick_character are clearly destructive/write operations, but lack explicit annotations. This forces LLMs to infer risk from descriptions alone.
Parameter descriptions lack constraint guidance. 'settle_ms' and 'max_chunk' in start_game have no min/max bounds. 'cols' and 'rows' lack valid ranges. LLMs may pass absurd values (e.g. cols=999999) without validation hints.
Error responses are generic (ok: bool, error: Option<String>). No recovery guidance. When execute_actions fails, the LLM gets 'error: "parse failed"' with no hint on what to try next. Should include actionable recovery steps.
Inferred effective spec: 2025-06-18+.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 57 | 2025-06-18+ | v2 |
Escape hatch — send raw keystrokes.
(Re)launch the NetHack process with a fresh PTY session. Use this at the very start, or to restart after death/quit. Any previous session is killed first. The `mirror` path, if set, receives a live copy of the raw NetHack terminal stream so a human can `tail -f` it and watch the game.
Descriptions for get_map, get_state, get_inventory are terse (60-70 chars). They state WHAT but not WHEN to use or how they differ from each other. LLMs may conflate get_state vs get_map.
dsl_reference has minimal description ("Return the DSL cheat sheet."). No guidance on when to call it or what it contains. Should explain it's a discovery tool for action syntax.