Solo-play gamebook engine: AI narrator over an MCP server (Phase 1 MVP). Engine tools for a solo-play gamebook. The narrator must route every dice roll, luck test, and state change through these tools and never invent numbers in prose.
Gamebook demonstrates solid tool design with clear naming (verb_noun pattern), comprehensive descriptions (avg 150 chars), and complete JSON Schema definitions for all 18 tools. All parameters are typed and described. However, output schemas are not formally documented in the tool definitions themselves, they rely on Pydantic model annotations in the domain layer. Error handling is present but minimal; most tools lack recovery guidance. No tool annotations (readOnlyHint/destructiveHint) despite clear risk classifications in the metadata. Composition is excellent: tools chain well (e.g., create_character → read_character_sheet → update_character_sheet), and state mutations are properly gated through dedicated update tools.
Move a final-state character to the graveyard (death) or hall of fame (victory).
Roll a new hero's attributes and persist a living character sheet.
Conclude the combat, finalise the sheet, and remove the in-progress record.
Flee the combat (only if allowed), taking 2 damage; ends with no winner.
Restore the full current state from a named save slot.
Return the hero's full character sheet.
Return the full chronicle of events, in order.
Output schemas not formally documented in tool definitions. Return types are inferred from Pydantic model annotations (CharacterSheet, World, DiceResult, etc.) but not explicitly declared in the @server.tool() decorator or schema parameter. LLMs cannot see what fields to expect without inspecting domain models.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk classifications in metadata. Tools like archive_character (IRREVERSIBLE), test_luck (WRITE), and save_game (WRITE) should declare their side effects explicitly so LLMs understand retry safety and confirmation requirements.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 62 | 2026-07-28+ | v2 |
Return the running narrative summary.
Return the current world state.
Append a hard fact to the chronicle, stamped with the current turn.
Resolve one combat round: roll attack strengths, apply damage, persist state.
Roll a dice expression like '2d6' or '1d6+6'.
Snapshot the full current state under a named save slot.
Start a fight against one or more living enemies.
Test the hero's luck (2d6 <= current luck); always spends one luck.
Patch the character sheet. Scalars/lists are replaced; attribute sub-dicts (skill/stamina/luck) are merged. Invariants are validated; on error the state is left unchanged.
Replace the running narrative summary.
Patch the world. Scalars/lists (current_location, visited_locations, known_npcs, turn) are replaced; 'flags' is merged key-wise so one flag can be set without dropping others. Invariants are validated; on error the state is left unchanged. Sole legal path to set the victory flag and advance the turn counter.
Error handling lacks recovery guidance. Tools raise ValueError with messages like 'no character sheet exists yet; create one first' and 'unknown character field(s)' but do not suggest next steps or categorize errors as retryable vs user-fixable. LLMs cannot plan recovery without explicit guidance.
Descriptions for read_* tools are generic and lack context about when to call them. 'Return the hero's full character sheet' does not explain that this should be called before narrating a session or after state changes. Descriptions should guide LLM decision-making about tool selection.
No pagination or result limits documented for read_events. If a chronicle grows large, returning all events could exhaust context. Tool should accept optional limit/offset parameters and document max result size.